## GstValue

GstValue — GValue implementations specific to GStreamer

## Synopsis

    #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_TYPE_FOURCC
    #define     GST_TYPE_INT_RANGE
    #define     GST_TYPE_DOUBLE_RANGE
    #define     GST_TYPE_LIST
    #define     GST_TYPE_FIXED_LIST
    #define     GST_TYPE_FRACTION
    #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);
    struct      GstValueTable;
    gboolean    gst_type_is_fixed               (GType type);
    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);
    G_CONST_RETURN 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);
    G_CONST_RETURN 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)

`a` : |
`b` : |
`c` : |
`d` : |

### GST_STR_FOURCC()

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

`f` : |

### GST_FOURCC_FORMAT

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

### GST_FOURCC_ARGS()

    #define     GST_FOURCC_ARGS(fourcc)

`fourcc` : |

### GST_VALUE_HOLDS_FOURCC()

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

`x` : |

### GST_VALUE_HOLDS_INT_RANGE()

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

`x` : |

### GST_VALUE_HOLDS_DOUBLE_RANGE()

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

`x` : |

### GST_VALUE_HOLDS_LIST()

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

`x` : |

### GST_VALUE_HOLDS_FIXED_LIST()

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

`x` : |

### GST_VALUE_HOLDS_CAPS()

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

`x` : |

### GST_VALUE_HOLDS_FRACTION()

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

`x` : |

### GST_TYPE_FOURCC

    #define GST_TYPE_FOURCC                  gst_type_fourcc

### GST_TYPE_INT_RANGE

    #define GST_TYPE_INT_RANGE               gst_type_int_range

### GST_TYPE_DOUBLE_RANGE

    #define GST_TYPE_DOUBLE_RANGE            gst_type_double_range

### GST_TYPE_LIST

    #define GST_TYPE_LIST                    gst_type_list

### GST_TYPE_FIXED_LIST

    #define GST_TYPE_FIXED_LIST              gst_type_fixed_list

### GST_TYPE_FRACTION

    #define GST_TYPE_FRACTION                gst_type_fraction

### GST_VALUE_LESS_THAN

    #define GST_VALUE_LESS_THAN              (-1)

### GST_VALUE_EQUAL

    #define GST_VALUE_EQUAL                   0

### GST_VALUE_GREATER_THAN

    #define GST_VALUE_GREATER_THAN            1

### GST_VALUE_UNORDERED

    #define GST_VALUE_UNORDERED               2

### GstValueCompareFunc ()

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

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

### 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);

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

### GstValueSubtractFunc ()

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

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

### struct GstValueTable

    struct GstValueTable {

      GType type;
      GstValueCompareFunc compare;
      GstValueSerializeFunc serialize;
      GstValueDeserializeFunc deserialize;

      void *_gst_reserved [GST_PADDING];
    };

### gst_type_is_fixed ()

    gboolean    gst_type_is_fixed               (GType type);

`type` : |
Returns : |

### gst_value_register ()

    void        gst_value_register              (const GstValueTable *table);

`table` : |

### gst_value_init_and_copy ()

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

`dest` : |
`src` : |

### gst_value_serialize ()

    gchar*      gst_value_serialize             (const GValue *value);

`value` : |
Returns : |

### gst_value_deserialize ()

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

`dest` : |
`src` : |
Returns : |

### 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 ()

    G_CONST_RETURN 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 ()

    G_CONST_RETURN 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 the two values.

`dest` : | the destination value for intersection
`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);

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

### gst_value_register_intersect_func ()

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

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