4 This document details the design of how buffers are be allocated and
7 Bufferpools increases performance by reducing allocation overhead and
8 improving possibilities to implement zero-copy memory transfer.
10 Together with the ALLOCATION query, elements can negotiate allocation properties
11 and bufferpools between themselves. This also allows elements to negotiate
12 buffer metadata between themselves.
17 - Provide a GstBufferPool base class to help the efficient implementation of a
18 list of reusable GstBuffer objects.
20 - Let upstream elements initiate the negotiation of a bufferpool and it
21 configuration. Allow downstream elements provide bufferpool properties and/or
22 a bufferpool. This includes the following properties:
24 * have minimum and maximum amount of buffers with the option of
25 preallocating buffers.
26 * alignment and padding support
28 * arbitrary extra options
30 - Integrate with dynamic caps renegotiation.
32 - Notify upstream element of new bufferpool availability. This is important
33 when a new element, that can provide a bufferpool, is dynamically linked
40 The bufferpool object manages a list of buffers with the same properties such
41 as size, padding and alignment.
43 The bufferpool has two states: active and inactive. In the in-active
44 state, the bufferpool can be configured with the required allocation
45 preferences. In the active state, buffers can be retrieved from and
48 The default implementation of the bufferpool is able to allocate buffers
49 from main memory with arbitrary alignment and padding/prefix.
51 Custom implementations of the bufferpool can override the allocation and
52 free algorithms of the buffers from the pool. This should allow for
53 different allocation strategies such as using shared memory or hardware
60 After a particular media format has been negotiated between two pads (using the
61 CAPS event), they must agree on how to allocate buffers.
63 The srcpad will always take the initiative to negotiate the allocation
64 properties. It starts with creating a GST_QUERY_ALLOCATION with the negotiated
67 The srcpad can set the need-pool flag to TRUE in the query to optionally make the
68 peer pad allocate a bufferpool.
70 It will then inspect the returned results and configure the returned pool or
71 create a new pool with the returned properties when needed.
73 Buffers are then allocated by the srcpad from the negotiated pool and pushed to
74 the peer pad as usual.
76 The allocation query can also return an allocator name when the buffers are of
77 different sizes and can't be allocated from a pool.
83 The allocation query has the following fields:
85 (in) "caps", GST_TYPE_CAPS
86 - the caps that was negotiated
88 (in) "need-pool", G_TYPE_BOOLEAN
89 - if a GstBufferPool is requested
91 (out) "size", G_TYPE_UINT
92 - the total size of the buffer memory. This size is set to 0 when the
93 buffers are of variable size.
95 (out) "min-buffers", G_TYPE_UINT
96 - the minimum amount of buffers to allocate
98 (out) "max-buffers", G_TYPE_UINT
99 - the maximum amount of buffers to allocate
101 (out) "prefix", G_TYPE_UINT
102 - the prefix of the buffer memory
104 (out) "align", G_TYPE_UINT
105 - the aligment of the memory in the buffers, the alignment will be applied
106 to the prefix. The aligment is expressed as a value ((1 << N) - 1).
107 Alignment will be done on multiples of (1 << N).
109 (out) "pool", GST_TYPE_BUFFER_POOL
110 - a buffer pool when need-pool was TRUE and the peer can provide a pool.
111 This pool is inactive and can be configured when needed.
113 (out) "metadata", G_TYPE_ARRAY of GType
114 - an array of metadata API types that can be accepted.
116 (out) "allocator", G_TYPE_ARRAY of GstAllocator *
117 - an array of allocators that can be used.
123 Buffers are allocated from the pool of a pad:
125 res = gst_buffer_pool_acquire_buffer (pool, &buffer, ¶ms);
127 A GstBuffer that is allocated from the pool will always be writable (have a
128 refcount of 1) and it will also have its pool member point to the GstBufferPool
129 that created the buffer.
131 Buffers are refcounted in the usual way. When the refcount of the buffer
132 reaches 0, the buffer is automatically returned to the pool.
134 Since all the buffers allocated from the pool keep a reference to the pool,
135 when nothing else is holding a refcount to the pool, it will be finalized
136 when all the buffers from the pool are unreffed. By setting the pool to
137 the inactive state we can drain all buffers from the pool.
139 When the pool is in the inactive state, gst_buffer_pool_acquire_buffer() will
140 return GST_FLOW_WRONG_STATE immediately.
142 Extra parameters can be given to the gst_buffer_pool_acquire_buffer() method to
143 influence the allocation decision. GST_BUFFER_POOL_FLAG_KEY_UNIT and
144 GST_BUFFER_POOL_FLAG_DISCONT serve as hints.
146 When the bufferpool is configured with a maximum number of buffers, allocation
147 will block when all buffers are outstanding until a buffer is returned to the
148 pool. This behaviour can be changed by specifying the
149 GST_BUFFER_POOL_FLAG_DONTWAIT flag in the parameters. With this flag set,
150 allocation will return GST_FLOW_EOS when the pool is empty.
156 Renegotiation of the bufferpool might need to be performed when the
157 configuration of the pool changes. Changes can be in the buffer size (because
158 of a caps change), alignment or number of buffers.
162 When the upstream element wants to negotiate a new format, it might need
163 to renegotiate a new bufferpool configuration with the downstream element.
164 This can, for example, happen when the buffer size changes.
166 We can not just reconfigure the existing bufferpool because there might
167 still be outstanding buffers from the pool in the pipeline. Therefore we
168 need to create a new bufferpool for the new configuration while we let the
171 Implementations can choose to reuse the same bufferpool object and wait for
172 the drain to finish before reconfiguring the pool.
174 The element that wants to renegotiate a new bufferpool uses exactly the same
175 algorithm as when it first started. It will negotiate caps first then use the
176 ALLOCATION query to get and configure the new pool.
180 When a downstream element wants to negotiate a new format, it will send a
181 RECONFIGURE event upstream. This instructs upstream to renegotiate both
182 the format and the bufferpool when needed.
184 A pipeline reconfiguration is when new elements are added or removed from
185 the pipeline or when the topology of the pipeline changes. Pipeline
186 reconfiguration also triggers possible renegotiation of the bufferpool and
189 A RECONFIGURE event tags each pad it travels on as needing reconfiguration.
190 The next buffer allocation will then require the renegotiation or
191 reconfiguration of a pool.
197 In push mode, a source pad is responsible for setting the pool to the
198 inactive state when streaming stops. The inactive state will unblock any pending
199 allocations so that the element can shut down.
201 In pull mode, the sink element should set the pool to the inactive state when
202 shutting down so that the peer _get_range() function can unblock.
204 In the inactive state, all the buffers that are returned to the pool will
205 automatically be freed by the pool and new allocations will fail.
211 1) videotestsrc ! xvimagesink
213 Before videotestsrc can output a buffer, it needs to negotiate caps and
214 a bufferpool with the downstream peer pad.
216 First it will negotiate a suitable format with downstream according to the
217 normal rules. It will send a CAPS event downstream with the negotiated
220 Then it does an ALLOCATION query. It will use the returned bufferpool or
221 configures its own bufferpool with the returned parameters. The bufferpool is
222 initially in the inactive state.
224 The ALLOCATION query lists the desired configuration of the downstream
225 xvimagesink, which can have specific alignment and/or min/max amount of
228 videotestsrc updates the configuration of the bufferpool, it will likely
229 set the min buffers to 1 and the size of the desired buffers. It then
230 updates the bufferpool configuration with the new properties.
232 When the configuration is successfully updated, videotestsrc sets the
233 bufferpool to the active state. This preallocates the buffers in the pool
234 (if needed). This operation can fail when there is not enough memory
235 available. Since the bufferpool is provided by xvimagesink, it will allocate
236 buffers backed by an XvImage and pointing to shared memory with the X server.
238 If the bufferpool is successfully activated, videotestsrc can acquire a
239 buffer from the pool, fill in the data and push it out to xvimagesink.
241 xvimagesink can know that the buffer originated from its pool by following
244 when shutting down, videotestsrc will set the pool to the inactive state,
245 this will cause further allocations to fail and currently allocated buffers
246 to be freed. videotestsrc will then free the pool and stop streaming.
249 2) videotestsrc ! queue ! myvideosink
251 In this second use case we have a videosink that can at most allocate
254 Again videotestsrc will have to negotiate a bufferpool with the peer
255 element. For this it will perform the ALLOCATION query which
256 queue will proxy to its downstream peer element.
258 The bufferpool returned from myvideosink will have a max_buffers set to 3.
259 queue and videotestsrc can operate with this upper limit because none of
260 those elements require more than that amount of buffers for temporary
263 The bufferpool of myvideosink will then be configured with the size of the
264 buffers for the negotiated format and according to the padding and alignment
265 rules. When videotestsrc sets the pool to active, the 3 video
266 buffers will be preallocated in the pool.
268 videotestsrc acquires a buffer from the configured pool on its srcpad and
269 pushes this into the queue. When the videotestsrc has acquired and pushed
270 3 frames, the next call to gst_buffer_pool_acquire_buffer() will block
271 (assuming the GST_BUFFER_POOL_FLAG_DONTWAIT is not specified).
273 When the queue has pushed out a buffer and the sink has rendered it, the
274 refcount of the buffer reaches 0 and the buffer is recycled in the pool.
275 This will wake up the videotestsrc that was blocked, waiting for more
276 buffers and will make it produce the next buffer.
278 In this setup, there are at most 3 buffers active in the pipeline and
279 the videotestsrc is rate limited by the rate at which buffers are recycled
282 When shutting down, videotestsrc will first set the bufferpool on the srcpad
283 to inactive. This causes any pending (blocked) acquire to return with a
284 WRONG_STATE result and causes the streaming thread to pause.
287 3) .. ! myvideodecoder ! queue ! fakesink
289 In this case, the myvideodecoder requires buffers to be aligned to 128
290 bytes and padded with 4096 bytes. The pipeline starts out with the
291 decoder linked to a fakesink but we will then dynamically change the
292 sink to one that can provide a bufferpool.
294 When it negotiates the size with the downstream element fakesink, it will
295 receive a NULL bufferpool because fakesink does not provide a bufferpool.
296 It will then select its own custom bufferpool to start the datatransfer.
298 At some point we block the queue srcpad, unlink the queue from the
299 fakesink, link a new sink and set the new sink to the PLAYING state.
300 Linking the new sink would automatically send a RECONFIGURE event upstream
301 and, through queue, inform myvideodecoder that it should renegotiate its
302 bufferpool because downstream has been reconfigured.
304 Before pushing the next buffer, myvideodecoder would renegotiate a new
305 bufferpool. To do this, it performs the usual bufferpool negotiation
306 algorithm. If it can obtain and configure a new bufferpool from downstream,
307 it sets its own (old) pool to inactive and unrefs it. This will eventually
308 drain and unref the old bufferpool.
310 The new bufferpool is set as the new bufferpool for the srcpad and sinkpad
311 of the queue and set to the active state.
314 4) .. ! myvideodecoder ! queue ! myvideosink
316 myvideodecoder has negotiated a bufferpool with the downstream myvideosink
317 to handle buffers of size 320x240. It has now detected a change in the
318 video format and need to renegotiate to a resolution of 640x480. This
319 requires it to negotiate a new bufferpool with a larger buffersize.
321 When myvideodecoder needs to get the bigger buffer, it starts the
322 negotiation of a new bufferpool. It queries a bufferpool from downstream,
323 reconfigures it with the new configuration (which includes the bigger buffer
324 size) and it then sets the bufferpool to active. The old pool is inactivated
325 and unreffed, which causes the old format to drain.
327 It then uses the new bufferpool for allocating new buffers of the new
330 If at some point, the decoder wants to switch to a lower resolution again,
331 it can choose to use the current pool (which has buffers that are larger
332 than the required size) or it can choose to renegotiate a new bufferpool.
335 5) .. ! myvideodecoder ! videoscale ! myvideosink
337 myvideosink is providing a bufferpool for upstream elements and wants to
338 change the resolution.
340 myvideosink sends a RECONFIGURE event upstream to notify upstream that a
341 new format is desirable. upstream elements try to negotiate a new format
342 and bufferpool before pushing out a new buffer. The old bufferpools are
343 drained in the regular way.