gi-gst-1.0.23: GStreamer bindings
CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellNone
LanguageHaskell2010

GI.Gst.Objects.BufferPool

Description

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.

Synopsis

Exported types

newtype BufferPool Source #

Memory-managed wrapper type.

Constructors

BufferPool (ManagedPtr BufferPool) 

Instances

Instances details
Eq BufferPool Source # 
Instance details

Defined in GI.Gst.Objects.BufferPool

Methods

(==) :: BufferPool -> BufferPool -> Bool

(/=) :: BufferPool -> BufferPool -> Bool

GObject BufferPool Source # 
Instance details

Defined in GI.Gst.Objects.BufferPool

ManagedPtrNewtype BufferPool Source # 
Instance details

Defined in GI.Gst.Objects.BufferPool

Methods

toManagedPtr :: BufferPool -> ManagedPtr BufferPool

TypedObject BufferPool Source # 
Instance details

Defined in GI.Gst.Objects.BufferPool

Methods

glibType :: IO GType

IsGValue BufferPool Source #

Convert BufferPool to and from GValue with toGValue and fromGValue.

Instance details

Defined in GI.Gst.Objects.BufferPool

Methods

toGValue :: BufferPool -> IO GValue

fromGValue :: GValue -> IO BufferPool

HasParentTypes BufferPool Source # 
Instance details

Defined in GI.Gst.Objects.BufferPool

type ParentTypes BufferPool Source # 
Instance details

Defined in GI.Gst.Objects.BufferPool

type ParentTypes BufferPool = '[Object, Object]

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

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

Instances

Instances details
(GObject o, IsDescendantOf BufferPool o) => IsBufferPool o Source # 
Instance details

Defined in GI.Gst.Objects.BufferPool

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

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

Methods

Overloaded methods

acquireBuffer

bufferPoolAcquireBuffer Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> m BufferPool

Returns: a new BufferPool instance

Creates a new BufferPool instance.

releaseBuffer

bufferPoolReleaseBuffer Source #

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 Source #

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 Source #

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 Source #

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