mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-06-16 13:00:41 +00:00
docs: standardize GstCaps documentation
* Don't repeat what annotations are stating with respect to ownership transfer, nullability * Reword the warnings for caps nestability in light of the 1.20 improvements * Misc cleanup / typo fixes / addition of links Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/754>
This commit is contained in:
Mathieu Duponchelle
parent
87fd35d59c
commit
3f5042d74e
|
|
@ -35,7 +35,8 @@
|
|||
* 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,
|
||||
|
|
@ -43,18 +44,18 @@
|
|||
* "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.
|
||||
*/
|
||||
|
|
@ -246,7 +247,6 @@ gst_caps_init (GstCaps * caps)
|
|||
* 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
|
||||
*/
|
||||
|
|
@ -290,7 +290,6 @@ gst_caps_new_any (void)
|
|||
*
|
||||
* 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
|
||||
*/
|
||||
|
|
@ -317,7 +316,6 @@ gst_caps_new_empty_simple (const char *media_type)
|
|||
* 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
|
||||
*/
|
||||
|
|
@ -400,10 +398,9 @@ G_DEFINE_POINTER_TYPE (GstStaticCaps, gst_static_caps);
|
|||
*
|
||||
* 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)
|
||||
|
|
@ -463,7 +460,7 @@ no_string:
|
|||
* 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)
|
||||
|
|
@ -700,7 +697,7 @@ gst_caps_append_structure_full (GstCaps * caps, GstStructure * structure,
|
|||
* @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
|
||||
|
|
@ -721,7 +718,7 @@ gst_caps_remove_structure (GstCaps * caps, guint idx)
|
|||
* @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.
|
||||
*/
|
||||
|
|
@ -859,11 +856,10 @@ gst_caps_get_size (const GstCaps * 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
|
||||
|
|
@ -871,9 +867,6 @@ gst_caps_get_size (const GstCaps * caps)
|
|||
* 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
|
||||
*/
|
||||
|
|
@ -891,21 +884,17 @@ gst_caps_get_structure (const GstCaps * caps, guint 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
|
||||
*
|
||||
|
|
@ -950,7 +939,7 @@ gst_caps_get_features (const GstCaps * caps, guint 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
|
||||
*/
|
||||
|
|
@ -982,7 +971,7 @@ gst_caps_set_features (GstCaps * caps, guint index, GstCapsFeatures * features)
|
|||
* @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
|
||||
*/
|
||||
|
|
@ -1056,7 +1045,7 @@ gst_caps_copy_nth (const GstCaps * caps, guint nth)
|
|||
* 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()
|
||||
|
|
@ -1064,7 +1053,7 @@ gst_caps_copy_nth (const GstCaps * caps, guint nth)
|
|||
* 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
|
||||
|
|
@ -2005,7 +1994,7 @@ gst_caps_normalize_foreach (GQuark field_id, const GValue * value, gpointer ptr)
|
|||
*
|
||||
* 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
|
||||
|
|
@ -2249,10 +2238,10 @@ gst_caps_simplify (GstCaps * caps)
|
|||
* 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
|
||||
*/
|
||||
|
|
@ -2369,13 +2358,15 @@ caps_serialize (const GstCaps * caps, GstSerializeFlags flags)
|
|||
* 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.
|
||||
*/
|
||||
|
|
@ -2514,8 +2505,8 @@ gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
|
|||
*
|
||||
* 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
|
||||
*/
|
||||
|
|
@ -2707,9 +2698,7 @@ gst_caps_filter_and_map_in_place (GstCaps * caps, GstCapsFilterMapFunc func,
|
|||
* 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)
|
||||
{
|
||||
|
|
@ -2720,7 +2709,7 @@ 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
|
||||
|
|
@ -2741,7 +2730,7 @@ gst_caps_ref (GstCaps * caps)
|
|||
* 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
|
||||
|
|
|
|||
|
|
@ -55,23 +55,25 @@ typedef enum {
|
|||
*
|
||||
* 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,
|
||||
|
|
@ -114,8 +116,7 @@ typedef enum {
|
|||
* 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)
|
||||
|
||||
|
|
@ -143,7 +144,7 @@ GST_API GstCaps * _gst_caps_none;
|
|||
* 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)
|
||||
|
||||
|
|
@ -152,14 +153,14 @@ GST_API GstCaps * _gst_caps_none;
|
|||
* 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)
|
||||
|
||||
|
|
@ -291,7 +292,7 @@ struct _GstCaps {
|
|||
* @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.
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in a new issue