## GstValue

GstValue — GValue implementations specific to GStreamer

## Synopsis

    #include <gst/gst.h>

    #define     GST_MAKE_FOURCC                 (a,b,c,d)
    #define     GST_STR_FOURCC                  (f)
    #define     GST_FOURCC_FORMAT
    #define     GST_FOURCC_ARGS                 (fourcc)
    #define     GST_VALUE_HOLDS_FOURCC          (x)
    #define     GST_VALUE_HOLDS_INT_RANGE       (x)
    #define     GST_VALUE_HOLDS_DOUBLE_RANGE    (x)
    #define     GST_VALUE_HOLDS_LIST            (x)
    #define     GST_VALUE_HOLDS_FIXED_LIST      (x)
    #define     GST_VALUE_HOLDS_CAPS            (x)
    #define     GST_VALUE_HOLDS_FRACTION        (x)
    #define     GST_VALUE_LESS_THAN
    #define     GST_VALUE_EQUAL
    #define     GST_VALUE_GREATER_THAN
    #define     GST_VALUE_UNORDERED
    int         (*GstValueCompareFunc)          (const GValue *value1,
                                                 const GValue *value2);
    char*       (*GstValueSerializeFunc)        (const GValue *value1);
    gboolean    (*GstValueDeserializeFunc)      (GValue *dest,
                                                 const char *s);
    int         (*GstValueUnionFunc)            (GValue *dest,
                                                 const GValue *value1,
                                                 const GValue *value2);
    int         (*GstValueIntersectFunc)        (GValue *dest,
                                                 const GValue *value1,
                                                 const GValue *value2);
    int         (*GstValueSubtractFunc)         (GValue *dest,
                                                 const GValue *minuend,
                                                 const GValue *subtrahend);
                GstValueTable;
    gboolean    gst_type_is_fixed               (GType type);
    gboolean    gst_value_is_fixed              (const GValue *value);
    void        gst_value_register              (const GstValueTable *table);
    void        gst_value_init_and_copy         (GValue *dest,
                                                 const GValue *src);
    gchar*      gst_value_serialize             (const GValue *value);
    gboolean    gst_value_deserialize           (GValue *dest,
                                                 const gchar *src);
    void        gst_value_list_append_value     (GValue *value,
                                                 const GValue *append_value);
    void        gst_value_list_prepend_value    (GValue *value,
                                                 const GValue *prepend_value);
    void        gst_value_list_concat           (GValue *dest,
                                                 const GValue *value1,
                                                 const GValue *value2);
    guint       gst_value_list_get_size         (const GValue *value);
    const GValue* gst_value_list_get_value      (const GValue *value,
                                                 guint index);
    void        gst_value_set_fourcc            (GValue *value,
                                                 guint32 fourcc);
    guint32     gst_value_get_fourcc            (const GValue *value);
    void        gst_value_set_int_range         (GValue *value,
                                                 int start,
                                                 int end);
    int         gst_value_get_int_range_min     (const GValue *value);
    int         gst_value_get_int_range_max     (const GValue *value);
    void        gst_value_set_double_range      (GValue *value,
                                                 double start,
                                                 double end);
    double      gst_value_get_double_range_min  (const GValue *value);
    double      gst_value_get_double_range_max  (const GValue *value);
    const GstCaps* gst_value_get_caps           (const GValue *value);
    void        gst_value_set_caps              (GValue *value,
                                                 const GstCaps *caps);
    int         gst_value_get_fraction_numerator
                                                (const GValue *value);
    int         gst_value_get_fraction_denominator
                                                (const GValue *value);
    void        gst_value_set_fraction          (GValue *value,
                                                 int numerator,
                                                 int denominator);
    gboolean    gst_value_fraction_multiply     (GValue *product,
                                                 const GValue *factor1,
                                                 const GValue *factor2);
    int         gst_value_compare               (const GValue *value1,
                                                 const GValue *value2);
    gboolean    gst_value_can_compare           (const GValue *value1,
                                                 const GValue *value2);
    gboolean    gst_value_union                 (GValue *dest,
                                                 const GValue *value1,
                                                 const GValue *value2);
    gboolean    gst_value_can_union             (const GValue *value1,
                                                 const GValue *value2);
    void        gst_value_register_union_func   (GType type1,
                                                 GType type2,
                                                 GstValueUnionFunc func);
    gboolean    gst_value_subtract              (GValue *dest,
                                                 const GValue *minuend,
                                                 const GValue *subtrahend);
    gboolean    gst_value_can_subtract          (const GValue *minuend,
                                                 const GValue *subtrahend);
    void        gst_value_register_subtract_func
                                                (GType minuend_type,
                                                 GType subtrahend_type,
                                                 GstValueSubtractFunc func);
    gboolean    gst_value_intersect             (GValue *dest,
                                                 const GValue *value1,
                                                 const GValue *value2);
    gboolean    gst_value_can_intersect         (const GValue *value1,
                                                 const GValue *value2);
    void        gst_value_register_intersect_func
                                                (GType type1,
                                                 GType type2,
                                                 GstValueIntersectFunc func);

## Description

## Details

### GST_MAKE_FOURCC()

    #define GST_MAKE_FOURCC(a,b,c,d)        (guint32)((a)|(b)<<8|(c)<<16|(d)<<24)

will transform four characters into a host-endiannness guint32 fourcc:

    guint32 fourcc = GST_MAKE_FOURCC ('M','J','P','G');

`a` : | the first component
`b` : | the second component
`c` : | the third component
`d` : | the fourth component

### GST_STR_FOURCC()

    #define GST_STR_FOURCC(f)               (guint32)(((f)[0])|((f)[1]<<8)|((f)[2]<<16)|((f)[3]<<24))

Creates a fourcc from an input string. The input string should consisnt of at least four characters (this is not checked for!).

    guint32 fourcc = GST_STR_FOURCC("MJPG");

`f` : | a string with four characters

### GST_FOURCC_FORMAT

    #define GST_FOURCC_FORMAT "%c%c%c%c"

Can be used to properly output a fourcc (a guint32) value in a `printf()`-style text message.

    printf ("fourcc: %" GST_FOURCC_FORMAT "\n", GST_FOURCC_ARGS (fcc));

### GST_FOURCC_ARGS()

    #define     GST_FOURCC_ARGS(fourcc)

Can be used to properly output a fourcc (a guint32) value in a `printf()`-style text message.

    printf ("fourcc: %" GST_FOURCC_FORMAT "\n", GST_FOURCC_ARGS (fcc));

`fourcc` : | the fourcc value to print

### GST_VALUE_HOLDS_FOURCC()

    #define GST_VALUE_HOLDS_FOURCC(x)       (G_VALUE_HOLDS(x, gst_type_fourcc))

Checks if the give GValue contains a FOURCC value.

`x` : | the GValue to check

### GST_VALUE_HOLDS_INT_RANGE()

    #define GST_VALUE_HOLDS_INT_RANGE(x)    (G_VALUE_HOLDS(x, gst_type_int_range))

Checks if the give GValue contains a INT_RANGE value.

`x` : | the GValue to check

### GST_VALUE_HOLDS_DOUBLE_RANGE()

    #define GST_VALUE_HOLDS_DOUBLE_RANGE(x) (G_VALUE_HOLDS(x, gst_type_double_range))

Checks if the give GValue contains a DOUBLE_RANGE value.

`x` : | the GValue to check

### GST_VALUE_HOLDS_LIST()

    #define GST_VALUE_HOLDS_LIST(x)         (G_VALUE_HOLDS(x, gst_type_list))

Checks if the give GValue contains a LIST value.

`x` : | the GValue to check

### GST_VALUE_HOLDS_FIXED_LIST()

    #define GST_VALUE_HOLDS_FIXED_LIST(x)   (G_VALUE_HOLDS(x, gst_type_fixed_list))

Checks if the give GValue contains a FIXED_LIST value.

`x` : | the GValue to check

### GST_VALUE_HOLDS_CAPS()

    #define GST_VALUE_HOLDS_CAPS(x)		(G_VALUE_HOLDS(x, GST_TYPE_CAPS))

Checks if the give GValue contains a CAPS value.

`x` : | the GValue to check

### GST_VALUE_HOLDS_FRACTION()

    #define GST_VALUE_HOLDS_FRACTION(x)	(G_VALUE_HOLDS(x, gst_type_fraction))

Checks if the give GValue contains a FRACTION value.

`x` : | the GValue to check

### GST_VALUE_LESS_THAN

    #define GST_VALUE_LESS_THAN              (-1)

Indicates that the first value provided to a comparison function (`gst_value_compare()`) is lesser than the second one.

### GST_VALUE_EQUAL

    #define GST_VALUE_EQUAL                   0

Indicates that the first value provided to a comparison function (`gst_value_compare()`) is equal to the second one.

### GST_VALUE_GREATER_THAN

    #define GST_VALUE_GREATER_THAN            1

Indicates that the first value provided to a comparison function (`gst_value_compare()`) is greater than the second one.

### GST_VALUE_UNORDERED

    #define GST_VALUE_UNORDERED               2

Indicates that the comparison function (`gst_value_compare()`) can not determine a order for the two provided values.

### GstValueCompareFunc ()

    int         (*GstValueCompareFunc)          (const GValue *value1,
                                                 const GValue *value2);

`value1` : |
`value2` : |
Returns : | one of GST_VALUE_LESS_THAN, GST_VALUE_EQUAL, GST_VALUE_GREATER_THAN or GST_VALUE_UNORDERED

### GstValueSerializeFunc ()

    char*       (*GstValueSerializeFunc)        (const GValue *value1);

`value1` : |
Returns : |

### GstValueDeserializeFunc ()

    gboolean    (*GstValueDeserializeFunc)      (GValue *dest,
                                                 const char *s);

`dest` : |
`s` : |
Returns : |

### GstValueUnionFunc ()

    int         (*GstValueUnionFunc)            (GValue *dest,
                                                 const GValue *value1,
                                                 const GValue *value2);

`dest` : |
`value1` : |
`value2` : |
Returns : |

### GstValueIntersectFunc ()

    int         (*GstValueIntersectFunc)        (GValue *dest,
                                                 const GValue *value1,
                                                 const GValue *value2);

Functions having this type calculate the intersection of `value1` and `value2`. If the intersection is non-empty, the result is placed in `dest` and TRUE is returned. If the intersection is empty, `dest` is unmodified and FALSE is returned.

`dest` : | a uninitialized GValue that will hold the calculated intersection value
`value1` : | a value to intersect
`value2` : | another value to intersect
Returns : | TRUE if the intersection is non-empty, FALSE otherwise

### GstValueSubtractFunc ()

    int         (*GstValueSubtractFunc)         (GValue *dest,
                                                 const GValue *minuend,
                                                 const GValue *subtrahend);

`dest` : |
`minuend` : |
`subtrahend` : |
Returns : |

### GstValueTable

    typedef struct {
      GType type;
      GstValueCompareFunc compare;
      GstValueSerializeFunc serialize;
      GstValueDeserializeFunc deserialize;
    } GstValueTable;

GType `type`; | GType that the functions operate on.
GstValueCompareFunc `compare`; | A function that compares two values of this type.
GstValueSerializeFunc `serialize`; | A function that transforms a value of this type to a string. Strings created by this function must be unique and should be human readable.
GstValueDeserializeFunc `deserialize`; | A function that transforms a string to a value of this type. This function must transform strings created by the serialize function back to the original value. This function may optionally transform other strings into values.

### gst_type_is_fixed ()

    gboolean    gst_type_is_fixed               (GType type);

Tests if the given GType, if available in a GstStructure (or any other container) will contain a "fixed" (which means: one possible value) or an "unfixed" (which means: multiple possible values, such as data lists or data ranges) value.

`type` : | the GType to check
Returns : | true if the type is "fixed".

### gst_value_is_fixed ()

    gboolean    gst_value_is_fixed              (const GValue *value);

Tests if the given GValue, if available in a GstStructure (or any other container) contains a "fixed" (which means: one value) or an "unfixed" (which means: multiple possible values, such as data lists or data ranges) value.

`value` : | the GValue to check
Returns : | true if the value is "fixed".

### gst_value_register ()

    void        gst_value_register              (const GstValueTable *table);

Registers functions to perform calculations on GValues of a given type.

`table` : | structure containing functions to register

### gst_value_init_and_copy ()

    void        gst_value_init_and_copy         (GValue *dest,
                                                 const GValue *src);

Initialises the target value to be of the same type as source and then copies the contents from source to target.

`dest` : | the target value
`src` : | the source value

### gst_value_serialize ()

    gchar*      gst_value_serialize             (const GValue *value);

tries to transform the given `value` into a string representation that allows getting back this string later on using `gst_value_deserialize()`.

`value` : | a GValue to serialize
Returns : | the serialization for `value` or NULL if none exists

### gst_value_deserialize ()

    gboolean    gst_value_deserialize           (GValue *dest,
                                                 const gchar *src);

Tries to deserialize a string into the type specified by the given GValue. If the operation succeeds, TRUE is returned, FALSE otherwise.

`dest` : | GValue to fill with contents of deserialization
`src` : | string to deserialize
Returns : | TRUE on success

### gst_value_list_append_value ()

    void        gst_value_list_append_value     (GValue *value,
                                                 const GValue *append_value);

Appends `append_value` to the GstValueList in `value`.

`value` : | a GstValueList to append a value to
`append_value` : | the value to append

### gst_value_list_prepend_value ()

    void        gst_value_list_prepend_value    (GValue *value,
                                                 const GValue *prepend_value);

Prepends `prepend_value` to the GstValueList in `value`.

`value` : | a GstValueList to prepend a value to
`prepend_value` : | the value to prepend

### gst_value_list_concat ()

    void        gst_value_list_concat           (GValue *dest,
                                                 const GValue *value1,
                                                 const GValue *value2);

Concatenates copies of value1 and value2 into a list. The value `dest` is initialized to the type GST_TYPE_LIST.

`dest` : | an uninitialized GValue to take the result
`value1` : | first value to put into the union
`value2` : | second value to put into the union

### gst_value_list_get_size ()

    guint       gst_value_list_get_size         (const GValue *value);

Gets the number of values contained in `value`.

`value` : | a GstValueList
Returns : | the number of values

### gst_value_list_get_value ()

    const GValue* gst_value_list_get_value      (const GValue *value,
                                                 guint index);

Gets the value that is a member of the list contained in `value` and has the index `index`.

`value` : | a GstValueList
`index` : | index of value to get from the list
Returns : | the value at the given index

### gst_value_set_fourcc ()

    void        gst_value_set_fourcc            (GValue *value,
                                                 guint32 fourcc);

Sets `value` to `fourcc`.

`value` : | a GValue initialized to GST_TYPE_FOURCC
`fourcc` : | the fourcc to set

### gst_value_get_fourcc ()

    guint32     gst_value_get_fourcc            (const GValue *value);

Gets the fourcc contained in `value`.

`value` : | a GValue initialized to GST_TYPE_FOURCC
Returns : | the fourcc contained in `value`.

### gst_value_set_int_range ()

    void        gst_value_set_int_range         (GValue *value,
                                                 int start,
                                                 int end);

Sets `value` to the range specified by `start` and `end`.

`value` : | a GValue initialized to GST_TYPE_INT_RANGE
`start` : | the start of the range
`end` : | the end of the range

### gst_value_get_int_range_min ()

    int         gst_value_get_int_range_min     (const GValue *value);

Gets the minimum of the range specified by `value`.

`value` : | a GValue initialized to GST_TYPE_INT_RANGE
Returns : | the minimum of the range

### gst_value_get_int_range_max ()

    int         gst_value_get_int_range_max     (const GValue *value);

Gets the maximum of the range specified by `value`.

`value` : | a GValue initialized to GST_TYPE_INT_RANGE
Returns : | the maxumum of the range

### gst_value_set_double_range ()

    void        gst_value_set_double_range      (GValue *value,
                                                 double start,
                                                 double end);

Sets `value` to the range specified by `start` and `end`.

`value` : | a GValue initialized to GST_TYPE_DOUBLE_RANGE
`start` : | the start of the range
`end` : | the end of the range

### gst_value_get_double_range_min ()

    double      gst_value_get_double_range_min  (const GValue *value);

Gets the minimum of the range specified by `value`.

`value` : | a GValue initialized to GST_TYPE_DOUBLE_RANGE
Returns : | the minumum of the range

### gst_value_get_double_range_max ()

    double      gst_value_get_double_range_max  (const GValue *value);

Gets the maximum of the range specified by `value`.

`value` : | a GValue initialized to GST_TYPE_DOUBLE_RANGE
Returns : | the maxumum of the range

### gst_value_get_caps ()

    const GstCaps* gst_value_get_caps           (const GValue *value);

Gets the contents of `value`.

`value` : | a GValue initialized to GST_TYPE_CAPS
Returns : | the contents of `value`

### gst_value_set_caps ()

    void        gst_value_set_caps              (GValue *value,
                                                 const GstCaps *caps);

Sets the contents of `value` to coorespond to `caps`. The actual GstCaps structure is copied before it is used.

`value` : | a GValue initialized to GST_TYPE_CAPS
`caps` : | the caps to set the value to

### gst_value_get_fraction_numerator ()

    int         gst_value_get_fraction_numerator
                                                (const GValue *value);

Gets the numerator of the fraction specified by `value`.

`value` : | a GValue initialized to GST_TYPE_FRACTION
Returns : | the numerator of the fraction.

### gst_value_get_fraction_denominator ()

    int         gst_value_get_fraction_denominator
                                                (const GValue *value);

Gets the denominator of the fraction specified by `value`.

`value` : | a GValue initialized to GST_TYPE_FRACTION
Returns : | the denominator of the fraction.

### gst_value_set_fraction ()

    void        gst_value_set_fraction          (GValue *value,
                                                 int numerator,
                                                 int denominator);

Sets `value` to the fraction specified by `numerator` over `denominator`. The fraction gets reduced to the smallest numerator and denominator, and if necessary the sign is moved to the numerator.

`value` : | a GValue initialized to GST_TYPE_FRACTION
`numerator` : | the numerator of the fraction
`denominator` : | the denominator of the fraction

### gst_value_fraction_multiply ()

    gboolean    gst_value_fraction_multiply     (GValue *product,
                                                 const GValue *factor1,
                                                 const GValue *factor2);

Multiplies the two GValues containing a GstFraction and sets `product` to the product of the two fractions.

`product` : | a GValue initialized to GST_TYPE_FRACTION
`factor1` : | a GValue initialized to GST_TYPE_FRACTION
`factor2` : | a GValue initialized to GST_TYPE_FRACTION
Returns : | FALSE in case of an error (like integer overflow), TRUE otherwise.

### gst_value_compare ()

    int         gst_value_compare               (const GValue *value1,
                                                 const GValue *value2);

Compares `value1` and `value2`. If `value1` and `value2` cannot be compared, the function returns GST_VALUE_UNORDERED. Otherwise, if `value1` is greater than `value2`, GST_VALUE_GREATER is returned. If `value1` is less than `value2`, GST_VALUE_LESSER is returned. If the values are equal, GST_VALUE_EQUAL is returned.

`value1` : | a value to compare
`value2` : | another value to compare
Returns : | A GstValueCompareType value

### gst_value_can_compare ()

    gboolean    gst_value_can_compare           (const GValue *value1,
                                                 const GValue *value2);

Determines if `value1` and `value2` can be compared.

`value1` : | a value to compare
`value2` : | another value to compare
Returns : | TRUE if the values can be compared

### gst_value_union ()

    gboolean    gst_value_union                 (GValue *dest,
                                                 const GValue *value1,
                                                 const GValue *value2);

Creates a GValue cooresponding to the union of `value1` and `value2`.

`dest` : | the destination value
`value1` : | a value to union
`value2` : | another value to union
Returns : | TRUE if the values could be unioned

### gst_value_can_union ()

    gboolean    gst_value_can_union             (const GValue *value1,
                                                 const GValue *value2);

Determines if `value1` and `value2` can be non-trivially unioned. Any two values can be trivially unioned by adding both of them to a GstValueList. However, certain types have the possibility to be unioned in a simpler way. For example, an integer range and an integer can be unioned if the integer is a subset of the integer range. If there is the possibility that two values can be unioned, this function returns TRUE.

`value1` : | a value to union
`value2` : | another value to union
Returns : | TRUE if there is a function allowing the two values to be unioned.

### gst_value_register_union_func ()

    void        gst_value_register_union_func   (GType type1,
                                                 GType type2,
                                                 GstValueUnionFunc func);

Registers a union function that can create a union between GValues of the type `type1` and `type2`.

`type1` : | a type to union
`type2` : | another type to union
`func` : | a function that implments creating a union between the two types

### gst_value_subtract ()

    gboolean    gst_value_subtract              (GValue *dest,
                                                 const GValue *minuend,
                                                 const GValue *subtrahend);

Subtracts `subtrahend` from `minuend` and stores the result in `dest`. Note that this means subtraction as in sets, not as in mathematics.

`dest` : | the destination value for the result if the subtraction is not empty
`minuend` : | the value to subtract from
`subtrahend` : | the value to subtract
Returns : | TRUE if the subtraction is not empty

### gst_value_can_subtract ()

    gboolean    gst_value_can_subtract          (const GValue *minuend,
                                                 const GValue *subtrahend);

Checks if it's possible to subtract `subtrahend` from `minuend`.

`minuend` : | the value to subtract from
`subtrahend` : | the value to subtract
Returns : | TRUE if a subtraction is possible

### gst_value_register_subtract_func ()

    void        gst_value_register_subtract_func
                                                (GType minuend_type,
                                                 GType subtrahend_type,
                                                 GstValueSubtractFunc func);

Registers `func` as a function capable of subtracting the values of `subtrahend_type` from values of `minuend_type`.

`minuend_type` : | type of the minuend
`subtrahend_type` : | type of the subtrahend
`func` : | function to use

### gst_value_intersect ()

    gboolean    gst_value_intersect             (GValue *dest,
                                                 const GValue *value1,
                                                 const GValue *value2);

Calculates the intersection of two values. If the values have a non-empty intersection, the value representing the intersection is placed in `dest`. If the intersection is non-empty, `dest` is not modified.

`dest` : | a uninitialized GValue that will hold the calculated intersection value
`value1` : | a value to intersect
`value2` : | another value to intersect
Returns : | TRUE if the intersection is non-empty

### gst_value_can_intersect ()

    gboolean    gst_value_can_intersect         (const GValue *value1,
                                                 const GValue *value2);

Determines if intersecting two values will produce a valid result. Two values will produce a valid intersection if they have the same type, or if there is a method (registered by gst_value_register_intersection_func) to calculate the intersection.

`value1` : | a value to intersect
`value2` : | another value to intersect
Returns : | TRUE if the values can intersect

### gst_value_register_intersect_func ()

    void        gst_value_register_intersect_func
                                                (GType type1,
                                                 GType type2,
                                                 GstValueIntersectFunc func);

`type1` : |
`type2` : |
`func` : |