1/* GStreamer
2 * Copyright (C) 2010 Wim Taymans <wim.taymans@gmail.com>
3 *
4 * gstbufferpool.h: Header for GstBufferPool object
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 */
21
22
23#ifndef __GST_BUFFER_POOL_H__
24#define __GST_BUFFER_POOL_H__
25
26#include <gst/gstminiobject.h>
27#include <gst/gstpad.h>
28#include <gst/gstbuffer.h>
29
30G_BEGIN_DECLS
31
32typedef struct _GstBufferPoolPrivate GstBufferPoolPrivate;
33typedef struct _GstBufferPoolClass GstBufferPoolClass;
34
35#define GST_TYPE_BUFFER_POOL (gst_buffer_pool_get_type())
36#define GST_IS_BUFFER_POOL(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_BUFFER_POOL))
37#define GST_IS_BUFFER_POOL_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_BUFFER_POOL))
38#define GST_BUFFER_POOL_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_BUFFER_POOL, GstBufferPoolClass))
39#define GST_BUFFER_POOL(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_BUFFER_POOL, GstBufferPool))
40#define GST_BUFFER_POOL_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_BUFFER_POOL, GstBufferPoolClass))
41#define GST_BUFFER_POOL_CAST(obj) ((GstBufferPool *)(obj))
42
43/**
44 * GstBufferPoolAcquireFlags:
45 * @GST_BUFFER_POOL_ACQUIRE_FLAG_NONE: no flags
46 * @GST_BUFFER_POOL_ACQUIRE_FLAG_KEY_UNIT: buffer is keyframe
47 * @GST_BUFFER_POOL_ACQUIRE_FLAG_DONTWAIT: when the bufferpool is empty, acquire_buffer
48 * will by default block until a buffer is released into the pool again. Setting
49 * this flag makes acquire_buffer return #GST_FLOW_EOS instead of blocking.
50 * @GST_BUFFER_POOL_ACQUIRE_FLAG_DISCONT: buffer is discont
51 * @GST_BUFFER_POOL_ACQUIRE_FLAG_LAST: last flag, subclasses can use private flags
52 * starting from this value.
53 *
54 * Additional flags to control the allocation of a buffer
55 */
56typedef enum {
57 GST_BUFFER_POOL_ACQUIRE_FLAG_NONE = 0,
58 GST_BUFFER_POOL_ACQUIRE_FLAG_KEY_UNIT = (1 << 0),
59 GST_BUFFER_POOL_ACQUIRE_FLAG_DONTWAIT = (1 << 1),
60 GST_BUFFER_POOL_ACQUIRE_FLAG_DISCONT = (1 << 2),
61 GST_BUFFER_POOL_ACQUIRE_FLAG_LAST = (1 << 16),
62} GstBufferPoolAcquireFlags;
63
64typedef struct _GstBufferPoolAcquireParams GstBufferPoolAcquireParams;
65
66/**
67 * GstBufferPoolAcquireParams:
68 * @format: the format of @start and @stop
69 * @start: the start position
70 * @stop: the stop position
71 * @flags: additional flags
72 *
73 * Parameters passed to the gst_buffer_pool_acquire_buffer() function to control the
74 * allocation of the buffer.
75 *
76 * The default implementation ignores the @start and @stop members but other
77 * implementations can use this extra information to decide what buffer to
78 * return.
79 */
80struct _GstBufferPoolAcquireParams {
81 GstFormat format;
82 gint64 start;
83 gint64 stop;
84 GstBufferPoolAcquireFlags flags;
85
86 /*< private >*/
87 gpointer _gst_reserved[GST_PADDING];
88};
89
90/**
91 * GST_BUFFER_POOL_IS_FLUSHING:
92 * @pool: a GstBufferPool
93 *
94 * Check if the bufferpool is flushing. Subclasses might want to check the
95 * state of the pool in the acquire function.
96 */
97#define GST_BUFFER_POOL_IS_FLUSHING(pool) (g_atomic_int_get (&pool->flushing))
98
99/**
100 * GstBufferPool:
101 * @object: the parent structure
102 * @flushing: whether the pool is currently gathering back outstanding buffers
103 *
104 * The structure of a #GstBufferPool. Use the associated macros to access the public
105 * variables.
106 */
107struct _GstBufferPool {
108 GstObject object;
109
110 /*< protected >*/
111 gint flushing;
112
113 /*< private >*/
114 GstBufferPoolPrivate *priv;
115
116 gpointer _gst_reserved[GST_PADDING];
117};
118
119/**
120 * GstBufferPoolClass:
121 * @object_class: Object parent class
122 *
123 * The #GstBufferPool class.
124 */
125struct _GstBufferPoolClass {
126 GstObjectClass object_class;
127
128 /*< public >*/
129
130 /**
131 * GstBufferPoolClass::get_options:
132 * @pool: the #GstBufferPool
133 *
134 * Get a list of options supported by this pool
135 *
136 * Returns: (array zero-terminated=1) (transfer none): a %NULL terminated array
137 * of strings.
138 */
139 const gchar ** (*get_options) (GstBufferPool *pool);
140
141 /**
142 * GstBufferPoolClass::set_config:
143 * @pool: the #GstBufferPool
144 * @config: the required configuration
145 *
146 * Apply the bufferpool configuration. The default configuration will parse
147 * the default config parameters.
148 *
149 * Returns: whether the configuration could be set.
150 */
151 gboolean (*set_config) (GstBufferPool *pool, GstStructure *config);
152
153 /**
154 * GstBufferPoolClass::start:
155 * @pool: the #GstBufferPool
156 *
157 * Start the bufferpool. The default implementation will preallocate
158 * min-buffers buffers and put them in the queue.
159 *
160 * Returns: whether the pool could be started.
161 */
162 gboolean (*start) (GstBufferPool *pool);
163
164 /**
165 * GstBufferPoolClass::stop:
166 * @pool: the #GstBufferPool
167 *
168 * Stop the bufferpool. the default implementation will free the
169 * preallocated buffers. This function is called when all the buffers are
170 * returned to the pool.
171 *
172 * Returns: whether the pool could be stopped.
173 */
174 gboolean (*stop) (GstBufferPool *pool);
175
176 /**
177 * GstBufferPoolClass::acquire_buffer:
178 * @pool: the #GstBufferPool
179 * @buffer: (out): a location for a #GstBuffer
180 * @params: (transfer none) (allow-none): parameters.
181 *
182 * Get a new buffer from the pool. The default implementation
183 * will take a buffer from the queue and optionally wait for a buffer to
184 * be released when there are no buffers available.
185 *
186 * Returns: a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is
187 * inactive.
188 */
189 GstFlowReturn (*acquire_buffer) (GstBufferPool *pool, GstBuffer **buffer,
190 GstBufferPoolAcquireParams *params);
191
192 /**
193 * GstBufferPoolClass::alloc_buffer:
194 * @pool: the #GstBufferPool
195 * @buffer: (out): a location for a #GstBuffer
196 * @params: (transfer none) (allow-none): parameters.
197 *
198 * Allocate a buffer. the default implementation allocates
199 * buffers from the configured memory allocator and with the configured
200 * parameters. All metadata that is present on the allocated buffer will
201 * be marked as #GST_META_FLAG_POOLED and #GST_META_FLAG_LOCKED and will
202 * not be removed from the buffer in #GstBufferPoolClass::reset_buffer.
203 * The buffer should have the #GST_BUFFER_FLAG_TAG_MEMORY cleared.
204 *
205 * Returns: a #GstFlowReturn to indicate whether the allocation was
206 * successful.
207 */
208 GstFlowReturn (*alloc_buffer) (GstBufferPool *pool, GstBuffer **buffer,
209 GstBufferPoolAcquireParams *params);
210
211 /**
212 * GstBufferPoolClass::reset_buffer:
213 * @pool: the #GstBufferPool
214 * @buffer: the #GstBuffer to reset
215 *
216 * Reset the buffer to its state when it was freshly allocated.
217 * The default implementation will clear the flags, timestamps and
218 * will remove the metadata without the #GST_META_FLAG_POOLED flag (even
219 * the metadata with #GST_META_FLAG_LOCKED). If the
220 * #GST_BUFFER_FLAG_TAG_MEMORY was set, this function can also try to
221 * restore the memory and clear the #GST_BUFFER_FLAG_TAG_MEMORY again.
222 */
223 void (*reset_buffer) (GstBufferPool *pool, GstBuffer *buffer);
224
225 /**
226 * GstBufferPoolClass::release_buffer:
227 * @pool: the #GstBufferPool
228 * @buffer: the #GstBuffer to release
229 *
230 * Release a buffer back in the pool. The default implementation
231 * will put the buffer back in the queue and notify any
232 * blocking #GstBufferPoolClass::acquire_buffer calls when the
233 * #GST_BUFFER_FLAG_TAG_MEMORY is not set on the buffer.
234 * If #GST_BUFFER_FLAG_TAG_MEMORY is set, the buffer will be freed with
235 * #GstBufferPoolClass::free_buffer.
236 */
237 void (*release_buffer) (GstBufferPool *pool, GstBuffer *buffer);
238
239 /**
240 * GstBufferPoolClass::free_buffer:
241 * @pool: the #GstBufferPool
242 * @buffer: the #GstBuffer to free
243 *
244 * Free a buffer. The default implementation unrefs the buffer.
245 */
246 void (*free_buffer) (GstBufferPool *pool, GstBuffer *buffer);
247
248 /**
249 * GstBufferPoolClass::flush_start:
250 * @pool: the #GstBufferPool
251 *
252 * Enter the flushing state.
253 *
254 * Since: 1.4
255 */
256 void (*flush_start) (GstBufferPool *pool);
257
258 /**
259 * GstBufferPoolClass::flush_stop:
260 * @pool: the #GstBufferPool
261 *
262 * Leave the flushing state.
263 *
264 * Since: 1.4
265 */
266 void (*flush_stop) (GstBufferPool *pool);
267
268 /*< private >*/
269 gpointer _gst_reserved[GST_PADDING - 2];
270};
271
272GST_API
273GType gst_buffer_pool_get_type (void);
274
275/* allocation */
276
277GST_API
278GstBufferPool * gst_buffer_pool_new (void);
279
280/* state management */
281
282GST_API
283gboolean gst_buffer_pool_set_active (GstBufferPool *pool, gboolean active);
284
285GST_API
286gboolean gst_buffer_pool_is_active (GstBufferPool *pool);
287
288GST_API
289gboolean gst_buffer_pool_set_config (GstBufferPool *pool, GstStructure *config);
290
291GST_API
292GstStructure * gst_buffer_pool_get_config (GstBufferPool *pool);
293
294GST_API
295const gchar ** gst_buffer_pool_get_options (GstBufferPool *pool);
296
297GST_API
298gboolean gst_buffer_pool_has_option (GstBufferPool *pool, const gchar *option);
299
300GST_API
301void gst_buffer_pool_set_flushing (GstBufferPool *pool, gboolean flushing);
302
303/* helpers for configuring the config structure */
304
305GST_API
306void gst_buffer_pool_config_set_params (GstStructure *config, GstCaps *caps,
307 guint size, guint min_buffers, guint max_buffers);
308
309GST_API
310gboolean gst_buffer_pool_config_get_params (GstStructure *config, GstCaps **caps,
311 guint *size, guint *min_buffers, guint *max_buffers);
312
313GST_API
314void gst_buffer_pool_config_set_allocator (GstStructure *config, GstAllocator *allocator,
315 const GstAllocationParams *params);
316
317GST_API
318gboolean gst_buffer_pool_config_get_allocator (GstStructure *config, GstAllocator **allocator,
319 GstAllocationParams *params);
320
321/* options */
322
323GST_API
324guint gst_buffer_pool_config_n_options (GstStructure *config);
325
326GST_API
327void gst_buffer_pool_config_add_option (GstStructure *config, const gchar *option);
328
329GST_API
330const gchar * gst_buffer_pool_config_get_option (GstStructure *config, guint index);
331
332GST_API
333gboolean gst_buffer_pool_config_has_option (GstStructure *config, const gchar *option);
334
335GST_API
336gboolean gst_buffer_pool_config_validate_params (GstStructure *config, GstCaps *caps,
337 guint size, guint min_buffers, guint max_buffers);
338
339/* buffer management */
340
341GST_API
342GstFlowReturn gst_buffer_pool_acquire_buffer (GstBufferPool *pool, GstBuffer **buffer,
343 GstBufferPoolAcquireParams *params);
344
345GST_API
346void gst_buffer_pool_release_buffer (GstBufferPool *pool, GstBuffer *buffer);
347
348G_END_DECLS
349
350#endif /* __GST_BUFFER_POOL_H__ */
351

source code of include/gstreamer-1.0/gst/gstbufferpool.h