## GstUtils

GstUtils — Various utility functions

## Synopsis

    #include <gst/gst.h>

    #define             GST_BOILERPLATE_WITH_INTERFACE      (type, type_as_function,
                                                             parent_type, parent_type_as_macro, interface_type,
                                                             interface_type_as_macro, interface_as_function)
    #define             GST_BOILERPLATE_FULL                (type, type_as_function, parent_type, parent_type_macro, additional_initializations)
    #define             GST_BOILERPLATE                     (type,type_as_function,parent_type,parent_type_macro)
    #define             GST_CALL_PARENT                     (parent_class_cast, name, args)
    #define             GST_CALL_PARENT_WITH_DEFAULT        (parent_class_cast, name, args, def_return)
    #define             GST_READ_UINT8                      (data)
    #define             GST_READ_UINT16_LE                  (data)
    #define             GST_READ_UINT16_BE                  (data)
    #define             GST_READ_UINT32_LE                  (data)
    #define             GST_READ_UINT32_BE                  (data)
    #define             GST_READ_UINT64_LE                  (data)
    #define             GST_READ_UINT64_BE                  (data)
    #define             GST_WRITE_UINT8                     (data, num)
    #define             GST_WRITE_UINT16_LE                 (data, num)
    #define             GST_WRITE_UINT16_BE                 (data, num)
    #define             GST_WRITE_UINT32_LE                 (data, num)
    #define             GST_WRITE_UINT32_BE                 (data, num)
    #define             GST_WRITE_UINT64_LE                 (data, num)
    #define             GST_WRITE_UINT64_BE                 (data, num)
    #define             GST_ROUND_UP_2                      (num)
    #define             GST_ROUND_UP_4                      (num)
    #define             GST_ROUND_UP_8                      (num)
    #define             GST_ROUND_UP_16                     (num)
    #define             GST_ROUND_UP_32                     (num)
    #define             GST_ROUND_UP_64                     (num)
    #define             GST_ROUND_DOWN_2                    (num)
    #define             GST_ROUND_DOWN_4                    (num)
    #define             GST_ROUND_DOWN_8                    (num)
    #define             GST_ROUND_DOWN_16                   (num)
    #define             GST_ROUND_DOWN_32                   (num)
    #define             GST_ROUND_DOWN_64                   (num)
    void                gst_atomic_int_set                  (gint *atomic_int,
                                                             gint value);
    const gchar*        gst_flow_get_name                   (GstFlowReturn ret);
    GQuark              gst_flow_to_quark                   (GstFlowReturn ret);
    void                gst_print_element_args              (GString *buf,
                                                             gint indent,
                                                             GstElement *element);
    void                gst_print_pad_caps                  (GString *buf,
                                                             gint indent,
                                                             GstPad *pad);
    #define             gst_guint64_to_gdouble              (value)
    #define             gst_gdouble_to_guint64              (value)
    GType               gst_type_register_static_full       (GType parent_type,
                                                             const gchar *type_name,
                                                             guint class_size,
                                                             GBaseInitFunc base_init,
                                                             GBaseFinalizeFunc base_finalize,
                                                             GClassInitFunc class_init,
                                                             GClassFinalizeFunc class_finalize,
                                                             gconstpointer class_data,
                                                             guint instance_size,
                                                             guint16 n_preallocs,
                                                             GInstanceInitFunc instance_init,
                                                             const GTypeValueTable *value_table,
                                                             GTypeFlags flags);
    void                gst_util_dump_mem                   (const guchar *mem,
                                                             guint size);
    guint64             gst_util_uint64_scale               (guint64 val,
                                                             guint64 num,
                                                             guint64 denom);
    guint64             gst_util_uint64_scale_int           (guint64 val,
                                                             gint num,
                                                             gint denom);
    void                gst_util_set_object_arg             (GObject *object,
                                                             const gchar *name,
                                                             const gchar *value);
    void                gst_util_set_value_from_string      (GValue *value,
                                                             const gchar *value_str);
    GstClockTime        gst_util_get_timestamp              (void);

## Description

When defining own plugins, use the GST_BOILERPLATE ease gobject creation.

## Details

### GST_BOILERPLATE_WITH_INTERFACE()

    #define             GST_BOILERPLATE_WITH_INTERFACE(type, type_as_function,		\
                    parent_type, parent_type_as_macro, interface_type,			\
                    interface_type_as_macro, interface_as_function)

Like GST_BOILERPLATE, but makes the type 1) implement an interface, and 2) implement GstImplementsInterface for that type.

After this you will need to implement interface_as_function ## _supported and interface_as_function ## _interface_init

`type` : | the name of the type struct
`type_as_function` : | the prefix for the functions
`parent_type` : | the parent type struct name
`parent_type_as_macro` : | the parent type macro
`interface_type` : | the name of the interface type struct
`interface_type_as_macro` : | the interface type macro
`interface_as_function` : | the interface function name prefix

### GST_BOILERPLATE_FULL()

    #define             GST_BOILERPLATE_FULL(type, type_as_function, parent_type, parent_type_macro, additional_initializations)

Define the boilerplate type stuff to reduce typos and code size. Defines the get_type method and the parent_class static variable.

      GST_BOILERPLATE_FULL (GstFdSink, gst_fdsink, GstElement, GST_TYPE_ELEMENT, _do_init);

`type` : | the name of the type struct
`type_as_function` : | the prefix for the functions
`parent_type` : | the parent type struct name
`parent_type_macro` : | the parent type macro
`additional_initializations` : | function pointer in the form of void additional_initializations (GType type) that can be used for initializing interfaces and the like

### GST_BOILERPLATE()

    #define             GST_BOILERPLATE(type,type_as_function,parent_type,parent_type_macro)

Define the boilerplate type stuff to reduce typos and code size. Defines the get_type method and the parent_class static variable.

      GST_BOILERPLATE (GstFdSink, gst_fdsink, GstElement, GST_TYPE_ELEMENT);

`type` : | the name of the type struct
`type_as_function` : | the prefix for the functions
`parent_type` : | the parent type struct name
`parent_type_macro` : | the parent type macro

### GST_CALL_PARENT()

    #define             GST_CALL_PARENT(parent_class_cast, name, args)

Just call the parent handler. This assumes that there is a variable named parent_class that points to the (duh!) parent class. Note that this macro is not to be used with things that return something, use the _WITH_DEFAULT version for that

`parent_class_cast` : | the name of the class cast macro for the parent type
`name` : | name of the function to call
`args` : | arguments enclosed in '( )'

### GST_CALL_PARENT_WITH_DEFAULT()

    #define             GST_CALL_PARENT_WITH_DEFAULT(parent_class_cast, name, args, def_return)

Same as `GST_CALL_PARENT()`, but in case there is no implementation, it evaluates to `def_return`.

`parent_class_cast` : | the name of the class cast macro for the parent type
`name` : | name of the function to call
`args` : | arguments enclosed in '( )'
`def_return` : | default result

### GST_READ_UINT8()

    #define             GST_READ_UINT8(data)

Read an 8 bit unsigned integer value from the memory buffer.

`data` : | memory location

### GST_READ_UINT16_LE()

    #define             GST_READ_UINT16_LE(data)

Read a 16 bit unsigned integer value in little endian format from the memory buffer.

`data` : | memory location

### GST_READ_UINT16_BE()

    #define             GST_READ_UINT16_BE(data)

Read a 16 bit unsigned integer value in big endian format from the memory buffer.

`data` : | memory location

### GST_READ_UINT32_LE()

    #define             GST_READ_UINT32_LE(data)

Read a 32 bit unsigned integer value in little endian format from the memory buffer.

`data` : | memory location

### GST_READ_UINT32_BE()

    #define             GST_READ_UINT32_BE(data)

Read a 32 bit unsigned integer value in big endian format from the memory buffer.

`data` : | memory location

### GST_READ_UINT64_LE()

    #define             GST_READ_UINT64_LE(data)

Read a 64 bit unsigned integer value in little endian format from the memory buffer.

`data` : | memory location

### GST_READ_UINT64_BE()

    #define             GST_READ_UINT64_BE(data)

Read a 64 bit unsigned integer value in big endian format from the memory buffer.

`data` : | memory location

### GST_WRITE_UINT8()

    #define             GST_WRITE_UINT8(data, num)

Store an 8 bit unsigned integer value into the memory buffer.

`data` : | memory location
`num` : | value to store

### GST_WRITE_UINT16_LE()

    #define             GST_WRITE_UINT16_LE(data, num)

Store a 16 bit unsigned integer value in little endian format into the memory buffer.

`data` : | memory location
`num` : | value to store

### GST_WRITE_UINT16_BE()

    #define             GST_WRITE_UINT16_BE(data, num)

Store a 16 bit unsigned integer value in big endian format into the memory buffer.

`data` : | memory location
`num` : | value to store

### GST_WRITE_UINT32_LE()

    #define             GST_WRITE_UINT32_LE(data, num)

Store a 32 bit unsigned integer value in little endian format into the memory buffer.

`data` : | memory location
`num` : | value to store

### GST_WRITE_UINT32_BE()

    #define             GST_WRITE_UINT32_BE(data, num)

Store a 32 bit unsigned integer value in big endian format into the memory buffer.

`data` : | memory location
`num` : | value to store

### GST_WRITE_UINT64_LE()

    #define             GST_WRITE_UINT64_LE(data, num)

Store a 64 bit unsigned integer value in little endian format into the memory buffer.

`data` : | memory location
`num` : | value to store

### GST_WRITE_UINT64_BE()

    #define             GST_WRITE_UINT64_BE(data, num)

Store a 64 bit unsigned integer value in big endian format into the memory buffer.

`data` : | memory location
`num` : | value to store

### GST_ROUND_UP_2()

    #define GST_ROUND_UP_2(num)  (((num)+1)&~1)

Rounds an integer value up to the next multiple of 2.

`num` : | integer value to round up

### GST_ROUND_UP_4()

    #define GST_ROUND_UP_4(num)  (((num)+3)&~3)

Rounds an integer value up to the next multiple of 4.

`num` : | integer value to round up

### GST_ROUND_UP_8()

    #define GST_ROUND_UP_8(num)  (((num)+7)&~7)

Rounds an integer value up to the next multiple of 8.

`num` : | integer value to round up

### GST_ROUND_UP_16()

    #define GST_ROUND_UP_16(num) (((num)+15)&~15)

Rounds an integer value up to the next multiple of 16.

`num` : | integer value to round up

### GST_ROUND_UP_32()

    #define GST_ROUND_UP_32(num) (((num)+31)&~31)

Rounds an integer value up to the next multiple of 32.

`num` : | integer value to round up

### GST_ROUND_UP_64()

    #define GST_ROUND_UP_64(num) (((num)+63)&~63)

Rounds an integer value up to the next multiple of 64.

`num` : | integer value to round up

### GST_ROUND_DOWN_2()

    #define GST_ROUND_DOWN_2(num)  ((num)&(~1))

Rounds an integer value down to the next multiple of 2.

`num` : | integer value to round down

Since 0.10.12

### GST_ROUND_DOWN_4()

    #define GST_ROUND_DOWN_4(num)  ((num)&(~3))

Rounds an integer value down to the next multiple of 4.

`num` : | integer value to round down

Since 0.10.12

### GST_ROUND_DOWN_8()

    #define GST_ROUND_DOWN_8(num)  ((num)&(~7))

Rounds an integer value down to the next multiple of 8.

`num` : | integer value to round down

Since 0.10.12

### GST_ROUND_DOWN_16()

    #define GST_ROUND_DOWN_16(num) ((num)&(~15))

Rounds an integer value down to the next multiple of 16.

`num` : | integer value to round down

Since 0.10.12

### GST_ROUND_DOWN_32()

    #define GST_ROUND_DOWN_32(num) ((num)&(~31))

Rounds an integer value down to the next multiple of 32.

`num` : | integer value to round down

Since 0.10.12

### GST_ROUND_DOWN_64()

    #define GST_ROUND_DOWN_64(num) ((num)&(~63))

Rounds an integer value down to the next multiple of 64.

`num` : | integer value to round down

Since 0.10.12

### gst_atomic_int_set ()

    void                gst_atomic_int_set                  (gint *atomic_int,
                                                             gint value);

Unconditionally sets the atomic integer to `value`.

`atomic_int` : | pointer to an atomic integer
`value` : | value to set

### gst_flow_get_name ()

    const gchar*        gst_flow_get_name                   (GstFlowReturn ret);

Gets a string representing the given flow return.

`ret` : | a GstFlowReturn to get the name of.
Returns : | a static string with the name of the flow return.

### gst_flow_to_quark ()

    GQuark              gst_flow_to_quark                   (GstFlowReturn ret);

Get the unique quark for the given GstFlowReturn.

`ret` : | a GstFlowReturn to get the quark of.
Returns : | the quark associated with the flow return or 0 if an invalid return was specified.

### gst_print_element_args ()

    void                gst_print_element_args              (GString *buf,
                                                             gint indent,
                                                             GstElement *element);

Print the element argument in a human readable format in the given GString.

`buf` : | the buffer to print the args in
`indent` : | initial indentation
`element` : | the element to print the args of

### gst_print_pad_caps ()

    void                gst_print_pad_caps                  (GString *buf,
                                                             gint indent,
                                                             GstPad *pad);

Write the pad capabilities in a human readable format into the given GString.

`buf` : | the buffer to print the caps in
`indent` : | initial indentation
`pad` : | the pad to print the caps from

### gst_guint64_to_gdouble()

    #define             gst_guint64_to_gdouble(value)

Convert `value` to a gdouble.

`value` : | the guint64 value to convert

### gst_gdouble_to_guint64()

    #define             gst_gdouble_to_guint64(value)

Convert `value` to a guint64.

`value` : | the gdouble value to convert

### gst_type_register_static_full ()

    GType               gst_type_register_static_full       (GType parent_type,
                                                             const gchar *type_name,
                                                             guint class_size,
                                                             GBaseInitFunc base_init,
                                                             GBaseFinalizeFunc base_finalize,
                                                             GClassInitFunc class_init,
                                                             GClassFinalizeFunc class_finalize,
                                                             gconstpointer class_data,
                                                             guint instance_size,
                                                             guint16 n_preallocs,
                                                             GInstanceInitFunc instance_init,
                                                             const GTypeValueTable *value_table,
                                                             GTypeFlags flags);

Helper function which constructs a GTypeInfo structure and registers a GType, but which generates less linker overhead than a static const GTypeInfo structure. For further details of the parameters, please see GTypeInfo in the GLib documentation.

Registers type_name as the name of a new static type derived from parent_type. The value of flags determines the nature (e.g. abstract or not) of the type. It works by filling a GTypeInfo struct and calling `g_type_info_register_static()`.

`parent_type` : | The GType of the parent type the newly registered type will derive from
`type_name` : | NULL-terminated string used as the name of the new type
`class_size` : | Size of the class structure.
`base_init` : | Location of the base initialization function (optional).
`base_finalize` : | Location of the base finalization function (optional).
`class_init` : | Location of the class initialization function for class types Location of the default vtable inititalization function for interface types. (optional)
`class_finalize` : | Location of the class finalization function for class types. Location of the default vtable finalization function for interface types. (optional)
`class_data` : | User-supplied data passed to the class init/finalize functions.
`instance_size` : | Size of the instance (object) structure (required for instantiatable types only).
`n_preallocs` : | The number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Ignored on recent GLib's.
`instance_init` : | Location of the instance initialization function (optional, for instantiatable types only).
`value_table` : | A GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types).
`flags` : | GTypeFlags for this GType. E.g: G_TYPE_FLAG_ABSTRACT
Returns : | A GType for the newly-registered type.

Since 0.10.14

### gst_util_dump_mem ()

    void                gst_util_dump_mem                   (const guchar *mem,
                                                             guint size);

Dumps the memory block into a hex representation. Useful for debugging.

`mem` : | a pointer to the memory to dump
`size` : | the size of the memory block to dump

### gst_util_uint64_scale ()

    guint64             gst_util_uint64_scale               (guint64 val,
                                                             guint64 num,
                                                             guint64 denom);

Scale `val` by `num` / `denom`, trying to avoid overflows.

This function can potentially be very slow if denom > G_MAXUINT32.

`val` : | the number to scale
`num` : | the numerator of the scale ratio
`denom` : | the denominator of the scale ratio
Returns : | `val` * `num` / `denom`, trying to avoid overflows. In the case of an overflow, this function returns G_MAXUINT64.

### gst_util_uint64_scale_int ()

    guint64             gst_util_uint64_scale_int           (guint64 val,
                                                             gint num,
                                                             gint denom);

Scale a guint64 by a factor expressed as a fraction (num/denom), avoiding overflows and loss of precision.

`num` and `denom` must be positive integers. `denom` cannot be 0.

`val` : | guint64 (such as a GstClockTime) to scale.
`num` : | numerator of the scale factor.
`denom` : | denominator of the scale factor.
Returns : | `val` * `num` / `denom`, avoiding overflow and loss of precision. In the case of an overflow, this function returns G_MAXUINT64.

### gst_util_set_object_arg ()

    void                gst_util_set_object_arg             (GObject *object,
                                                             const gchar *name,
                                                             const gchar *value);

Convertes the string value to the type of the objects argument and sets the argument with it.

`object` : | the object to set the argument of
`name` : | the name of the argument to set
`value` : | the string value to set

### gst_util_set_value_from_string ()

    void                gst_util_set_value_from_string      (GValue *value,
                                                             const gchar *value_str);

Converts the string to the type of the value and sets the value with it.

`value` : | the value to set
`value_str` : | the string to get the value from

### gst_util_get_timestamp ()

    GstClockTime        gst_util_get_timestamp              (void);

Get a timestamp as GstClockTime to be used for interval meassurements. The timestamp should not be interpreted in any other way.

Returns : | the timestamp

Since 0.10.16