mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-06-02 08:42:41 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs: standardize GstContext, GstControlBinding documentation

Browse source 
* Document virtual methods in standalone comments, in order to properly
  annotate them

* Don't repeat what annotations are stating with respect to ownership
  transfer, nullability

* Mark GstControlBinding ABI field as private

* Misc cleanup / typo fixes / addition of links

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/758>
This commit is contained in:
Mathieu Duponchelle 2021-02-15 15:06:46 +01:00
parent d5ae9f293a
commit 45d11f6590
3 changed files with 70 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
gst/gstcontext.c
View file

@ -33,24 +33,25 @@
*
* Applications can set a context on a complete pipeline by using
* gst_element_set_context(), which will then be propagated to all
* child elements. Elements can handle these in #GstElementClass.set_context()
* child elements. Elements can handle these in #GstElementClass::set_context
* and merge them with the context information they already have.
*
* When an element needs a context it will do the following actions in this
* order until one step succeeds:
*
* 1. Check if the element already has a context
* 2. Query downstream with GST_QUERY_CONTEXT for the context
* 3. Query upstream with GST_QUERY_CONTEXT for the context
* 4. Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required
* 2. Query downstream with %GST_QUERY_CONTEXT for the context
* 3. Query upstream with %GST_QUERY_CONTEXT for the context
* 4. Post a %GST_MESSAGE_NEED_CONTEXT message on the bus with the required
* context types and afterwards check if a usable context was set now
* 5. Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message
* 5. Create a context by itself and post a %GST_MESSAGE_HAVE_CONTEXT message
* on the bus.
*
* Bins will catch GST_MESSAGE_NEED_CONTEXT messages and will set any previously
* Bins will catch %GST_MESSAGE_NEED_CONTEXT messages and will set any previously
* known context on the element that asks for it if possible. Otherwise the
* application should provide one if it can.
*
* #GstContext<!-- -->s can be persistent.
* #GstContext can be persistent.
* A persistent #GstContext is kept in elements when they reach
* %GST_STATE_NULL, non-persistent ones will be removed.
* Also, a non-persistent context won't override a previous persistent
@ -156,7 +157,7 @@ gst_context_init (GstContext * context)
* @context_type: Context type
* @persistent: Persistent context
*
* Create a new context.
* Creates a new context.
*
* Returns: (transfer full): The new context.
*
@ -189,7 +190,7 @@ gst_context_new (const gchar * context_type, gboolean persistent)
* gst_context_get_context_type:
* @context: The #GstContext.
*
* Get the type of @context.
* Gets the type of @context.
*
* Returns: The type of the context.
*
@ -228,7 +229,7 @@ gst_context_has_context_type (const GstContext * context,
* gst_context_get_structure:
* @context: The #GstContext.
*
* Access the structure of the context.
* Accesses the structure of the context.
*
* Returns: (transfer none): The structure of the context. The structure is
* still owned by the context, which means that you should not modify it,
@ -248,7 +249,7 @@ gst_context_get_structure (const GstContext * context)
* gst_context_writable_structure:
* @context: The #GstContext.
*
* Get a writable version of the structure.
* Gets a writable version of the structure.
*
* Returns: The structure of the context. The structure is still
* owned by the context, which means that you should not free it and
@ -270,7 +271,7 @@ gst_context_writable_structure (GstContext * context)
* gst_context_is_persistent:
* @context: The #GstContext.
*
* Check if @context is persistent.
* Checks if @context is persistent.
*
* Returns: %TRUE if the context is persistent.
*

8
gst/gstcontrolbinding.c
View file

@ -24,7 +24,7 @@
* @title: GstControlBinding
* @short_description: attachment for control source sources
*
* A base class for value mapping objects that attaches control sources to gobject
* A base class for value mapping objects that attaches control sources to #GObject
* properties. Such an object is taking one or more #GstControlSource instances,
* combines them and maps the resulting value to the type and value range of the
* bound property.
@ -244,7 +244,7 @@ gst_control_binding_get_property (GObject * object, guint prop_id,
* @last_sync: the last time this was called
*
* Sets the property of the @object, according to the #GstControlSources that
* handle them and for the given timestamp.
* handles it and for the given timestamp.
*
* If this function fails, it is most likely the application developers fault.
* Most probably the control sources are not setup correctly.
@ -313,7 +313,7 @@ gst_control_binding_get_value (GstControlBinding * binding,
* @values: (array length=n_values): array to put control-values in
*
* Gets a number of values for the given controlled property starting at the
* requested time. The array @values need to hold enough space for @n_values of
* requested time. The array @values needs to hold enough space for @n_values of
* the same type as the objects property's type.
*
* This function is useful if one wants to e.g. draw a graph of the control
@ -482,7 +482,7 @@ gst_control_binding_set_disabled (GstControlBinding * binding,
* gst_control_binding_is_disabled:
* @binding: the control binding
*
* Check if the control binding is disabled.
* Checks if the control binding is disabled.
*
* Returns: %TRUE if the binding is inactive
*/

58
gst/gstcontrolbinding.h
View file

@ -56,6 +56,7 @@ typedef void (* GstControlBindingConvert) (GstControlBinding *binding, gdouble s
/**
* GstControlBinding:
* @parent: the parent structure
* @name: name of the property of this binding
* @pspec: #GParamSpec for this property
*
@ -79,8 +80,10 @@ struct _GstControlBinding {
union {
struct {
/*< private >*/
GstControlBindingPrivate *priv;
} abi;
/*< private >*/
gpointer _gst_reserved[GST_PADDING];
} ABI;
};
@ -88,11 +91,6 @@ struct _GstControlBinding {
/**
* GstControlBindingClass:
* @parent_class: Parent class
* @sync_values: implementation for updating the target values
* @get_value: implementation to fetch a single control-value
* @get_value_array: implementation to fetch a series of control-values
* @get_g_value_array: implementation to fetch a series of control-values
* as g_values
*
* The class structure of #GstControlBinding.
*/
@ -102,9 +100,59 @@ struct _GstControlBindingClass
GstObjectClass parent_class;
/*< public >*/
/**
* GstControlBindingClass::sync_values:
* @binding: the control binding
* @object: the object that has controlled properties
* @timestamp: the time that should be processed
* @last_sync: the last time this was called
*
* Update the target values
*
* Returns: %TRUE if the controller value could be applied to the object
* property, %FALSE otherwise
*/
gboolean (* sync_values) (GstControlBinding *binding, GstObject *object, GstClockTime timestamp, GstClockTime last_sync);
/**
* GstControlBindingClass::get_value:
* @binding: the control binding
* @timestamp: the time the control-change should be read from
*
* Fetch a single control-value
*
* Returns: (nullable): the GValue of the property at the given time,
* or %NULL if the property isn't controlled.
*/
GValue * (* get_value) (GstControlBinding *binding, GstClockTime timestamp);
/**
* GstControlBindingClass::get_value_array:
* @binding: the control binding
* @timestamp: the time that should be processed
* @interval: the time spacing between subsequent values
* @n_values: the number of values
* @values: (array length=n_values): array to put control-values in
*
* Fetch a series of control-values
*
* Returns: %TRUE if the given array could be filled, %FALSE otherwise
*/
gboolean (* get_value_array) (GstControlBinding *binding, GstClockTime timestamp,GstClockTime interval, guint n_values, gpointer values);
/**
* GstControlBindingClass::get_g_value_array:
* @binding: the control binding
* @timestamp: the time that should be processed
* @interval: the time spacing between subsequent values
* @n_values: the number of values
* @values: (array length=n_values): array to put control-values in
*
* Fetch a series of control-values as g_values
*
* Returns: %TRUE if the given array could be filled, %FALSE otherwise
*/
gboolean (* get_g_value_array) (GstControlBinding *binding, GstClockTime timestamp,GstClockTime interval, guint n_values, GValue *values);
/*< private >*/