mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-01-11 18:05:37 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs: update bufferpool draft

Browse source
This commit is contained in:
Wim Taymans 2011-03-04 16:05:44 +01:00
parent b11ede5984
commit 2dca02869b
1 changed files with 40 additions and 63 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

103
docs/design/draft-bufferpool.txt
View file

@ -72,9 +72,9 @@ GstBufferPool
The bufferpool object manages a list of buffers with the same properties such The bufferpool object manages a list of buffers with the same properties such
as size, padding and alignment. 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 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. returned to the pool.
The default implementation of the bufferpool is able to allocate buffers The default implementation of the bufferpool is able to allocate buffers
@ -92,37 +92,16 @@ GstBufferPool
GstPad 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); The returned bufferpool object can then be configured with the desired
parameters of the buffers it should provide.
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.
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 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 */ * prepare an output buffer but has no pool yet */
/* first get the pool from the downstream peer */ /* 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) { if (pool != NULL) {
GstBufferPoolConfig config; GstBufferPoolConfig config;
/* clear the pool so that we can reconfigure it */ /* clear the pool so that we can reconfigure it */
gst_buffer_pool_set_flushing (pool, TRUE); gst_buffer_pool_set_active (pool, FALSE);
do { do {
/* get the config */ /* get the config */
@ -163,8 +142,8 @@ The algorithm for doing this is rougly like this:
while (!gst_buffer_pool_set_config (pool, &config)); while (!gst_buffer_pool_set_config (pool, &config));
/* we managed to update the config, all is fine now */ /* we managed to update the config, all is fine now */
/* set the pool to non-flushing to make it allocate things */ /* set the pool to active to make it allocate things */
gst_buffer_pool_set_flushing (pool, FALSE); gst_buffer_pool_set_active (pool, TRUE);
} }
if (pool == NULL) { 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 */ /* 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 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, 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 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 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 Renegotiation
@ -251,15 +230,14 @@ Shutting down
------------- -------------
In push mode, a source pad is responsible for setting the pool to the 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. 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. 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 In the inactive state, all the buffers that are returned to the pool will
be automatically freed by the pool and new allocations will fail. 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 First it will negotiate a suitable format with downstream according to the
normal rules. normal rules.
Then it does gst_pad_peer_query_bufferpool() which triggers the querybufferpool Then it does gst_pad_query_bufferpool() which triggers the BUFFERPOOL query.
function installed on the xvimagesink pad. This bufferpool is currently in This bufferpool is currently in the inactive state and thus has no buffers
the flushing state and thus has no buffers allocated. allocated.
videotestsrc gets the configuration of the bufferpool object. This videotestsrc gets the configuration of the bufferpool object. This
configuration lists the desired configuration of the xvimagesink, which can 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 set the min buffers to 1 and the size of the desired buffers. It then
updates the bufferpool configuration with the new properties. updates the bufferpool configuration with the new properties.
When the configuration is successfully updated, videotestsrc sets the When the configuration is successfully updated, videotestsrc pushes the
bufferpool on its source pad, this will also set the pool on the peer bufferpool downstream with the BUFFERPOOL event.
sinkpad.
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 the buffers in the pool (if needed). This operation can fail when there
is not enough memory available. Since the bufferpool is provided by is not enough memory available. Since the bufferpool is provided by
xvimagesink, it will allocate buffers backed by an XvImage and pointing xvimagesink, it will allocate buffers backed by an XvImage and pointing
@ -301,10 +278,10 @@ Use cases
out to xvimagesink. out to xvimagesink.
xvimagesink can know that the buffer originated from its pool by following xvimagesink can know that the buffer originated from its pool by following
the pool member or checking the specific GType of it GstBuffer subclass. the pool member. It might need to get the parent buffer first in case of
It might need to get the parent buffer first in case of subbuffers. 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 this will cause further allocations to fail and currently allocated buffers
to be freed. videotestsrc will then free the pool and stop streaming. to be freed. videotestsrc will then free the pool and stop streaming.
@ -315,7 +292,7 @@ Use cases
3 video buffers. 3 video buffers.
Again videotestsrc will have to negotiate a bufferpool with the peer 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. queue will proxy to its downstream peer element.
The bufferpool returned from myvideosink will have a max_buffers set to 3. 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 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 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. buffers will be preallocated in the pool.
The pool will then be configured on the src of videotestsrc and the The pool will then be configured to downstream elements with the BUFFERPOOL
sinkpad of the queue. The queue will proxy the setbufferpool method to event. The queue will proxy the BUFFERPOOL event to its srcpad, which
its srcpad, which finally configures the pool all the way to the sink. finally configures the pool all the way to the sink.
videotestsrc acquires a buffer from the configured pool on its srcpad and videotestsrc acquires a buffer from the configured pool on its srcpad and
pushes this into the queue. When the videotestsrc has acquired and pushed pushes this into the queue. When the videotestsrc has acquired and pushed
@ -347,7 +324,7 @@ Use cases
in the bufferpool. in the bufferpool.
When shutting down, videotestsrc will first set the bufferpool on the srcpad 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. 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 Before pushing the next buffer, myvideodecoder would renegotiate a new
bufferpool. To do this, it performs the usual bufferpool negotiation bufferpool. To do this, it performs the usual bufferpool negotiation
algorithm. If it can obtain and configure a new bufferpool from downstream, 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. drain and unref the old bufferpool.
The new bufferpool is set as the new bufferpool for the srcpad and sinkpad 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 4) .. ! myvideodecoder ! queue ! myvideosink
@ -389,9 +366,9 @@ Use cases
When myvideodecoder needs to get the bigger buffer, it starts the When myvideodecoder needs to get the bigger buffer, it starts the
negotiation of a new bufferpool. It queries a bufferpool from downstream, negotiation of a new bufferpool. It queries a bufferpool from downstream,
reconfigures it with the new configuration (which includes the bigger buffer reconfigures it with the new configuration (which includes the bigger buffer
size), it sets the bufferpool to non-flushing and sets the bufferpool as size), it sets the bufferpool to active and pushes the bufferpool downstream.
the new pool for the srcpad and its peer. This automatically flushes the This automatically inactivates the old pool and unrefs it, which causes the
old pool and unrefs it, which causes the old format to drain. old format to drain.
It then uses the new bufferpool for allocating new buffers of the new It then uses the new bufferpool for allocating new buffers of the new
dimension. dimension.