From 46f6cbe5fc0a9ba4fe0e59884396480859f742e4 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Tue, 2 Oct 2012 12:49:17 +0200 Subject: [PATCH] pwg: add bufferpool docs --- docs/pwg/advanced-allocation.xml | 137 ++++++++++++++++++++++++++++++- 1 file changed, 135 insertions(+), 2 deletions(-) diff --git a/docs/pwg/advanced-allocation.xml b/docs/pwg/advanced-allocation.xml index a50184f1ed..f368e7d380 100644 --- a/docs/pwg/advanced-allocation.xml +++ b/docs/pwg/advanced-allocation.xml @@ -518,15 +518,148 @@ gst_buffer_add_my_example_meta (GstBuffer *buffer, to the buffers in the pool or such as enabling specific padding on the memory in the buffers. + + A Bufferpool can be inactivate and active. In the inactive state, + you can configure the pool. In the active state, you can't change + the configuration anymore but you can acquire and release buffers + from/to the pool. + + + In the following sections we take a look at how you can use + a bufferpool. + GstBufferPool API example - WRITEME + Many different bufferpool implementations can exist; they are all + subclasses of the base class GstBufferPool. + For this example, we will assume we somehow have access to a + bufferpool, either because we created it ourselves or because + we were given one as a result of the ALLOCATION query as we will + see below. + + + The bufferpool is initially in the inactive state so that we can + configure it. Trying to configure a bufferpool that is not in the + inactive state will fail. Likewise, trying to activate a bufferpool + that is not configured will fail. + + + + + + The configuration of the bufferpool is maintained in a generic + GstStructure that can be obtained with + gst_buffer_pool_get_config(). Convenience + methods exist to get and set the configuration options in this + structure. After updating the structure, it is set as the current + configuration in the bufferpool again with + gst_buffer_pool_set_config(). + + + The following options can be configured on a bufferpool: + + + + + The caps of the buffers to allocate. + + + + + The size of the buffers. This is the suggested size of the + buffers in the pool. The pool might decide to allocate larger + buffers to add padding. + + + + + The minimum and maximum amount of buffers in the pool. When + minimum is set to > 0, the bufferpool will pre-allocate this + amount of buffers. When maximum is not 0, the bufferpool + will allocate up to maximum amount of buffers. + + + + + The allocator and parameters to use. Some bufferpools might + ignore the allocator and use its internal one. + + + + + Other arbitrary bufferpool options identified with a string. + a bufferpool lists the supported options with + gst_buffer_pool_get_options() and you + can ask if an option is supported with + gst_buffer_pool_has_option(). The option + can be enabled by adding it to the configuration structure + with gst_buffer_pool_config_add_option (). + These options are used to enable things like letting the + pool set metadata on the buffers or to add extra configuration + options for padding, for example. + + + + + After the configuration is set on the bufferpool, the pool can + be activated with + gst_buffer_pool_set_active (pool, TRUE). From + that point on you can use + gst_buffer_pool_acquire_buffer () to retrieve + a buffer from the pool, like this: + + + + + + It is important to check the return value of the acquire function + because it is possible that it fails: When your + element shuts down, it will deactivate the bufferpool and then + all calls to acquire will return GST_FLOW_FLUSHNG. + + + All buffers that are acquired from the pool will have their pool + member set to the original pool. When the last ref is decremented + on the buffer, &GStreamer; will automatically call + gst_buffer_pool_release_buffer() to release + the buffer back to the pool. You (or any other downstream element) + don't need to know if a buffer came from a pool, you can just + unref it. - + Implementing a new GstBufferPool WRITEME