* handle or produce at runtime.
*
* A #GstCaps can be constructed with the following code fragment:
- * |[<!-- language="C" -->
+ *
+ * ``` C
* GstCaps *caps = gst_caps_new_simple ("video/x-raw",
* "format", G_TYPE_STRING, "I420",
* "framerate", GST_TYPE_FRACTION, 25, 1,
* "width", G_TYPE_INT, 320,
* "height", G_TYPE_INT, 240,
* NULL);
- * ]|
+ * ```
*
- * A #GstCaps is fixed when it has no properties with ranges or lists. Use
+ * A #GstCaps is fixed when it has no fields with ranges or lists. Use
* gst_caps_is_fixed() to test for fixed caps. Fixed caps can be used in a
* caps event to notify downstream elements of the current media type.
*
* Various methods exist to work with the media types such as subtracting
* or intersecting.
*
- * Be aware that the current #GstCaps / #GstStructure serialization into string
- * has limited support for nested #GstCaps / #GstStructure fields. It can only
- * support one level of nesting. Using more levels will lead to unexpected
+ * Be aware that until 1.20 the #GstCaps / #GstStructure serialization into string
+ * had limited support for nested #GstCaps / #GstStructure fields. It could only
+ * support one level of nesting. Using more levels would lead to unexpected
* behavior when using serialization features, such as gst_caps_to_string() or
* gst_value_serialize() and their counterparts.
*/
* Creates a new #GstCaps that is empty. That is, the returned
* #GstCaps contains no media formats.
* The #GstCaps is guaranteed to be writable.
- * Caller is responsible for unreffing the returned caps.
*
* Returns: (transfer full): the new #GstCaps
*/
*
* Creates a new #GstCaps that contains one #GstStructure with name
* @media_type.
- * Caller is responsible for unreffing the returned caps.
*
* Returns: (transfer full): the new #GstCaps
*/
* Creates a new #GstCaps that contains one #GstStructure. The
* structure is defined by the arguments, which have the same format
* as gst_structure_new().
- * Caller is responsible for unreffing the returned caps.
*
* Returns: (transfer full): the new #GstCaps
*/
*
* Converts a #GstStaticCaps to a #GstCaps.
*
- * Returns: (transfer full) (nullable): a pointer to the #GstCaps. Unref
- * after usage. Since the core holds an additional ref to the
- * returned caps, use gst_caps_make_writable() on the returned caps
- * to modify it.
+ * Returns: (transfer full) (nullable): a pointer to the #GstCaps. Since the
+ * core holds an additional ref to the returned caps, use
+ * gst_caps_make_writable() on the returned caps to modify it.
*/
GstCaps *
gst_static_caps_get (GstStaticCaps * static_caps)
* gst_static_caps_cleanup:
* @static_caps: the #GstStaticCaps to clean
*
- * Clean up the cached caps contained in @static_caps.
+ * Cleans up the cached caps contained in @static_caps.
*/
void
gst_static_caps_cleanup (GstStaticCaps * static_caps)
* @caps: the #GstCaps to remove from
* @idx: Index of the structure to remove
*
- * removes the structure with the given index from the list of structures
+ * Removes the structure with the given index from the list of structures
* contained in @caps.
*/
void
* @caps: (transfer full): the #GstCaps to merge into
* @structure: (transfer full): the #GstStructure to merge
*
- * Appends @structure to @caps if its not already expressed by @caps.
+ * Appends @structure to @caps if it is not already expressed by @caps.
*
* Returns: (transfer full): the merged caps.
*/
* @caps: a #GstCaps
* @index: the index of the structure
*
- * Finds the structure in @caps that has the index @index, and
- * returns it.
+ * Finds the structure in @caps at @index, and returns it.
*
- * WARNING: This function takes a const GstCaps *, but returns a
- * non-const GstStructure *. This is for programming convenience --
+ * WARNING: This function takes a `const GstCaps *`, but returns a
+ * non-const `GstStructure *`. This is for programming convenience --
* the caller should be aware that structures inside a constant
* #GstCaps should not be modified. However, if you know the caps
* are writable, either because you have just copied them or made
* structure returned in the usual way, e.g. with functions like
* gst_structure_set().
*
- * You do not need to free or unref the structure returned, it
- * belongs to the #GstCaps.
- *
* Returns: (transfer none): a pointer to the #GstStructure corresponding
* to @index
*/
* @caps: a #GstCaps
* @index: the index of the structure
*
- * Finds the features in @caps that has the index @index, and
- * returns it.
+ * Finds the features in @caps at @index, and returns it.
*
- * WARNING: This function takes a const GstCaps *, but returns a
- * non-const GstCapsFeatures *. This is for programming convenience --
- * the caller should be aware that structures inside a constant
+ * WARNING: This function takes a `const GstCaps *`, but returns a
+ * non-const `GstCapsFeatures *`. This is for programming convenience --
+ * the caller should be aware that features inside a constant
* #GstCaps should not be modified. However, if you know the caps
* are writable, either because you have just copied them or made
* them writable with gst_caps_make_writable(), you may modify the
* features returned in the usual way, e.g. with functions like
* gst_caps_features_add().
*
- * You do not need to free or unref the structure returned, it
- * belongs to the #GstCaps.
- *
* Returns: (transfer none) (nullable): a pointer to the #GstCapsFeatures
* corresponding to @index
*
* @index: the index of the structure
* @features: (allow-none) (transfer full): the #GstCapsFeatures to set
*
- * Sets the #GstCapsFeatures @features for the structure at @index.
+ * Sets the @features for the structure at @index.
*
* Since: 1.2
*/
* @caps: a #GstCaps
* @features: (allow-none) (transfer full): the #GstCapsFeatures to set
*
- * Sets the #GstCapsFeatures @features for all the structures of @caps.
+ * Sets the @features for all the structures of @caps.
*
* Since: 1.16
*/
* gst_caps_truncate:
* @caps: (transfer full): the #GstCaps to truncate
*
- * Discard all but the first structure from @caps. Useful when
+ * Discards all but the first structure from @caps. Useful when
* fixating.
*
* This function takes ownership of @caps and will call gst_caps_make_writable()
* additional reference to it with gst_caps_ref().
*
* Note that it is not guaranteed that the returned caps have exactly one
- * structure. If @caps is any or empty caps then then returned caps will be
+ * structure. If @caps is any or empty caps then the returned caps will be
* the same and contain no structure at all.
*
* Returns: (transfer full): truncated caps
*
* Returns a #GstCaps that represents the same set of formats as
* @caps, but contains no lists. Each list is expanded into separate
- * @GstStructures.
+ * #GstStructure.
*
* This function takes ownership of @caps and will call gst_caps_make_writable()
* on it so you must not use @caps afterwards unless you keep an additional
* reference to it with gst_caps_ref().
*
* Note that it is not guaranteed that the returned caps have exactly one
- * structure. If @caps are empty caps then then returned caps will be
+ * structure. If @caps are empty caps then the returned caps will be
* the empty too and contain no structure at all.
*
- * Calling this function with any caps is not allowed.
+ * Calling this function with ANY caps is not allowed.
*
* Returns: (transfer full): the fixated caps
*/
* can be converted back to a #GstCaps by gst_caps_from_string().
*
* For debugging purposes its easier to do something like this:
- * |[<!-- language="C" -->
+ *
+ * ``` C
* GST_LOG ("caps are %" GST_PTR_FORMAT, caps);
- * ]|
+ * ```
+ *
* This prints the caps in human readable form.
*
- * The current implementation of serialization will lead to unexpected results
- * when there are nested #GstCaps / #GstStructure deeper than one level.
+ * The implementation of serialization up to 1.20 would lead to unexpected results
+ * when there were nested #GstCaps / #GstStructure deeper than one level.
*
* Returns: (transfer full): a newly allocated string representing @caps.
*/
*
* Converts @caps from a string representation.
*
- * The current implementation of serialization will lead to unexpected results
- * when there are nested #GstCaps / #GstStructure deeper than one level.
+ * The implementation of serialization up to 1.20 would lead to unexpected results
+ * when there were nested #GstCaps / #GstStructure deeper than one level.
*
* Returns: (transfer full) (nullable): a newly allocated #GstCaps
*/
* followed by a gst_caps_make_writable(). If you only want to hold on to a
* reference to the data, you should use gst_caps_ref().
*
- * When you are finished with the caps, call gst_caps_unref() on it.
- *
- * Returns: the new #GstCaps
+ * Returns: (transfer full): the new #GstCaps
*/
GstCaps *(gst_caps_copy) (const GstCaps * caps)
{
* gst_caps_ref: (skip)
* @caps: the #GstCaps to reference
*
- * Add a reference to a #GstCaps object.
+ * Adds a reference to a #GstCaps object.
*
* From this point on, until the caller calls gst_caps_unref() or
* gst_caps_make_writable(), it is guaranteed that the caps object will not
* gst_caps_unref: (skip)
* @caps: a #GstCaps.
*
- * Unref a #GstCaps and and free all its structures and the
+ * Unrefs a #GstCaps and frees all its structures and the
* structures' values when the refcount reaches 0.
*/
void
*
* Modes of caps intersection
*
- * @GST_CAPS_INTERSECT_ZIG_ZAG tries to preserve overall order of both caps
+ * %GST_CAPS_INTERSECT_ZIG_ZAG tries to preserve overall order of both caps
* by iterating on the caps' structures as the following matrix shows:
- * |[
+ *
+ * ```
* caps1
* +-------------
* | 1 2 4 7
* caps2 | 3 5 8 10
* | 6 9 11 12
- * ]|
+ * ```
+ *
* Used when there is no explicit precedence of one caps over the other. e.g.
* tee's sink pad getcaps function, it will probe its src pad peers' for their
* caps and intersect them with this mode.
*
- * @GST_CAPS_INTERSECT_FIRST is useful when an element wants to preserve
+ * %GST_CAPS_INTERSECT_FIRST is useful when an element wants to preserve
* another element's caps priority order when intersecting with its own caps.
- * Example: If caps1 is [A, B, C] and caps2 is [E, B, D, A], the result
- * would be [A, B], maintaining the first caps priority on the intersection.
+ * Example: If caps1 is `[A, B, C]` and caps2 is `[E, B, D, A]`, the result
+ * would be `[A, B]`, maintaining the first caps priority on the intersection.
*/
typedef enum {
GST_CAPS_INTERSECT_ZIG_ZAG = 0,
* GST_CAPS_IS_SIMPLE:
* @caps: the #GstCaps instance to check
*
- * Convenience macro that checks if the number of structures in the given caps
- * is exactly one.
+ * Checks if the number of structures in the given caps is exactly one.
*/
#define GST_CAPS_IS_SIMPLE(caps) (gst_caps_get_size(caps) == 1)
* GST_CAPS_FLAGS:
* @caps: a #GstCaps.
*
- * A flags word containing #GstCapsFlags flags set on this caps.
+ * Gets a flags word containing #GstCapsFlags flags set on this caps.
*/
#define GST_CAPS_FLAGS(caps) GST_MINI_OBJECT_FLAGS(caps)
* GST_CAPS_REFCOUNT:
* @caps: a #GstCaps
*
- * Get access to the reference count field of the caps
+ * Gives access to the reference count field of the caps
*/
#define GST_CAPS_REFCOUNT(caps) GST_MINI_OBJECT_REFCOUNT(caps)
/**
* GST_CAPS_REFCOUNT_VALUE:
* @caps: a #GstCaps
*
- * Get the reference count value of the caps.
+ * Gets the reference count value of the caps.
*/
#define GST_CAPS_REFCOUNT_VALUE(caps) GST_MINI_OBJECT_REFCOUNT_VALUE(caps)
* @caps: the cached #GstCaps
* @string: a string describing a caps
*
- * Datastructure to initialize #GstCaps from a string description usually
+ * Data structure to initialize #GstCaps from a string description usually
* used in conjunction with GST_STATIC_CAPS() and gst_static_caps_get() to
* instantiate a #GstCaps.
*/
projects / platform / upstream / gstreamer.git / commitdiff