GstBufferPool

GstBufferPool — Pool for buffers

Synopsis

#include <gst/gst.h>

                    GstBufferPool;
struct              GstBufferPoolClass;
enum                GstBufferPoolFlags;
#define             GST_BUFFER_POOL_IS_FLUSHING         (pool)
                    GstBufferPoolParams;
GstBufferPool *     gst_buffer_pool_new                 (void);
gboolean            gst_buffer_pool_config_get          (GstStructure *config,
                                                         const GstCaps **caps,
                                                         guint *size,
                                                         guint *min_buffers,
                                                         guint *max_buffers,
                                                         guint *prefix,
                                                         guint *align);
void                gst_buffer_pool_config_set          (GstStructure *config,
                                                         const GstCaps *caps,
                                                         guint size,
                                                         guint min_buffers,
                                                         guint max_buffers,
                                                         guint prefix,
                                                         guint align);
void                gst_buffer_pool_config_add_option   (GstStructure *config,
                                                         const gchar *option);
const gchar *       gst_buffer_pool_config_get_option   (GstStructure *config,
                                                         guint index);
gboolean            gst_buffer_pool_config_has_option   (GstStructure *config,
                                                         const gchar *option);
guint               gst_buffer_pool_config_n_options    (GstStructure *config);
const gchar **      gst_buffer_pool_get_options         (GstBufferPool *pool);
gboolean            gst_buffer_pool_has_option          (GstBufferPool *pool,
                                                         const gchar *option);
GstStructure *      gst_buffer_pool_get_config          (GstBufferPool *pool);
gboolean            gst_buffer_pool_set_config          (GstBufferPool *pool,
                                                         GstStructure *config);
gboolean            gst_buffer_pool_set_active          (GstBufferPool *pool,
                                                         gboolean active);
gboolean            gst_buffer_pool_is_active           (GstBufferPool *pool);
GstFlowReturn       gst_buffer_pool_acquire_buffer      (GstBufferPool *pool,
                                                         GstBuffer **buffer,
                                                         GstBufferPoolParams *params);
void                gst_buffer_pool_release_buffer      (GstBufferPool *pool,
                                                         GstBuffer *buffer);

Description

Details

GstBufferPool

typedef struct {
  GstObject            object;
} GstBufferPool;

The structure of a GstBufferPool. Use the associated macros to access the public variables.

GstObject object;

the parent structure

struct GstBufferPoolClass

struct GstBufferPoolClass {
  GstObjectClass    object_class;

  /* vmethods */
  const gchar ** (*get_options)    (GstBufferPool *pool);
  gboolean       (*set_config)     (GstBufferPool *pool, GstStructure *config);

  gboolean       (*start)          (GstBufferPool *pool);
  gboolean       (*stop)           (GstBufferPool *pool);

  GstFlowReturn  (*acquire_buffer) (GstBufferPool *pool, GstBuffer **buffer,
                                    GstBufferPoolParams *params);
  GstFlowReturn  (*alloc_buffer)   (GstBufferPool *pool, GstBuffer **buffer,
                                    GstBufferPoolParams *params);
  void           (*reset_buffer)   (GstBufferPool *pool, GstBuffer *buffer,
                                    GstBufferPoolParams *params);
  void           (*release_buffer) (GstBufferPool *pool, GstBuffer *buffer);
  void           (*free_buffer)    (GstBufferPool *pool, GstBuffer *buffer);
};

The GstBufferPool class.

GstObjectClass object_class;

Object parent class

get_options ()

get a list of options supported by this pool

set_config ()

apply the bufferpool configuration. The default configuration will parse the default config parameters

start ()

start the bufferpool. The default implementation will preallocate min-buffers buffers and put them in the queue

stop ()

stop the bufferpool. the default implementation will free the preallocated buffers. This function is called when all the buffers are returned to the pool.

acquire_buffer ()

get a new buffer from the pool. The default implementation will take a buffer from the queue and optionally wait for a buffer to be released when there are no buffers available.

alloc_buffer ()

allocate a buffer. the default implementation allocates buffers from the default memory allocator and with the configured size, prefix and alignment.

reset_buffer ()

reset the buffer to its state when it was freshly allocated. The default implementation will clear the flags and timestamps.

release_buffer ()

release a buffer back in the pool. The default implementation will put the buffer back in the queue and notify any blocking acquire_buffer calls.

free_buffer ()

free a buffer. The default implementation unrefs the buffer.

enum GstBufferPoolFlags

typedef enum {
  GST_BUFFER_POOL_FLAG_NONE     = 0,
  GST_BUFFER_POOL_FLAG_KEY_UNIT = (1 << 0),
  GST_BUFFER_POOL_FLAG_DONTWAIT = (1 << 1),
  GST_BUFFER_POOL_FLAG_DISCONT  = (1 << 2),
  GST_BUFFER_POOL_FLAG_LAST     = (1 << 16),
} GstBufferPoolFlags;

Additional flags to control the allocation of a buffer

GST_BUFFER_POOL_FLAG_NONE

no flags

GST_BUFFER_POOL_FLAG_KEY_UNIT

buffer is keyframe

GST_BUFFER_POOL_FLAG_DONTWAIT

don't wait for buffer. This makes the acquire_buffer method return GST_FLOW_UNEXPECTED.

GST_BUFFER_POOL_FLAG_DISCONT

buffer is discont

GST_BUFFER_POOL_FLAG_LAST

last flag, subclasses can use private flags starting from this value.

GST_BUFFER_POOL_IS_FLUSHING()

#define GST_BUFFER_POOL_IS_FLUSHING(pool)  (g_atomic_int_get (&pool->flushing))

Check if the bufferpool is flushing. Subclasses might want to check the state of the pool in the acquire function.

pool :

a GstBufferPool

GstBufferPoolParams

typedef struct {
  GstFormat          format;
  gint64             start;
  gint64             stop;
  GstBufferPoolFlags flags;
} GstBufferPoolParams;

Parameters passed to the gst_buffer_pool_acquire_buffer() function to control the allocation of the buffer.

The default implementation ignores the start and stop members but other implementations can use this extra information to decide what buffer to return.

GstFormat format;

the format of start and stop

gint64 start;

the start position

gint64 stop;

the stop position

GstBufferPoolFlags flags;

additional flags

gst_buffer_pool_new ()

GstBufferPool *     gst_buffer_pool_new                 (void);

Creates a new GstBufferPool instance.

Returns :

a new GstBufferPool instance

gst_buffer_pool_config_get ()

gboolean            gst_buffer_pool_config_get          (GstStructure *config,
                                                         const GstCaps **caps,
                                                         guint *size,
                                                         guint *min_buffers,
                                                         guint *max_buffers,
                                                         guint *prefix,
                                                         guint *align);

Get the configuration values from config.

config :

a GstBufferPool configuration

caps :

the caps of buffers

size :

the size of each buffer, not including prefix

min_buffers :

the minimum amount of buffers to allocate.

max_buffers :

the maximum amount of buffers to allocate or 0 for unlimited.

prefix :

prefix each buffer with this many bytes

align :

alignment of the buffer data.

gst_buffer_pool_config_set ()

void                gst_buffer_pool_config_set          (GstStructure *config,
                                                         const GstCaps *caps,
                                                         guint size,
                                                         guint min_buffers,
                                                         guint max_buffers,
                                                         guint prefix,
                                                         guint align);

Configure config with the given parameters.

config :

a GstBufferPool configuration

caps :

caps for the buffers

size :

the size of each buffer, not including prefix

min_buffers :

the minimum amount of buffers to allocate.

max_buffers :

the maximum amount of buffers to allocate or 0 for unlimited.

prefix :

prefix each buffer with this many bytes

align :

alignment of the buffer data.

gst_buffer_pool_config_add_option ()

void                gst_buffer_pool_config_add_option   (GstStructure *config,
                                                         const gchar *option);

Enabled the option in config. This will instruct the bufferpool to enable the specified option on the buffers that it allocates.

The supported options by pool can be retrieved with gst_buffer_pool_get_options().

config :

a GstBufferPool configuration

option :

an option to add

gst_buffer_pool_config_get_option ()

const gchar *       gst_buffer_pool_config_get_option   (GstStructure *config,
                                                         guint index);

Parse an available config and get the option at index of the options API array.

config :

a GstBufferPool configuration

index :

position in the option array to read

Returns :

a gchar of the option at index.

gst_buffer_pool_config_has_option ()

gboolean            gst_buffer_pool_config_has_option   (GstStructure *config,
                                                         const gchar *option);

Check if config contains option

config :

a GstBufferPool configuration

option :

an option

Returns :

TRUE if the options array contains option.

gst_buffer_pool_config_n_options ()

guint               gst_buffer_pool_config_n_options    (GstStructure *config);

Retrieve the number of values currently stored in the options array of the config structure.

config :

a GstBufferPool configuration

Returns :

the options array size as a guint.

gst_buffer_pool_get_options ()

const gchar **      gst_buffer_pool_get_options         (GstBufferPool *pool);

Get a NULL terminated array of string with supported bufferpool options for pool. An option would typically be enabled with gst_buffer_pool_config_add_option().

pool :

a GstBufferPool

Returns :

a NULL terminated array of strings.

gst_buffer_pool_has_option ()

gboolean            gst_buffer_pool_has_option          (GstBufferPool *pool,
                                                         const gchar *option);

Check if the bufferpool supports option.

pool :

a GstBufferPool

option :

an option

Returns :

a NULL terminated array of strings.

gst_buffer_pool_get_config ()

GstStructure *      gst_buffer_pool_get_config          (GstBufferPool *pool);

Get a copy of the current configuration of the pool. This configuration can either be modified and used for the gst_buffer_pool_set_config() call or it must be freed after usage.

pool :

a GstBufferPool

Returns :

a copy of the current configuration of pool. use gst_structure_free() after usage or gst_buffer_pool_set_config().

gst_buffer_pool_set_config ()

gboolean            gst_buffer_pool_set_config          (GstBufferPool *pool,
                                                         GstStructure *config);

Set the configuration of the pool. The pool must be inactive and all buffers allocated form this pool must be returned or else this function will do nothing and return FALSE.

config is a GstStructure that contains the configuration parameters for the pool. A default and mandatory set of parameters can be configured with gst_buffer_pool_config_set(). This function takes ownership of config.

pool :

a GstBufferPool

config :

a GstStructure

Returns :

TRUE when the configuration could be set.

gst_buffer_pool_set_active ()

gboolean            gst_buffer_pool_set_active          (GstBufferPool *pool,
                                                         gboolean active);

Control the active state of pool. When the pool is active, new calls to gst_buffer_pool_acquire_buffer() will return with GST_FLOW_WRONG_STATE.

Activating the bufferpool will preallocate all resources in the pool based on the configuration of the pool.

Deactivating will free the resources again when there are no outstanding buffers. When there are outstanding buffers, they will be freed as soon as they are all returned to the pool.

pool :

a GstBufferPool

active :

the new active state

Returns :

FALSE when the pool was not configured or when preallocation of the buffers failed.

gst_buffer_pool_is_active ()

gboolean            gst_buffer_pool_is_active           (GstBufferPool *pool);

Check if pool is active. A pool can be activated with the gst_buffer_pool_set_active() call.

pool :

a GstBufferPool

Returns :

TRUE when the pool is active.

gst_buffer_pool_acquire_buffer ()

GstFlowReturn       gst_buffer_pool_acquire_buffer      (GstBufferPool *pool,
                                                         GstBuffer **buffer,
                                                         GstBufferPoolParams *params);

Acquire a buffer from pool. buffer should point to a memory location that can hold a pointer to the new buffer.

params can be NULL or contain optional parameters to influence the allocation.

pool :

a GstBufferPool

buffer :

a location for a GstBuffer

params :

parameters.

Returns :

a GstFlowReturn such as GST_FLOW_WRONG_STATE when the pool is inactive.

gst_buffer_pool_release_buffer ()

void                gst_buffer_pool_release_buffer      (GstBufferPool *pool,
                                                         GstBuffer *buffer);

Release buffer to pool. buffer should have previously been allocated from pool with gst_buffer_pool_acquire_buffer().

This function is usually called automatically when the last ref on buffer disappears.

pool :

a GstBufferPool

buffer :

a GstBuffer

See Also

GstBuffer