mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-27 06:20:12 +00:00
docs: standardize GstContext, GstControlBinding documentation
* 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:
parent
d5ae9f293a
commit
45d11f6590
3 changed files with 70 additions and 21 deletions
|
@ -33,24 +33,25 @@
|
||||||
*
|
*
|
||||||
* Applications can set a context on a complete pipeline by using
|
* Applications can set a context on a complete pipeline by using
|
||||||
* gst_element_set_context(), which will then be propagated to all
|
* 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.
|
* and merge them with the context information they already have.
|
||||||
*
|
*
|
||||||
* When an element needs a context it will do the following actions in this
|
* When an element needs a context it will do the following actions in this
|
||||||
* order until one step succeeds:
|
* order until one step succeeds:
|
||||||
|
*
|
||||||
* 1. Check if the element already has a context
|
* 1. Check if the element already has a context
|
||||||
* 2. Query downstream with GST_QUERY_CONTEXT for the context
|
* 2. Query downstream with %GST_QUERY_CONTEXT for the context
|
||||||
* 3. Query upstream 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
|
* 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
|
* 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.
|
* 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
|
* known context on the element that asks for it if possible. Otherwise the
|
||||||
* application should provide one if it can.
|
* 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
|
* A persistent #GstContext is kept in elements when they reach
|
||||||
* %GST_STATE_NULL, non-persistent ones will be removed.
|
* %GST_STATE_NULL, non-persistent ones will be removed.
|
||||||
* Also, a non-persistent context won't override a previous persistent
|
* Also, a non-persistent context won't override a previous persistent
|
||||||
|
@ -156,7 +157,7 @@ gst_context_init (GstContext * context)
|
||||||
* @context_type: Context type
|
* @context_type: Context type
|
||||||
* @persistent: Persistent context
|
* @persistent: Persistent context
|
||||||
*
|
*
|
||||||
* Create a new context.
|
* Creates a new context.
|
||||||
*
|
*
|
||||||
* Returns: (transfer full): The 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:
|
* gst_context_get_context_type:
|
||||||
* @context: The #GstContext.
|
* @context: The #GstContext.
|
||||||
*
|
*
|
||||||
* Get the type of @context.
|
* Gets the type of @context.
|
||||||
*
|
*
|
||||||
* Returns: The type of the context.
|
* Returns: The type of the context.
|
||||||
*
|
*
|
||||||
|
@ -228,7 +229,7 @@ gst_context_has_context_type (const GstContext * context,
|
||||||
* gst_context_get_structure:
|
* gst_context_get_structure:
|
||||||
* @context: The #GstContext.
|
* @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
|
* Returns: (transfer none): The structure of the context. The structure is
|
||||||
* still owned by the context, which means that you should not modify it,
|
* 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:
|
* gst_context_writable_structure:
|
||||||
* @context: The #GstContext.
|
* @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
|
* Returns: The structure of the context. The structure is still
|
||||||
* owned by the context, which means that you should not free it and
|
* 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:
|
* gst_context_is_persistent:
|
||||||
* @context: The #GstContext.
|
* @context: The #GstContext.
|
||||||
*
|
*
|
||||||
* Check if @context is persistent.
|
* Checks if @context is persistent.
|
||||||
*
|
*
|
||||||
* Returns: %TRUE if the context is persistent.
|
* Returns: %TRUE if the context is persistent.
|
||||||
*
|
*
|
||||||
|
|
|
@ -24,7 +24,7 @@
|
||||||
* @title: GstControlBinding
|
* @title: GstControlBinding
|
||||||
* @short_description: attachment for control source sources
|
* @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,
|
* 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
|
* combines them and maps the resulting value to the type and value range of the
|
||||||
* bound property.
|
* bound property.
|
||||||
|
@ -244,7 +244,7 @@ gst_control_binding_get_property (GObject * object, guint prop_id,
|
||||||
* @last_sync: the last time this was called
|
* @last_sync: the last time this was called
|
||||||
*
|
*
|
||||||
* Sets the property of the @object, according to the #GstControlSources that
|
* 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.
|
* If this function fails, it is most likely the application developers fault.
|
||||||
* Most probably the control sources are not setup correctly.
|
* 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
|
* @values: (array length=n_values): array to put control-values in
|
||||||
*
|
*
|
||||||
* Gets a number of values for the given controlled property starting at the
|
* 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.
|
* 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
|
* 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:
|
* gst_control_binding_is_disabled:
|
||||||
* @binding: the control binding
|
* @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
|
* Returns: %TRUE if the binding is inactive
|
||||||
*/
|
*/
|
||||||
|
|
|
@ -56,6 +56,7 @@ typedef void (* GstControlBindingConvert) (GstControlBinding *binding, gdouble s
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* GstControlBinding:
|
* GstControlBinding:
|
||||||
|
* @parent: the parent structure
|
||||||
* @name: name of the property of this binding
|
* @name: name of the property of this binding
|
||||||
* @pspec: #GParamSpec for this property
|
* @pspec: #GParamSpec for this property
|
||||||
*
|
*
|
||||||
|
@ -79,8 +80,10 @@ struct _GstControlBinding {
|
||||||
|
|
||||||
union {
|
union {
|
||||||
struct {
|
struct {
|
||||||
|
/*< private >*/
|
||||||
GstControlBindingPrivate *priv;
|
GstControlBindingPrivate *priv;
|
||||||
} abi;
|
} abi;
|
||||||
|
/*< private >*/
|
||||||
gpointer _gst_reserved[GST_PADDING];
|
gpointer _gst_reserved[GST_PADDING];
|
||||||
} ABI;
|
} ABI;
|
||||||
};
|
};
|
||||||
|
@ -88,11 +91,6 @@ struct _GstControlBinding {
|
||||||
/**
|
/**
|
||||||
* GstControlBindingClass:
|
* GstControlBindingClass:
|
||||||
* @parent_class: Parent class
|
* @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.
|
* The class structure of #GstControlBinding.
|
||||||
*/
|
*/
|
||||||
|
@ -102,9 +100,59 @@ struct _GstControlBindingClass
|
||||||
GstObjectClass parent_class;
|
GstObjectClass parent_class;
|
||||||
|
|
||||||
/*< public >*/
|
/*< 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);
|
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);
|
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);
|
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);
|
gboolean (* get_g_value_array) (GstControlBinding *binding, GstClockTime timestamp,GstClockTime interval, guint n_values, GValue *values);
|
||||||
|
|
||||||
/*< private >*/
|
/*< private >*/
|
||||||
|
|
Loading…
Reference in a new issue