subprojects/gstreamer/gst/gstbufferpool.h

   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) (transfer full) (nullable): a location for a #GstBuffer
 180    * @params: (transfer none) (nullable): 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) (transfer full) (nullable): a location for a #GstBuffer
 196    * @params: (transfer none) (nullable): 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__ */