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 30 G_BEGIN_DECLS 31 32 typedef struct _GstBufferPoolPrivate GstBufferPoolPrivate; 33 typedef 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 */ 56 typedef 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 64 typedef 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 */ 80 struct _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 */ 107 struct _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 */ 125 struct _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 272 GST_API 273 GType gst_buffer_pool_get_type (void); 274 275 /* allocation */ 276 277 GST_API 278 GstBufferPool * gst_buffer_pool_new (void); 279 280 /* state management */ 281 282 GST_API 283 gboolean gst_buffer_pool_set_active (GstBufferPool *pool, gboolean active); 284 285 GST_API 286 gboolean gst_buffer_pool_is_active (GstBufferPool *pool); 287 288 GST_API 289 gboolean gst_buffer_pool_set_config (GstBufferPool *pool, GstStructure *config); 290 291 GST_API 292 GstStructure * gst_buffer_pool_get_config (GstBufferPool *pool); 293 294 GST_API 295 const gchar ** gst_buffer_pool_get_options (GstBufferPool *pool); 296 297 GST_API 298 gboolean gst_buffer_pool_has_option (GstBufferPool *pool, const gchar *option); 299 300 GST_API 301 void gst_buffer_pool_set_flushing (GstBufferPool *pool, gboolean flushing); 302 303 /* helpers for configuring the config structure */ 304 305 GST_API 306 void gst_buffer_pool_config_set_params (GstStructure *config, GstCaps *caps, 307 guint size, guint min_buffers, guint max_buffers); 308 309 GST_API 310 gboolean gst_buffer_pool_config_get_params (GstStructure *config, GstCaps **caps, 311 guint *size, guint *min_buffers, guint *max_buffers); 312 313 GST_API 314 void gst_buffer_pool_config_set_allocator (GstStructure *config, GstAllocator *allocator, 315 const GstAllocationParams *params); 316 317 GST_API 318 gboolean gst_buffer_pool_config_get_allocator (GstStructure *config, GstAllocator **allocator, 319 GstAllocationParams *params); 320 321 /* options */ 322 323 GST_API 324 guint gst_buffer_pool_config_n_options (GstStructure *config); 325 326 GST_API 327 void gst_buffer_pool_config_add_option (GstStructure *config, const gchar *option); 328 329 GST_API 330 const gchar * gst_buffer_pool_config_get_option (GstStructure *config, guint index); 331 332 GST_API 333 gboolean gst_buffer_pool_config_has_option (GstStructure *config, const gchar *option); 334 335 GST_API 336 gboolean gst_buffer_pool_config_validate_params (GstStructure *config, GstCaps *caps, 337 guint size, guint min_buffers, guint max_buffers); 338 339 /* buffer management */ 340 341 GST_API 342 GstFlowReturn gst_buffer_pool_acquire_buffer (GstBufferPool *pool, GstBuffer **buffer, 343 GstBufferPoolAcquireParams *params); 344 345 GST_API 346 void gst_buffer_pool_release_buffer (GstBufferPool *pool, GstBuffer *buffer); 347 348 G_END_DECLS 349 350 #endif /* __GST_BUFFER_POOL_H__ */ 351