GI.Gst.Objects.BufferPool

A BufferPool is an object that can be used to pre-allocate and recycle buffers of the same size and with the same properties.

A BufferPool is created with bufferPoolNew.

Once a pool is created, it needs to be configured. A call to bufferPoolGetConfig returns the current configuration structure from the pool. With bufferPoolConfigSetParams and bufferPoolConfigSetAllocator the bufferpool parameters and allocator can be configured. Other properties can be configured in the pool depending on the pool implementation.

A bufferpool can have extra options that can be enabled with bufferPoolConfigAddOption. The available options can be retrieved with bufferPoolGetOptions. Some options allow for additional configuration properties to be set.

After the configuration structure has been configured, bufferPoolSetConfig updates the configuration in the pool. This can fail when the configuration structure is not accepted.

After the a pool has been configured, it can be activated with bufferPoolSetActive. This will preallocate the configured resources in the pool.

When the pool is active, bufferPoolAcquireBuffer can be used to retrieve a buffer from the pool.

Buffers allocated from a bufferpool will automatically be returned to the pool with bufferPoolReleaseBuffer when their refcount drops to 0.

The bufferpool can be deactivated again with bufferPoolSetActive. All further bufferPoolAcquireBuffer calls will return an error. When all buffers are returned to the pool they will be freed.

Use objectUnref to release the reference to a bufferpool. If the refcount of the pool reaches 0, the pool will be freed.

Exported types

newtype BufferPool

Memory-managed wrapper type.

Constructors

BufferPool (ManagedPtr BufferPool)

Instances

GObject BufferPool

Defined in GI.Gst.Objects.BufferPool

Methods

gobjectType :: IO GType

HasParentTypes BufferPool

Defined in GI.Gst.Objects.BufferPool

type ParentTypes BufferPool

Defined in GI.Gst.Objects.BufferPool

type ParentTypes BufferPool = Object ': (Object ': ([] :: [Type]))

class (GObject o, IsDescendantOf BufferPool o) => IsBufferPool o

Type class for types which can be safely cast to BufferPool, for instance with toBufferPool.

Instances

(GObject o, IsDescendantOf BufferPool o) => IsBufferPool o

Defined in GI.Gst.Objects.BufferPool

toBufferPool :: (MonadIO m, IsBufferPool o) => o -> m BufferPool

Cast to BufferPool, for types for which this is known to be safe. For general casts, use castTo.

noBufferPool :: Maybe BufferPool

A convenience alias for Nothing :: Maybe BufferPool.

Methods

acquireBuffer

bufferPoolAcquireBuffer

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Maybe BufferPoolAcquireParams

params: parameters.

-> m (FlowReturn, Buffer)

Returns: a FlowReturn such as FlowReturnFlushing when the pool is inactive.

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

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

configAddOption

bufferPoolConfigAddOption

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> Text

option: an option to add

-> m ()

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 bufferPoolGetOptions.

configGetAllocator

bufferPoolConfigGetAllocator

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> m (Bool, Allocator, AllocationParams)

Returns: True, if the values are set.

Get the allocator and params from config.

configGetOption

bufferPoolConfigGetOption

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> Word32

index: position in the option array to read

-> m Text

Returns: a gchar of the option at index.

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

configGetParams

bufferPoolConfigGetParams

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> m (Bool, Caps, Word32, Word32, Word32)

Returns: True if all parameters could be fetched.

Get the configuration values from config.

configHasOption

bufferPoolConfigHasOption

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> Text

option: an option

-> m Bool

Returns: True if the options array contains option.

Check if config contains option.

configNOptions

bufferPoolConfigNOptions

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> m Word32

Returns: the options array size as a guint.

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

configSetAllocator

bufferPoolConfigSetAllocator

Arguments

:: (HasCallStack, MonadIO m, IsAllocator a)

=> Structure

config: a BufferPool configuration

-> Maybe a

allocator: a Allocator

-> Maybe AllocationParams

params: AllocationParams

-> m ()

Set the allocator and params on config.

One of allocator and params can be Nothing, but not both. When allocator is Nothing, the default allocator of the pool will use the values in param to perform its allocation. When param is Nothing, the pool will use the provided allocator with its default AllocationParams.

A call to bufferPoolSetConfig can update the allocator and params with the values that it is able to do. Some pools are, for example, not able to operate with different allocators or cannot allocate with the values specified in params. Use bufferPoolGetConfig to get the currently used values.

configSetParams

bufferPoolConfigSetParams

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> Caps

caps: caps for the buffers

-> Word32

size: the size of each buffer, not including prefix and padding

-> Word32

minBuffers: the minimum amount of buffers to allocate.

-> Word32

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

-> m ()

Configure config with the given parameters.

configValidateParams

bufferPoolConfigValidateParams

Arguments

:: (HasCallStack, MonadIO m)

=> Structure

config: a BufferPool configuration

-> Caps

caps: the excepted caps of buffers

-> Word32

size: the expected size of each buffer, not including prefix and padding

-> Word32

minBuffers: the expected minimum amount of buffers to allocate.

-> Word32

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

-> m Bool

Returns: True, if the parameters are valid in this context.

Validate that changes made to config are still valid in the context of the expected parameters. This function is a helper that can be used to validate changes made by a pool to a config when bufferPoolSetConfig returns False. This expects that caps haven't changed and that minBuffers aren't lower then what we initially expected. This does not check if options or allocator parameters are still valid, won't check if size have changed, since changing the size is valid to adapt padding.

Since: 1.4

getConfig

bufferPoolGetConfig

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> m Structure

Returns: a copy of the current configuration of pool. use structureFree after usage or bufferPoolSetConfig.

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

getOptions

bufferPoolGetOptions

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> m [Text]

Returns: a Nothing terminated array of strings.

Get a Nothing terminated array of string with supported bufferpool options for pool. An option would typically be enabled with bufferPoolConfigAddOption.

hasOption

bufferPoolHasOption

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Text

option: an option

-> m Bool

Returns: True if the buffer pool contains option.

Check if the bufferpool supports option.

isActive

bufferPoolIsActive

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> m Bool

Returns: True when the pool is active.

Check if pool is active. A pool can be activated with the bufferPoolSetActive call.

new

bufferPoolNew

Arguments

:: (HasCallStack, MonadIO m)

=> m BufferPool

Returns: a new BufferPool instance

Creates a new BufferPool instance.

releaseBuffer

bufferPoolReleaseBuffer

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Buffer

buffer: a Buffer

-> m ()

Release buffer to pool. buffer should have previously been allocated from pool with bufferPoolAcquireBuffer.

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

setActive

bufferPoolSetActive

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Bool

active: the new active state

-> m Bool

Returns: False when the pool was not configured or when preallocation of the buffers failed.

Control the active state of pool. When the pool is inactive, new calls to bufferPoolAcquireBuffer will return with FlowReturnFlushing.

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.

setConfig

bufferPoolSetConfig

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Structure

config: a Structure

-> m Bool

Returns: True when the configuration could be set.

Set the configuration of the pool. If the pool is already configured, and the configuration haven't change, this function will return True. If the pool is active, this method will return False and active configuration will remain. Buffers allocated form this pool must be returned or else this function will do nothing and return False.

config is a Structure that contains the configuration parameters for the pool. A default and mandatory set of parameters can be configured with bufferPoolConfigSetParams, bufferPoolConfigSetAllocator and bufferPoolConfigAddOption.

If the parameters in config can not be set exactly, this function returns False and will try to update as much state as possible. The new state can then be retrieved and refined with bufferPoolGetConfig.

This function takes ownership of config.

setFlushing

bufferPoolSetFlushing

Arguments

:: (HasCallStack, MonadIO m, IsBufferPool a)

=> a

pool: a BufferPool

-> Bool

flushing: whether to start or stop flushing

-> m ()

Enable or disable the flushing state of a pool without freeing or allocating buffers.

Since: 1.4