mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-19 14:56:36 +00:00
docs: standardize GstBufferPool documentation
* Don't repeat what annotations are stating with respect to ownership transfer, nullability * Document virtual methods in standalone comments, so that parameters can be documented. This is functionally useful here, as parameters require annotations, and should make the class more usable by bindings. * Misc cleanup / typo fixes / addition of links Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/752>
This commit is contained in:
Mathieu Duponchelle
parent
85763437c7
commit
12639aad34
2 changed files with 152 additions and 64 deletions
|
|
@ -46,7 +46,7 @@
|
|||
* gst_buffer_pool_set_config() updates the configuration in the pool. This can
|
||||
* fail when the configuration structure is not accepted.
|
||||
*
|
||||
* After the a pool has been configured, it can be activated with
|
||||
* After the pool has been configured, it can be activated with
|
||||
* gst_buffer_pool_set_active(). This will preallocate the configured resources
|
||||
* in the pool.
|
||||
*
|
||||
|
|
@ -59,9 +59,6 @@
|
|||
* The bufferpool can be deactivated again with gst_buffer_pool_set_active().
|
||||
* All further gst_buffer_pool_acquire_buffer() calls will return an error. When
|
||||
* all buffers are returned to the pool they will be freed.
|
||||
*
|
||||
* Use gst_object_unref() to release the reference to a bufferpool. If the
|
||||
* refcount of the pool reaches 0, the pool will be freed.
|
||||
*/
|
||||
|
||||
#include "gst_private.h"
|
||||
|
|
@ -477,7 +474,7 @@ do_set_flushing (GstBufferPool * pool, gboolean flushing)
|
|||
* @pool: a #GstBufferPool
|
||||
* @active: the new active state
|
||||
*
|
||||
* Control the active state of @pool. When the pool is inactive, new calls to
|
||||
* Controls the active state of @pool. When the pool is inactive, new calls to
|
||||
* gst_buffer_pool_acquire_buffer() will return with %GST_FLOW_FLUSHING.
|
||||
*
|
||||
* Activating the bufferpool will preallocate all resources in the pool based on
|
||||
|
|
@ -572,7 +569,7 @@ stop_failed:
|
|||
* gst_buffer_pool_is_active:
|
||||
* @pool: a #GstBufferPool
|
||||
*
|
||||
* Check if @pool is active. A pool can be activated with the
|
||||
* Checks if @pool is active. A pool can be activated with the
|
||||
* gst_buffer_pool_set_active() call.
|
||||
*
|
||||
* Returns: %TRUE when the pool is active.
|
||||
|
|
@ -633,10 +630,10 @@ wrong_config:
|
|||
* @pool: a #GstBufferPool
|
||||
* @config: (transfer full): a #GstStructure
|
||||
*
|
||||
* Set the configuration of the pool. If the pool is already configured, and
|
||||
* the configuration haven't change, this function will return %TRUE. If the
|
||||
* Sets the configuration of the pool. If the pool is already configured, and
|
||||
* the configuration hasn't changed, this function will return %TRUE. If the
|
||||
* pool is active, this method will return %FALSE and active configuration
|
||||
* will remain. Buffers allocated form this pool must be returned or else this
|
||||
* will remain. Buffers allocated from this pool must be returned or else this
|
||||
* function will do nothing and return %FALSE.
|
||||
*
|
||||
* @config is a #GstStructure that contains the configuration parameters for
|
||||
|
|
@ -727,12 +724,10 @@ have_outstanding:
|
|||
* gst_buffer_pool_get_config:
|
||||
* @pool: a #GstBufferPool
|
||||
*
|
||||
* Get a copy of the current configuration of the pool. This configuration
|
||||
* can either be modified and used for the gst_buffer_pool_set_config() call
|
||||
* or it must be freed after usage.
|
||||
* Gets a copy of the current configuration of the pool. This configuration
|
||||
* can be modified and used for the gst_buffer_pool_set_config() call.
|
||||
*
|
||||
* Returns: (transfer full): a copy of the current configuration of @pool. use
|
||||
* gst_structure_free() after usage or gst_buffer_pool_set_config().
|
||||
* Returns: (transfer full): a copy of the current configuration of @pool.
|
||||
*/
|
||||
GstStructure *
|
||||
gst_buffer_pool_get_config (GstBufferPool * pool)
|
||||
|
|
@ -754,7 +749,7 @@ static const gchar *empty_option[] = { NULL };
|
|||
* gst_buffer_pool_get_options:
|
||||
* @pool: a #GstBufferPool
|
||||
*
|
||||
* Get a %NULL terminated array of string with supported bufferpool options for
|
||||
* Gets a %NULL terminated array of string with supported bufferpool options for
|
||||
* @pool. An option would typically be enabled with
|
||||
* gst_buffer_pool_config_add_option().
|
||||
*
|
||||
|
|
@ -792,7 +787,7 @@ invalid_result:
|
|||
* @pool: a #GstBufferPool
|
||||
* @option: an option
|
||||
*
|
||||
* Check if the bufferpool supports @option.
|
||||
* Checks if the bufferpool supports @option.
|
||||
*
|
||||
* Returns: %TRUE if the buffer pool contains @option.
|
||||
*/
|
||||
|
|
@ -822,7 +817,7 @@ gst_buffer_pool_has_option (GstBufferPool * pool, const gchar * option)
|
|||
* @min_buffers: the minimum amount of buffers to allocate.
|
||||
* @max_buffers: the maximum amount of buffers to allocate or 0 for unlimited.
|
||||
*
|
||||
* Configure @config with the given parameters.
|
||||
* Configures @config with the given parameters.
|
||||
*/
|
||||
void
|
||||
gst_buffer_pool_config_set_params (GstStructure * config, GstCaps * caps,
|
||||
|
|
@ -845,7 +840,7 @@ gst_buffer_pool_config_set_params (GstStructure * config, GstCaps * caps,
|
|||
* @allocator: (nullable): a #GstAllocator
|
||||
* @params: (nullable): #GstAllocationParams
|
||||
*
|
||||
* Set the @allocator and @params on @config.
|
||||
* Sets the @allocator and @params on @config.
|
||||
*
|
||||
* One of @allocator and @params can be %NULL, but not both. When @allocator
|
||||
* is %NULL, the default allocator of the pool will use the values in @param
|
||||
|
|
@ -875,10 +870,10 @@ gst_buffer_pool_config_set_allocator (GstStructure * config,
|
|||
* @config: a #GstBufferPool configuration
|
||||
* @option: an option to add
|
||||
*
|
||||
* Enabled the option in @config. This will instruct the @bufferpool to enable
|
||||
* Enables the option in @config. This will instruct the @bufferpool to enable
|
||||
* the specified option on the buffers that it allocates.
|
||||
*
|
||||
* The supported options by @pool can be retrieved with gst_buffer_pool_get_options().
|
||||
* The options supported by @pool can be retrieved with gst_buffer_pool_get_options().
|
||||
*/
|
||||
void
|
||||
gst_buffer_pool_config_add_option (GstStructure * config, const gchar * option)
|
||||
|
|
@ -914,7 +909,7 @@ gst_buffer_pool_config_add_option (GstStructure * config, const gchar * option)
|
|||
* gst_buffer_pool_config_n_options:
|
||||
* @config: a #GstBufferPool configuration
|
||||
*
|
||||
* Retrieve the number of values currently stored in the options array of the
|
||||
* Retrieves the number of values currently stored in the options array of the
|
||||
* @config structure.
|
||||
*
|
||||
* Returns: the options array size as a #guint.
|
||||
|
|
@ -939,10 +934,10 @@ gst_buffer_pool_config_n_options (GstStructure * config)
|
|||
* @config: a #GstBufferPool configuration
|
||||
* @index: position in the option array to read
|
||||
*
|
||||
* Parse an available @config and get the option at @index of the options API
|
||||
* Parses an available @config and gets the option at @index of the options API
|
||||
* array.
|
||||
*
|
||||
* Returns: (nullable): a #gchar of the option at @index.
|
||||
* Returns: (nullable): the option at @index.
|
||||
*/
|
||||
const gchar *
|
||||
gst_buffer_pool_config_get_option (GstStructure * config, guint index)
|
||||
|
|
@ -968,7 +963,7 @@ gst_buffer_pool_config_get_option (GstStructure * config, guint index)
|
|||
* @config: a #GstBufferPool configuration
|
||||
* @option: an option
|
||||
*
|
||||
* Check if @config contains @option.
|
||||
* Checks if @config contains @option.
|
||||
*
|
||||
* Returns: %TRUE if the options array contains @option.
|
||||
*/
|
||||
|
|
@ -1001,7 +996,7 @@ gst_buffer_pool_config_has_option (GstStructure * config, const gchar * option)
|
|||
* @min_buffers: (out) (optional): the minimum amount of buffers to allocate.
|
||||
* @max_buffers: (out) (optional): the maximum amount of buffers to allocate or 0 for unlimited.
|
||||
*
|
||||
* Get the configuration values from @config.
|
||||
* Gets the configuration values from @config.
|
||||
*
|
||||
* Returns: %TRUE if all parameters could be fetched.
|
||||
*/
|
||||
|
|
@ -1027,7 +1022,7 @@ gst_buffer_pool_config_get_params (GstStructure * config, GstCaps ** caps,
|
|||
* @allocator: (out) (optional) (nullable) (transfer none): a #GstAllocator, or %NULL
|
||||
* @params: (out caller-allocates) (optional): #GstAllocationParams, or %NULL
|
||||
*
|
||||
* Get the @allocator and @params from @config.
|
||||
* Gets the @allocator and @params from @config.
|
||||
*
|
||||
* Returns: %TRUE, if the values are set.
|
||||
*/
|
||||
|
|
@ -1062,7 +1057,7 @@ gst_buffer_pool_config_get_allocator (GstStructure * config,
|
|||
* @min_buffers: the expected minimum amount of buffers to allocate.
|
||||
* @max_buffers: the expect maximum amount of buffers to allocate or 0 for unlimited.
|
||||
*
|
||||
* Validate that changes made to @config are still valid in the context of the
|
||||
* Validates that changes made to @config are still valid in the context of the
|
||||
* expected parameters. This function is a helper that can be used to validate
|
||||
* changes made by a pool to a config when gst_buffer_pool_set_config()
|
||||
* returns %FALSE. This expects that @caps haven't changed and that
|
||||
|
|
@ -1250,11 +1245,10 @@ default_reset_buffer (GstBufferPool * pool, GstBuffer * buffer)
|
|||
* @buffer: (out): a location for a #GstBuffer
|
||||
* @params: (transfer none) (allow-none): parameters.
|
||||
*
|
||||
* Acquire a buffer from @pool. @buffer should point to a memory location that
|
||||
* Acquires a buffer from @pool. @buffer should point to a memory location that
|
||||
* can hold a pointer to the new buffer.
|
||||
*
|
||||
* @params can be %NULL or contain optional parameters to influence the
|
||||
* allocation.
|
||||
* @params can contain optional parameters to influence the allocation.
|
||||
*
|
||||
* Returns: a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is
|
||||
* inactive.
|
||||
|
|
@ -1348,7 +1342,7 @@ discard:
|
|||
* @pool: a #GstBufferPool
|
||||
* @buffer: (transfer full): a #GstBuffer
|
||||
*
|
||||
* Release @buffer to @pool. @buffer should have previously been allocated from
|
||||
* Releases @buffer to @pool. @buffer should have previously been allocated from
|
||||
* @pool with gst_buffer_pool_acquire_buffer().
|
||||
*
|
||||
* This function is usually called automatically when the last ref on @buffer
|
||||
|
|
@ -1387,7 +1381,7 @@ gst_buffer_pool_release_buffer (GstBufferPool * pool, GstBuffer * buffer)
|
|||
* @pool: a #GstBufferPool
|
||||
* @flushing: whether to start or stop flushing
|
||||
*
|
||||
* Enable or disable the flushing state of a @pool without freeing or
|
||||
* Enables or disables the flushing state of a @pool without freeing or
|
||||
* allocating buffers.
|
||||
*
|
||||
* Since: 1.4
|
||||
|
|
|
|||
|
|
@ -98,6 +98,8 @@ struct _GstBufferPoolAcquireParams {
|
|||
|
||||
/**
|
||||
* GstBufferPool:
|
||||
* @object: the parent structure
|
||||
* @flushing: whether the pool is currently gathering back outstanding buffers
|
||||
*
|
||||
* The structure of a #GstBufferPool. Use the associated macros to access the public
|
||||
* variables.
|
||||
|
|
@ -117,58 +119,150 @@ struct _GstBufferPool {
|
|||
/**
|
||||
* GstBufferPoolClass:
|
||||
* @object_class: Object parent class
|
||||
* @get_options: get a list of options supported by this pool
|
||||
* @set_config: apply the bufferpool configuration. The default configuration
|
||||
* will parse the default config parameters
|
||||
* @start: start the bufferpool. The default implementation will preallocate
|
||||
* min-buffers buffers and put them in the queue
|
||||
* @stop: stop the bufferpool. the default implementation will free the
|
||||
* preallocated buffers. This function is called when all the buffers are
|
||||
* returned to the pool.
|
||||
* @acquire_buffer: get a new buffer from the pool. The default implementation
|
||||
* will take a buffer from the queue and optionally wait for a buffer to
|
||||
* be released when there are no buffers available.
|
||||
* @alloc_buffer: allocate a buffer. the default implementation allocates
|
||||
* buffers from the configured memory allocator and with the configured
|
||||
* parameters. All metadata that is present on the allocated buffer will
|
||||
* be marked as #GST_META_FLAG_POOLED and #GST_META_FLAG_LOCKED and will
|
||||
* not be removed from the buffer in @reset_buffer. The buffer should
|
||||
* have the GST_BUFFER_FLAG_TAG_MEMORY cleared.
|
||||
* @reset_buffer: reset the buffer to its state when it was freshly allocated.
|
||||
* The default implementation will clear the flags, timestamps and
|
||||
* will remove the metadata without the #GST_META_FLAG_POOLED flag (even
|
||||
* the metadata with #GST_META_FLAG_LOCKED). If the
|
||||
* #GST_BUFFER_FLAG_TAG_MEMORY was set, this function can also try to
|
||||
* restore the memory and clear the #GST_BUFFER_FLAG_TAG_MEMORY again.
|
||||
* @release_buffer: release a buffer back in the pool. The default
|
||||
* implementation will put the buffer back in the queue and notify any
|
||||
* blocking acquire_buffer calls when the #GST_BUFFER_FLAG_TAG_MEMORY
|
||||
* is not set on the buffer. If #GST_BUFFER_FLAG_TAG_MEMORY is set, the
|
||||
* buffer will be freed with @free_buffer.
|
||||
* @free_buffer: free a buffer. The default implementation unrefs the buffer.
|
||||
* @flush_start: enter the flushing state. (Since: 1.4)
|
||||
* @flush_stop: leave the flushign state. (Since: 1.4)
|
||||
*
|
||||
* The GstBufferPool class.
|
||||
* The #GstBufferPool class.
|
||||
*/
|
||||
struct _GstBufferPoolClass {
|
||||
GstObjectClass object_class;
|
||||
|
||||
/*< public >*/
|
||||
|
||||
/**
|
||||
* GstBufferPoolClass::get_options:
|
||||
* @pool: the #GstBufferPool
|
||||
*
|
||||
* Get a list of options supported by this pool
|
||||
*
|
||||
* Returns: (array zero-terminated=1) (transfer none): a %NULL terminated array
|
||||
* of strings.
|
||||
*/
|
||||
const gchar ** (*get_options) (GstBufferPool *pool);
|
||||
|
||||
/**
|
||||
* GstBufferPoolClass::set_config:
|
||||
* @pool: the #GstBufferPool
|
||||
* @config: the required configuration
|
||||
*
|
||||
* Apply the bufferpool configuration. The default configuration will parse
|
||||
* the default config parameters.
|
||||
*
|
||||
* Returns: whether the configuration could be set.
|
||||
*/
|
||||
gboolean (*set_config) (GstBufferPool *pool, GstStructure *config);
|
||||
|
||||
/**
|
||||
* GstBufferPoolClass::start:
|
||||
* @pool: the #GstBufferPool
|
||||
*
|
||||
* Start the bufferpool. The default implementation will preallocate
|
||||
* min-buffers buffers and put them in the queue.
|
||||
*
|
||||
* Returns: whether the pool could be started.
|
||||
*/
|
||||
gboolean (*start) (GstBufferPool *pool);
|
||||
|
||||
/**
|
||||
* GstBufferPoolClass::stop:
|
||||
* @pool: the #GstBufferPool
|
||||
*
|
||||
* Stop the bufferpool. the default implementation will free the
|
||||
* preallocated buffers. This function is called when all the buffers are
|
||||
* returned to the pool.
|
||||
*
|
||||
* Returns: whether the pool could be stopped.
|
||||
*/
|
||||
gboolean (*stop) (GstBufferPool *pool);
|
||||
|
||||
/**
|
||||
* GstBufferPoolClass::acquire_buffer:
|
||||
* @pool: the #GstBufferPool
|
||||
* @buffer: (out): a location for a #GstBuffer
|
||||
* @params: (transfer none) (allow-none): parameters.
|
||||
*
|
||||
* Get a new buffer from the pool. The default implementation
|
||||
* will take a buffer from the queue and optionally wait for a buffer to
|
||||
* be released when there are no buffers available.
|
||||
*
|
||||
* Returns: a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is
|
||||
* inactive.
|
||||
*/
|
||||
GstFlowReturn (*acquire_buffer) (GstBufferPool *pool, GstBuffer **buffer,
|
||||
GstBufferPoolAcquireParams *params);
|
||||
|
||||
/**
|
||||
* GstBufferPoolClass::alloc_buffer:
|
||||
* @pool: the #GstBufferPool
|
||||
* @buffer: (out): a location for a #GstBuffer
|
||||
* @params: (transfer none) (allow-none): parameters.
|
||||
*
|
||||
* Allocate a buffer. the default implementation allocates
|
||||
* buffers from the configured memory allocator and with the configured
|
||||
* parameters. All metadata that is present on the allocated buffer will
|
||||
* be marked as #GST_META_FLAG_POOLED and #GST_META_FLAG_LOCKED and will
|
||||
* not be removed from the buffer in #GstBufferPoolClass::reset_buffer.
|
||||
* The buffer should have the #GST_BUFFER_FLAG_TAG_MEMORY cleared.
|
||||
*
|
||||
* Returns: a #GstFlowReturn to indicate whether the allocation was
|
||||
* successful.
|
||||
*/
|
||||
GstFlowReturn (*alloc_buffer) (GstBufferPool *pool, GstBuffer **buffer,
|
||||
GstBufferPoolAcquireParams *params);
|
||||
|
||||
/**
|
||||
* GstBufferPoolClass::reset_buffer:
|
||||
* @pool: the #GstBufferPool
|
||||
* @buffer: the #GstBuffer to reset
|
||||
*
|
||||
* Reset the buffer to its state when it was freshly allocated.
|
||||
* The default implementation will clear the flags, timestamps and
|
||||
* will remove the metadata without the #GST_META_FLAG_POOLED flag (even
|
||||
* the metadata with #GST_META_FLAG_LOCKED). If the
|
||||
* #GST_BUFFER_FLAG_TAG_MEMORY was set, this function can also try to
|
||||
* restore the memory and clear the #GST_BUFFER_FLAG_TAG_MEMORY again.
|
||||
*/
|
||||
void (*reset_buffer) (GstBufferPool *pool, GstBuffer *buffer);
|
||||
|
||||
/**
|
||||
* GstBufferPoolClass::release_buffer:
|
||||
* @pool: the #GstBufferPool
|
||||
* @buffer: the #GstBuffer to release
|
||||
*
|
||||
* Release a buffer back in the pool. The default implementation
|
||||
* will put the buffer back in the queue and notify any
|
||||
* blocking #GstBufferPoolClass::acquire_buffer calls when the
|
||||
* #GST_BUFFER_FLAG_TAG_MEMORY is not set on the buffer.
|
||||
* If #GST_BUFFER_FLAG_TAG_MEMORY is set, the buffer will be freed with
|
||||
* #GstBufferPoolClass::free_buffer.
|
||||
*/
|
||||
void (*release_buffer) (GstBufferPool *pool, GstBuffer *buffer);
|
||||
|
||||
/**
|
||||
* GstBufferPoolClass::free_buffer:
|
||||
* @pool: the #GstBufferPool
|
||||
* @buffer: the #GstBuffer to free
|
||||
*
|
||||
* Free a buffer. The default implementation unrefs the buffer.
|
||||
*/
|
||||
void (*free_buffer) (GstBufferPool *pool, GstBuffer *buffer);
|
||||
|
||||
/**
|
||||
* GstBufferPoolClass::flush_start:
|
||||
* @pool: the #GstBufferPool
|
||||
*
|
||||
* Enter the flushing state.
|
||||
*
|
||||
* Since: 1.4
|
||||
*/
|
||||
void (*flush_start) (GstBufferPool *pool);
|
||||
|
||||
/**
|
||||
* GstBufferPoolClass::flush_stop:
|
||||
* @pool: the #GstBufferPool
|
||||
*
|
||||
* Leave the flushing state.
|
||||
*
|
||||
* Since: 1.4
|
||||
*/
|
||||
void (*flush_stop) (GstBufferPool *pool);
|
||||
|
||||
/*< private >*/
|
||||
|
|
|
|||
Loading…
Reference in a new issue