GstValue: GStreamer 1.0 Core Reference Manual

## GstValue GstValue — GValue implementations specific to GStreamer |

## Functions

#define | GST_MAKE_FOURCC()
#define | GST_STR_FOURCC()
#define | GST_FOURCC_ARGS()
#define | GST_VALUE_HOLDS_INT_RANGE()
#define | GST_TYPE_INT_RANGE
void | gst_value_set_int_range ()
gint | gst_value_get_int_range_min ()
gint | gst_value_get_int_range_max ()
void | gst_value_set_int_range_step ()
gint | gst_value_get_int_range_step ()
#define | GST_VALUE_HOLDS_BITMASK()
#define | GST_TYPE_BITMASK
void | gst_value_set_bitmask ()
guint64 | gst_value_get_bitmask ()
#define | GST_VALUE_HOLDS_FLAG_SET()
#define | GST_TYPE_FLAG_SET
gboolean | gst_structure_get_flagset ()
guint | gst_value_get_flagset_flags ()
guint | gst_value_get_flagset_mask ()
void | gst_value_set_flagset ()
#define | GST_FLAG_SET_MASK_EXACT
#define | GST_VALUE_HOLDS_INT64_RANGE()
#define | GST_TYPE_INT64_RANGE
void | gst_value_set_int64_range ()
gint64 | gst_value_get_int64_range_min ()
gint64 | gst_value_get_int64_range_max ()
void | gst_value_set_int64_range_step ()
gint64 | gst_value_get_int64_range_step ()
#define | GST_VALUE_HOLDS_DOUBLE_RANGE()
#define | GST_TYPE_DOUBLE_RANGE
void | gst_value_set_double_range ()
gdouble | gst_value_get_double_range_min ()
gdouble | gst_value_get_double_range_max ()
#define | GST_VALUE_HOLDS_LIST()
#define | GST_TYPE_LIST
#define | GST_VALUE_HOLDS_ARRAY()
#define | GST_TYPE_ARRAY
void | gst_value_list_append_value ()
void | gst_value_list_append_and_take_value ()
void | gst_value_list_prepend_value ()
void | gst_value_list_concat ()
void | gst_value_list_merge ()
guint | gst_value_list_get_size ()
const GValue * | gst_value_list_get_value ()
#define | GST_VALUE_HOLDS_FRACTION()
#define | GST_TYPE_FRACTION
void | gst_value_set_fraction ()
gint | gst_value_get_fraction_numerator ()
gint | gst_value_get_fraction_denominator ()
gboolean | gst_value_fraction_multiply ()
gboolean | gst_value_fraction_subtract ()
#define | GST_VALUE_HOLDS_FRACTION_RANGE()
#define | GST_TYPE_FRACTION_RANGE
void | gst_value_set_fraction_range ()
const GValue * | gst_value_get_fraction_range_min ()
const GValue * | gst_value_get_fraction_range_max ()
void | gst_value_set_fraction_range_full ()
#define | GST_VALUE_HOLDS_DATE_TIME()
#define | GST_VALUE_HOLDS_CAPS()
void | gst_value_set_caps ()
const GstCaps * | gst_value_get_caps ()
#define | GST_VALUE_HOLDS_CAPS_FEATURES()
void | gst_value_set_caps_features ()
const GstCapsFeatures * | gst_value_get_caps_features ()
#define | GST_VALUE_HOLDS_STRUCTURE()
void | gst_value_set_structure ()
const GstStructure * | gst_value_get_structure ()
#define | GST_VALUE_HOLDS_BUFFER()
#define | gst_value_get_buffer()
#define | gst_value_set_buffer()
#define | gst_value_take_buffer()
#define | GST_VALUE_HOLDS_SAMPLE()
#define | gst_value_get_sample()
#define | gst_value_set_sample()
#define | gst_value_take_sample()
#define | GST_VALUE_LESS_THAN
gint | (*GstValueCompareFunc) ()
gchar * | (*GstValueSerializeFunc) ()
gboolean | (*GstValueDeserializeFunc) ()
gboolean | gst_value_is_fixed ()
void | gst_value_register ()
void | gst_value_init_and_copy ()
gchar * | gst_value_serialize ()
gboolean | gst_value_deserialize ()
gint | gst_value_compare ()
gboolean | gst_value_can_compare ()
gboolean | gst_value_union ()
gboolean | gst_value_can_union ()
gboolean | gst_value_subtract ()
gboolean | gst_value_can_subtract ()
gboolean | gst_value_intersect ()
gboolean | gst_value_can_intersect ()
gboolean | gst_value_is_subset ()
void | gst_value_array_append_value ()
void | gst_value_array_append_and_take_value ()
guint | gst_value_array_get_size ()
const GValue * | gst_value_array_get_value ()
void | gst_value_array_prepend_value ()
gboolean | gst_value_fixate ()

## Types and Values

#define | GST_FOURCC_FORMAT
#define | GST_VALUE_EQUAL
#define | GST_VALUE_GREATER_THAN
#define | GST_VALUE_UNORDERED
struct | GstValueTable

## Includes

    #include <gst/gst.h>

## Description

GValue implementations specific to GStreamer.

Note that operations on the same GValue from multiple threads may lead to undefined behaviour.

## Functions

### GST_MAKE_FOURCC()

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

Transform four characters into a guint32 fourcc value with host endianness.

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

#### Parameters

a | the first character |
b | the second character |
c | the third character |
d | the fourth character |

### GST_STR_FOURCC()

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

Transform an input string into a guint32 fourcc value with host endianness. Caller is responsible for ensuring the input string consists of at least four characters.

    1
    guint32 fourcc = GST_STR_FOURCC ("MJPG");

#### Parameters

f | a string with at least four characters |

### GST_FOURCC_ARGS()

    #define             GST_FOURCC_ARGS(fourcc)

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

#### Parameters

fourcc | a guint32 fourcc value to output |

### GST_VALUE_HOLDS_INT_RANGE()

    #define GST_VALUE_HOLDS_INT_RANGE(x)      ((x) != NULL && G_VALUE_TYPE(x) == _gst_int_range_type)

Checks if the given GValue contains a GST_TYPE_INT_RANGE value.

#### Parameters

x | the GValue to check |

### GST_TYPE_INT_RANGE

    #define GST_TYPE_INT_RANGE               (_gst_int_range_type)

a GValue type that represents an integer range

#### Returns

the GType of GstIntRange

### gst_value_set_int_range ()

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

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

#### Parameters

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

    gint
    gst_value_get_int_range_min (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_INT_RANGE |

#### Returns

the minimum of the range

### gst_value_get_int_range_max ()

    gint
    gst_value_get_int_range_max (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_INT_RANGE |

#### Returns

the maximum of the range

### gst_value_set_int_range_step ()

    void
    gst_value_set_int_range_step (GValue *value,
                                  gint start,
                                  gint end,
                                  gint step);

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

#### Parameters

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

### gst_value_get_int_range_step ()

    gint
    gst_value_get_int_range_step (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_INT_RANGE |

#### Returns

the step of the range

### GST_VALUE_HOLDS_BITMASK()

    #define GST_VALUE_HOLDS_BITMASK(x)      ((x) != NULL && G_VALUE_TYPE(x) == _gst_bitmask_type)

Checks if the given GValue contains a GST_TYPE_BITMASK value.

#### Parameters

x | the GValue to check |

### GST_TYPE_BITMASK

    #define GST_TYPE_BITMASK                 (_gst_bitmask_type)

a GValue type that represents a 64-bit bitmask.

#### Returns

the GType of GstBitmask (which is not explicitly typed)

### gst_value_set_bitmask ()

    void
    gst_value_set_bitmask (GValue *value,
                           guint64 bitmask);

Sets `value` to the bitmask specified by `bitmask` .

#### Parameters

value | a GValue initialized to GST_TYPE_BITMASK |
bitmask | the bitmask |

### gst_value_get_bitmask ()

    guint64
    gst_value_get_bitmask (const GValue *value);

Gets the bitmask specified by `value` .

#### Parameters

value | a GValue initialized to GST_TYPE_BITMASK |

#### Returns

the bitmask.

### GST_VALUE_HOLDS_FLAG_SET()

    #define GST_VALUE_HOLDS_FLAG_SET(x)     (G_TYPE_CHECK_VALUE_TYPE ((x), GST_TYPE_FLAG_SET))

Checks if the given GValue contains a GST_TYPE_FLAG_SET value.

#### Parameters

x | the GValue to check |

Since: 1.6

### GST_TYPE_FLAG_SET

    #define GST_TYPE_FLAG_SET                   (_gst_flagset_type)

a GValue type that represents a 32-bit flag bitfield, with 32-bit mask indicating which of the bits in the field are explicitly set. Useful for negotiation.

#### Returns

the GType of GstFlags (which is not explicitly typed)

Since: 1.6

### gst_structure_get_flagset ()

    gboolean
    gst_structure_get_flagset (const GstStructure *structure,
                               const gchar *fieldname,
                               guint *value_flags,
                               guint *value_mask);

Read the GstFlagSet flags and mask out of the structure into the provided pointers.

#### Parameters

structure | a GstStructure |
fieldname | the name of a field |
value_flags | a pointer to a guint for the flags field. | [out][allow-none]
value_mask | a pointer to a guint for the mask field. | [out][allow-none]

#### Returns

`TRUE` if the values could be set correctly. If there was no field with `fieldname` or the existing field did not contain a GstFlagSet, this function returns `FALSE`.

Since: 1.6

### gst_value_get_flagset_flags ()

    guint
    gst_value_get_flagset_flags (const GValue *value);

Retrieve the flags field of a GstFlagSet `value` .

#### Parameters

value | a GValue initialized to GST_TYPE_FLAG_SET |

#### Returns

the flags field of the flagset instance.

Since: 1.6

### gst_value_get_flagset_mask ()

    guint
    gst_value_get_flagset_mask (const GValue *value);

Retrieve the mask field of a GstFlagSet `value` .

#### Parameters

value | a GValue initialized to GST_TYPE_FLAG_SET |

#### Returns

the mask field of the flagset instance.

Since: 1.6

### gst_value_set_flagset ()

    void
    gst_value_set_flagset (GValue *value,
                           guint flags,
                           guint mask);

Sets `value` to the flags and mask values provided in `flags` and `mask` . The `flags` value indicates the values of flags, the `mask` represents which bits in the flag value have been set, and which are "don't care"

#### Parameters

value | a GValue initialized to GST_TYPE_FLAGS |
flags | The value of the flags set or unset |
mask | The mask indicate which flags bits must match for comparisons |

Since: 1.6

### GST_FLAG_SET_MASK_EXACT

    #define GST_FLAG_SET_MASK_EXACT ((guint)(-1))

### GST_VALUE_HOLDS_INT64_RANGE()

    #define GST_VALUE_HOLDS_INT64_RANGE(x)    ((x) != NULL && G_VALUE_TYPE(x) == _gst_int64_range_type)

Checks if the given GValue contains a GST_TYPE_INT64_RANGE value.

#### Parameters

x | the GValue to check |

### GST_TYPE_INT64_RANGE

    #define GST_TYPE_INT64_RANGE             (_gst_int64_range_type)

a GValue type that represents an gint64 range

#### Returns

the GType of GstInt64Range

### gst_value_set_int64_range ()

    void
    gst_value_set_int64_range (GValue *value,
                               gint64 start,
                               gint64 end);

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

#### Parameters

value | a GValue initialized to GST_TYPE_INT64_RANGE |
start | the start of the range |
end | the end of the range |

### gst_value_get_int64_range_min ()

    gint64
    gst_value_get_int64_range_min (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_INT64_RANGE |

#### Returns

the minimum of the range

### gst_value_get_int64_range_max ()

    gint64
    gst_value_get_int64_range_max (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_INT64_RANGE |

#### Returns

the maximum of the range

### gst_value_set_int64_range_step ()

    void
    gst_value_set_int64_range_step (GValue *value,
                                    gint64 start,
                                    gint64 end,
                                    gint64 step);

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

#### Parameters

value | a GValue initialized to GST_TYPE_INT64_RANGE |
start | the start of the range |
end | the end of the range |
step | the step of the range |

### gst_value_get_int64_range_step ()

    gint64
    gst_value_get_int64_range_step (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_INT64_RANGE |

#### Returns

the step of the range

### GST_VALUE_HOLDS_DOUBLE_RANGE()

    #define GST_VALUE_HOLDS_DOUBLE_RANGE(x)   ((x) != NULL && G_VALUE_TYPE(x) == _gst_double_range_type)

Checks if the given GValue contains a GST_TYPE_DOUBLE_RANGE value.

#### Parameters

x | the GValue to check |

### GST_TYPE_DOUBLE_RANGE

    #define GST_TYPE_DOUBLE_RANGE            (_gst_double_range_type)

a GValue type that represents a floating point range with double precision

#### Returns

the GType of GstIntRange

### gst_value_set_double_range ()

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

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

#### Parameters

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

    gdouble
    gst_value_get_double_range_min (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_DOUBLE_RANGE |

#### Returns

the minimum of the range

### gst_value_get_double_range_max ()

    gdouble
    gst_value_get_double_range_max (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_DOUBLE_RANGE |

#### Returns

the maximum of the range

### GST_VALUE_HOLDS_LIST()

    #define GST_VALUE_HOLDS_LIST(x)         ((x) != NULL && G_VALUE_TYPE(x) == _gst_value_list_type)

Checks if the given GValue contains a GST_TYPE_LIST value.

#### Parameters

x | the GValue to check |

### GST_TYPE_LIST

    #define GST_TYPE_LIST                    (_gst_value_list_type)

a GValue type that represents an unordered list of GValue values. This is used for example to express a list of possible values for a field in a caps structure, like a list of possible sample rates, of which only one will be chosen in the end. This means that all values in the list are meaningful on their own.

#### Returns

the GType of GstValueList (which is not explicitly typed)

### GST_VALUE_HOLDS_ARRAY()

    #define GST_VALUE_HOLDS_ARRAY(x)        ((x) != NULL && G_VALUE_TYPE(x) == _gst_value_array_type)

Checks if the given GValue contains a GST_TYPE_ARRAY value.

#### Parameters

x | the GValue to check |

### GST_TYPE_ARRAY

    #define GST_TYPE_ARRAY                   (_gst_value_array_type)

a GValue type that represents an ordered list of GValue values. This is used to express a set of values that is meaningful only in their specific combination and order of values. Each value on its own is not particularly meaningful, only the ordered array in its entirety is meaningful. This is used for example to express channel layouts for multichannel audio where each channel needs to be mapped to a position in the room.

#### Returns

the GType of GstArrayList (which is not explicitly typed)

### 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` .

#### Parameters

value | a GValue of type GST_TYPE_LIST |
append_value | the value to append. | [transfer none]

### gst_value_list_append_and_take_value ()

    void
    gst_value_list_append_and_take_value (GValue *value,
                                          GValue *append_value);

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

#### Parameters

value | a GValue of type GST_TYPE_LIST |
append_value | the value to append. | [transfer full]

Since: 1.2

### 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` .

#### Parameters

value | a GValue of type GST_TYPE_LIST |
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. Values that are not of type GST_TYPE_LIST are treated as if they were lists of length 1. `dest` will be initialized to the type GST_TYPE_LIST.

#### Parameters

dest | an uninitialized GValue to take the result. | [out caller-allocates]
value1 | a GValue |
value2 | a GValue |

### gst_value_list_merge ()

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

Merges copies of `value1` and `value2` . Values that are not of type GST_TYPE_LIST are treated as if they were lists of length 1.

The result will be put into `dest` and will either be a list that will not contain any duplicates, or a non-list type (if `value1` and `value2` were equal).

#### Parameters

dest | an uninitialized GValue to take the result. | [out caller-allocates]
value1 | a GValue |
value2 | a GValue |

### gst_value_list_get_size ()

    guint
    gst_value_list_get_size (const GValue *value);

Gets the number of values contained in `value` .

#### Parameters

value | a GValue of type GST_TYPE_LIST |

#### 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` .

#### Parameters

value | a GValue of type GST_TYPE_LIST |
index | index of value to get from the list |

#### Returns

the value at the given index.

[transfer none]

### GST_VALUE_HOLDS_FRACTION()

    #define GST_VALUE_HOLDS_FRACTION(x)     ((x) != NULL && G_VALUE_TYPE(x) == _gst_fraction_type)

Checks if the given GValue contains a GST_TYPE_FRACTION value.

#### Parameters

x | the GValue to check |

### GST_TYPE_FRACTION

    #define GST_TYPE_FRACTION                (_gst_fraction_type)

a GValue type that represents a fraction of an integer numerator over an integer denominator

#### Returns

the GType of GstFraction (which is not explicitly typed)

### gst_value_set_fraction ()

    void
    gst_value_set_fraction (GValue *value,
                            gint numerator,
                            gint 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.

#### Parameters

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

### gst_value_get_fraction_numerator ()

    gint
    gst_value_get_fraction_numerator (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_FRACTION |

#### Returns

the numerator of the fraction.

### gst_value_get_fraction_denominator ()

    gint
    gst_value_get_fraction_denominator (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_FRACTION |

#### Returns

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 GValue items containing a GST_TYPE_FRACTION and sets `product` to the product of the two fractions.

#### Parameters

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

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

Subtracts the `subtrahend` from the `minuend` and sets `dest` to the result.

#### Parameters

dest | a GValue initialized to GST_TYPE_FRACTION |
minuend | a GValue initialized to GST_TYPE_FRACTION |
subtrahend | a GValue initialized to GST_TYPE_FRACTION |

#### Returns

`FALSE` in case of an error (like integer overflow), `TRUE` otherwise.

### GST_VALUE_HOLDS_FRACTION_RANGE()

    #define GST_VALUE_HOLDS_FRACTION_RANGE(x) ((x) != NULL && G_VALUE_TYPE(x) == _gst_fraction_range_type)

Checks if the given GValue contains a GST_TYPE_FRACTION_RANGE value.

#### Parameters

x | the GValue to check |

### GST_TYPE_FRACTION_RANGE

    #define GST_TYPE_FRACTION_RANGE           (_gst_fraction_range_type)

a GValue type that represents a GstFraction range

#### Returns

the GType of GstFractionRange

### gst_value_set_fraction_range ()

    void
    gst_value_set_fraction_range (GValue *value,
                                  const GValue *start,
                                  const GValue *end);

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

#### Parameters

value | a GValue initialized to GST_TYPE_FRACTION_RANGE |
start | the start of the range (a GST_TYPE_FRACTION GValue) |
end | the end of the range (a GST_TYPE_FRACTION GValue) |

### gst_value_get_fraction_range_min ()

    const GValue *
    gst_value_get_fraction_range_min (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_FRACTION_RANGE |

#### Returns

the minimum of the range

### gst_value_get_fraction_range_max ()

    const GValue *
    gst_value_get_fraction_range_max (const GValue *value);

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

#### Parameters

value | a GValue initialized to GST_TYPE_FRACTION_RANGE |

#### Returns

the maximum of the range

### gst_value_set_fraction_range_full ()

    void
    gst_value_set_fraction_range_full (GValue *value,
                                       gint numerator_start,
                                       gint denominator_start,
                                       gint numerator_end,
                                       gint denominator_end);

Sets `value` to the range specified by `numerator_start` /`denominator_start` and `numerator_end` /`denominator_end` .

#### Parameters

value | a GValue initialized to GST_TYPE_FRACTION_RANGE |
numerator_start | the numerator start of the range |
denominator_start | the denominator start of the range |
numerator_end | the numerator end of the range |
denominator_end | the denominator end of the range |

### GST_VALUE_HOLDS_DATE_TIME()

    #define GST_VALUE_HOLDS_DATE_TIME(x)    ((x) != NULL && G_VALUE_TYPE(x) == _gst_date_time_type)

Checks if the given GValue contains a GST_TYPE_DATE_TIME value.

#### Parameters

x | the GValue to check |

### GST_VALUE_HOLDS_CAPS()

    #define GST_VALUE_HOLDS_CAPS(x)         ((x) != NULL && G_VALUE_TYPE(x) == _gst_caps_type)

Checks if the given GValue contains a GST_TYPE_CAPS value.

#### Parameters

x | the GValue to check |

### gst_value_set_caps ()

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

Sets the contents of `value` to `caps` . A reference to the provided `caps` will be taken by the `value` .

#### Parameters

value | a GValue initialized to GST_TYPE_CAPS |
caps | the caps to set the value to. | [transfer none]

### gst_value_get_caps ()

    const GstCaps *
    gst_value_get_caps (const GValue *value);

Gets the contents of `value` . The reference count of the returned GstCaps will not be modified, therefore the caller must take one before getting rid of the `value` .

#### Parameters

value | a GValue initialized to GST_TYPE_CAPS |

#### Returns

the contents of `value` .

[transfer none]

### GST_VALUE_HOLDS_CAPS_FEATURES()

    #define GST_VALUE_HOLDS_CAPS_FEATURES(x)        (G_VALUE_HOLDS((x), _gst_caps_features_type))

Checks if the given GValue contains a GST_TYPE_CAPS_FEATURES value.

#### Parameters

x | the GValue to check |

### gst_value_set_caps_features ()

    void
    gst_value_set_caps_features (GValue *value,
                                 const GstCapsFeatures *features);

Sets the contents of `value` to `features` .

#### Parameters

value | a GValue initialized to GST_TYPE_CAPS_FEATURES |
features | the features to set the value to |

### gst_value_get_caps_features ()

    const GstCapsFeatures *
    gst_value_get_caps_features (const GValue *value);

Gets the contents of `value` .

#### Parameters

value | a GValue initialized to GST_TYPE_CAPS_FEATURES |

#### Returns

the contents of `value` .

[transfer none]

### GST_VALUE_HOLDS_STRUCTURE()

    #define GST_VALUE_HOLDS_STRUCTURE(x)            (G_VALUE_HOLDS((x), _gst_structure_type))

Checks if the given GValue contains a GST_TYPE_STRUCTURE value.

#### Parameters

x | the GValue to check |

### gst_value_set_structure ()

    void
    gst_value_set_structure (GValue *value,
                             const GstStructure *structure);

Sets the contents of `value` to `structure` . The actual

#### Parameters

value | a GValue initialized to GST_TYPE_STRUCTURE |
structure | the structure to set the value to |

### gst_value_get_structure ()

    const GstStructure *
    gst_value_get_structure (const GValue *value);

Gets the contents of `value` .

#### Parameters

value | a GValue initialized to GST_TYPE_STRUCTURE |

#### Returns

the contents of `value` .

[transfer none]

### GST_VALUE_HOLDS_BUFFER()

    #define GST_VALUE_HOLDS_BUFFER(x)       ((x) != NULL && G_VALUE_TYPE(x) == _gst_buffer_type)

Checks if the given GValue contains a GST_TYPE_BUFFER value.

#### Parameters

x | the GValue to check |

### gst_value_get_buffer()

    #define         gst_value_get_buffer(v)         GST_BUFFER_CAST (g_value_get_boxed(v))

Receives a GstBuffer as the value of `v` . Does not return a reference to the buffer, so the pointer is only valid for as long as the caller owns a reference to `v` .

#### Parameters

v | a GValue to query |

#### Returns

buffer.

[transfer none]

### gst_value_set_buffer()

    #define         gst_value_set_buffer(v,b)       g_value_set_boxed((v),(b))

Sets `b` as the value of `v` . Caller retains reference to buffer.

#### Parameters

v | a GValue to receive the data |
b | a GstBuffer to assign to the GstValue. | [transfer none]

### gst_value_take_buffer()

    #define         gst_value_take_buffer(v,b)      g_value_take_boxed(v,(b))

Sets `b` as the value of `v` . Caller gives away reference to buffer.

#### Parameters

v | a GValue to receive the data |
b | a GstBuffer to assign to the GstValue. | [transfer full]

### GST_VALUE_HOLDS_SAMPLE()

    #define GST_VALUE_HOLDS_SAMPLE(x)       ((x) != NULL && G_VALUE_TYPE(x) == _gst_sample_type)

Checks if the given GValue contains a GST_TYPE_SAMPLE value.

#### Parameters

x | the GValue to check |

### gst_value_get_sample()

    #define         gst_value_get_sample(v)         GST_SAMPLE_CAST (g_value_get_boxed(v))

Receives a GstSample as the value of `v` . Does not return a reference to the sample, so the pointer is only valid for as long as the caller owns a reference to `v` .

#### Parameters

v | a GValue to query |

#### Returns

sample.

[transfer none]

### gst_value_set_sample()

    #define         gst_value_set_sample(v,b)       g_value_set_boxed((v),(b))

Sets `b` as the value of `v` . Caller retains reference to sample.

#### Parameters

v | a GValue to receive the data |
b | a GstSample to assign to the GstValue. | [transfer none]

### gst_value_take_sample()

    #define         gst_value_take_sample(v,b)      g_value_take_boxed(v,(b))

Sets `b` as the value of `v` . Caller gives away reference to sample.

#### Parameters

v | a GValue to receive the data |
b | a GstSample to assign to the GstValue. | [transfer full]

### 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.

### GstValueCompareFunc ()

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

Used together with `gst_value_compare()` to compare GValue items.

#### Parameters

value1 | first value for comparison |
value2 | second value for comparison |

#### Returns

one of GST_VALUE_LESS_THAN, GST_VALUE_EQUAL, GST_VALUE_GREATER_THAN or GST_VALUE_UNORDERED

### GstValueSerializeFunc ()

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

Used by `gst_value_serialize()` to obtain a non-binary form of the GValue.

Free-function: g_free

#### Parameters

value1 | a GValue |

#### Returns

the string representation of the value.

[transfer full]

### GstValueDeserializeFunc ()

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

Used by `gst_value_deserialize()` to parse a non-binary form into the GValue.

#### Parameters

dest | a GValue |
s | a string |

#### Returns

`TRUE` for success

### 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.

#### Parameters

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 GValue items of a given type. Each type can only be added once.

#### Parameters

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.

#### Parameters

dest | the target value. | [out caller-allocates]
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()`.

Free-function: g_free

#### Parameters

value | a GValue to serialize |

#### Returns

the serialization for `value` or `NULL` if none exists.

[transfer full][nullable]

### 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.

#### Parameters

dest | GValue to fill with contents of deserialization. | [out caller-allocates]
src | string to deserialize |

#### Returns

`TRUE` on success

### gst_value_compare ()

    gint
    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_THAN is returned. If `value1` is less than `value2` , GST_VALUE_LESS_THAN is returned. If the values are equal, GST_VALUE_EQUAL is returned.

#### Parameters

value1 | a value to compare |
value2 | another value to compare |

#### Returns

comparison result

### gst_value_can_compare ()

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

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

#### Parameters

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 corresponding to the union of `value1` and `value2` .

#### Parameters

dest | the destination value. | [out caller-allocates]
value1 | a value to union |
value2 | another value to union |

#### Returns

`TRUE` if the union succeeded.

### 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`.

#### Parameters

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_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.

#### Parameters

dest | the destination value for the result if the subtraction is not empty. May be `NULL`, in which case the resulting set will not be computed, which can give a fair speedup. | [out caller-allocates][allow-none]
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` .

#### Parameters

minuend | the value to subtract from |
subtrahend | the value to subtract |

#### Returns

`TRUE` if a subtraction is possible

### 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` , unless `NULL`. If the intersection is non-empty, `dest` is not modified.

#### Parameters

dest | a uninitialized GValue that will hold the calculated intersection value. May be `NULL` if the resulting set if not needed. | [out caller-allocates][transfer full][allow-none]
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.

#### Parameters

value1 | a value to intersect |
value2 | another value to intersect |

#### Returns

`TRUE` if the values can intersect

### gst_value_is_subset ()

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

Check that `value1` is a subset of `value2` .

Return: `TRUE` is `value1` is a subset of `value2`

#### Parameters

value1 | a GValue |
value2 | a GValue |

### gst_value_array_append_value ()

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

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

#### Parameters

value | a GValue of type GST_TYPE_ARRAY |
append_value | the value to append |

### gst_value_array_append_and_take_value ()

    void
    gst_value_array_append_and_take_value (GValue *value,
                                           GValue *append_value);

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

#### Parameters

value | a GValue of type GST_TYPE_ARRAY |
append_value | the value to append. | [transfer full]

Since: 1.2

### gst_value_array_get_size ()

    guint
    gst_value_array_get_size (const GValue *value);

Gets the number of values contained in `value` .

#### Parameters

value | a GValue of type GST_TYPE_ARRAY |

#### Returns

the number of values

### gst_value_array_get_value ()

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

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

#### Parameters

value | a GValue of type GST_TYPE_ARRAY |
index | index of value to get from the array |

#### Returns

the value at the given index.

[transfer none]

### gst_value_array_prepend_value ()

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

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

#### Parameters

value | a GValue of type GST_TYPE_ARRAY |
prepend_value | the value to prepend |

### gst_value_fixate ()

    gboolean
    gst_value_fixate (GValue *dest,
                      const GValue *src);

Fixate `src` into a new value `dest` . For ranges, the first element is taken. For lists and arrays, the first item is fixated and returned. If `src` is already fixed, this function returns `FALSE`.

#### Parameters

dest | the GValue destination |
src | the GValue to fixate |

#### Returns

`TRUE` if `dest` contains a fixated version of `src` .

## Types and Values

### GST_FOURCC_FORMAT

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

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

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

### 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.

### struct GstValueTable

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

VTable for the GValue `type` .

#### Members

GType `type`; | a GType |
GstValueCompareFunc `compare`; | a GstValueCompareFunc |
GstValueSerializeFunc `serialize`; | a GstValueSerializeFunc |
GstValueDeserializeFunc `deserialize`; | a GstValueDeserializeFunc |