mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-11-18 07:47:17 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs: standardize GstCaps documentation

Browse source 
* 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 2021-02-10 14:19:18 +01:00
parent 87fd35d59c
commit 3f5042d74e
2 changed files with 51 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

87
gst/gstcaps.c
View file

@ -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

25
gst/gstcaps.h
View file

@ -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.
*/