From 2dca02869bf2377258c63c4a79d7e2d05da4874a Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Fri, 4 Mar 2011 16:05:44 +0100 Subject: [PATCH] docs: update bufferpool draft --- docs/design/draft-bufferpool.txt | 103 ++++++++++++------------------- 1 file changed, 40 insertions(+), 63 deletions(-) diff --git a/docs/design/draft-bufferpool.txt b/docs/design/draft-bufferpool.txt index 72d3a617a8..4061ee7675 100644 --- a/docs/design/draft-bufferpool.txt +++ b/docs/design/draft-bufferpool.txt @@ -72,9 +72,9 @@ GstBufferPool The bufferpool object manages a list of buffers with the same properties such as size, padding and alignment. - The bufferpool has two states: flushing and non-flushing. In the flushing + The bufferpool has two states: active and inactive. In the in-active state, the bufferpool can be configured with the required allocation - preferences. In the non-flushing state, buffers can be retrieved from and + preferences. In the active state, buffers can be retrieved from and returned to the pool. The default implementation of the bufferpool is able to allocate buffers @@ -92,37 +92,16 @@ GstBufferPool GstPad ------ - The GstPad has a method to query a GstBufferPool and its configuration. + A GstPad can query a new bufferpool from a peer element withe the BUFFERPOOL + query. - GstBufferPool * gst_pad_query_bufferpool (GstPad * pad); - - This function can return a handle to a bufferpool object or NULL when no - bufferpool object can be provided by the pad. - - This function should return a bufferpool object with the - GstBufferPoolConfig set to the desired parameters of the buffers that will be - handled by the given pad. This function can only be called on a sinkpad and - will usually be called by the peer srcpad with the convenience method: - - GstBufferPool * gst_pad_peer_query_bufferpool (GstPad * pad); - - - There is also a new function to configure a bufferpool on a pad and its peer - pad: - - gboolean gst_pad_set_bufferpool (GstPad * pad, GstBufferPool *pool); - - This function is to inform a pad and its peer pad that a bufferpool should - be used for allocation (on source pads) and that bufferpool is used by the - upstream element (on sinkpads). - - The currently configured bufferpool can be retrieved with: - - GstBufferPool * gst_pad_get_bufferpool (GstPad * pad); - - New functions exist to configure these bufferpool functions on pads: - gst_pad_set_querybufferpool_function and gst_pad_set_setbufferpool_function. + The returned bufferpool object can then be configured with the desired + parameters of the buffers it should provide. + When the bufferpool is configured, it must be pushed downstream with the + BUFFERPOOL event. This is to inform a pad and its peer pad that a bufferpool + should be used for allocation (on source pads) and that bufferpool is used + by the upstream element (on sinkpads). negotiating pool and config --------------------------- @@ -139,13 +118,13 @@ The algorithm for doing this is rougly like this: * prepare an output buffer but has no pool yet */ /* first get the pool from the downstream peer */ - pool = gst_pad_peer_query_bufferpool (srcpad); + res = gst_pad_query_bufferpool (srcpad, &pool); if (pool != NULL) { GstBufferPoolConfig config; /* clear the pool so that we can reconfigure it */ - gst_buffer_pool_set_flushing (pool, TRUE); + gst_buffer_pool_set_active (pool, FALSE); do { /* get the config */ @@ -163,8 +142,8 @@ The algorithm for doing this is rougly like this: while (!gst_buffer_pool_set_config (pool, &config)); /* we managed to update the config, all is fine now */ - /* set the pool to non-flushing to make it allocate things */ - gst_buffer_pool_set_flushing (pool, FALSE); + /* set the pool to active to make it allocate things */ + gst_buffer_pool_set_active (pool, TRUE); } if (pool == NULL) { @@ -173,7 +152,7 @@ The algorithm for doing this is rougly like this: } /* now set the pool on this pad and the peer pad */ - gst_pad_set_bufferpool (pad, pool); + gst_pad_push_event (pad, gst_event_new_bufferpool (pool)); Negotiation is the same for both push and pull mode. In the case of pull @@ -199,7 +178,7 @@ Allocating from pool Since all the buffers allocated from the pool keep a reference to the pool, when nothing else is holding a refcount to the pool, it will be finalized when all the buffers from the pool are unreffed. By setting the pool to - the flushing state we can drain all buffers from the pool. + the inactive state we can drain all buffers from the pool. Renegotiation @@ -251,15 +230,14 @@ Shutting down ------------- In push mode, a source pad is responsible for setting the pool to the - flushing state when streaming stops. The flush will unblock any pending + inactive state when streaming stops. The inactive state will unblock any pending allocations so that the element can shut down. - In pull mode, the sink element should set the pool to the flushing state when + In pull mode, the sink element should set the pool to the inactive state when shutting down so that the peer _get_range() function can unblock. - In the flushing state, all the buffers that are returned to the pool will - be automatically freed by the pool and new allocations will fail. - + In the inactive state, all the buffers that are returned to the pool will + automatically be freed by the pool and new allocations will fail. @@ -274,9 +252,9 @@ Use cases First it will negotiate a suitable format with downstream according to the normal rules. - Then it does gst_pad_peer_query_bufferpool() which triggers the querybufferpool - function installed on the xvimagesink pad. This bufferpool is currently in - the flushing state and thus has no buffers allocated. + Then it does gst_pad_query_bufferpool() which triggers the BUFFERPOOL query. + This bufferpool is currently in the inactive state and thus has no buffers + allocated. videotestsrc gets the configuration of the bufferpool object. This configuration lists the desired configuration of the xvimagesink, which can @@ -286,11 +264,10 @@ Use cases set the min buffers to 1 and the size of the desired buffers. It then updates the bufferpool configuration with the new properties. - When the configuration is successfully updated, videotestsrc sets the - bufferpool on its source pad, this will also set the pool on the peer - sinkpad. + When the configuration is successfully updated, videotestsrc pushes the + bufferpool downstream with the BUFFERPOOL event. - It then sets the bufferpool to the non-flushing state. This preallocates + It then sets the bufferpool to the active state. This preallocates the buffers in the pool (if needed). This operation can fail when there is not enough memory available. Since the bufferpool is provided by xvimagesink, it will allocate buffers backed by an XvImage and pointing @@ -301,10 +278,10 @@ Use cases out to xvimagesink. xvimagesink can know that the buffer originated from its pool by following - the pool member or checking the specific GType of it GstBuffer subclass. - It might need to get the parent buffer first in case of subbuffers. + the pool member. It might need to get the parent buffer first in case of + subbuffers. - when shutting down, videotestsrc will set the pool to the flushing state, + when shutting down, videotestsrc will set the pool to the inactive state, this will cause further allocations to fail and currently allocated buffers to be freed. videotestsrc will then free the pool and stop streaming. @@ -315,7 +292,7 @@ Use cases 3 video buffers. Again videotestsrc will have to negotiate a bufferpool with the peer - element. For this it will perform gst_pad_peer_query_bufferpool() which + element. For this it will perform gst_pad_query_bufferpool() which queue will proxy to its downstream peer element. The bufferpool returned from myvideosink will have a max_buffers set to 3. @@ -325,12 +302,12 @@ Use cases The bufferpool of myvideosink will then be configured with the size of the buffers for the negotiated format and according to the padding and alignment - rules. When videotestsrc sets the pool to non-flushing, the 3 video + rules. When videotestsrc sets the pool to active, the 3 video buffers will be preallocated in the pool. - The pool will then be configured on the src of videotestsrc and the - sinkpad of the queue. The queue will proxy the setbufferpool method to - its srcpad, which finally configures the pool all the way to the sink. + The pool will then be configured to downstream elements with the BUFFERPOOL + event. The queue will proxy the BUFFERPOOL event to its srcpad, which + finally configures the pool all the way to the sink. videotestsrc acquires a buffer from the configured pool on its srcpad and pushes this into the queue. When the videotestsrc has acquired and pushed @@ -347,7 +324,7 @@ Use cases in the bufferpool. When shutting down, videotestsrc will first set the bufferpool on the srcpad - to flushing. This causes any pending (blocked) acquire to return with a + to inactive. This causes any pending (blocked) acquire to return with a WRONG_STATE result and causes the streaming thread to pause. @@ -372,11 +349,11 @@ Use cases Before pushing the next buffer, myvideodecoder would renegotiate a new bufferpool. To do this, it performs the usual bufferpool negotiation algorithm. If it can obtain and configure a new bufferpool from downstream, - it sets its own (old) pool to flushing and unrefs it. This will eventually + it sets its own (old) pool to inactive and unrefs it. This will eventually drain and unref the old bufferpool. The new bufferpool is set as the new bufferpool for the srcpad and sinkpad - of the queue and set to the non-flushing state. + of the queue and set to the active state. 4) .. ! myvideodecoder ! queue ! myvideosink @@ -389,9 +366,9 @@ Use cases When myvideodecoder needs to get the bigger buffer, it starts the negotiation of a new bufferpool. It queries a bufferpool from downstream, reconfigures it with the new configuration (which includes the bigger buffer - size), it sets the bufferpool to non-flushing and sets the bufferpool as - the new pool for the srcpad and its peer. This automatically flushes the - old pool and unrefs it, which causes the old format to drain. + size), it sets the bufferpool to active and pushes the bufferpool downstream. + This automatically inactivates the old pool and unrefs it, which causes the + old format to drain. It then uses the new bufferpool for allocating new buffers of the new dimension.