GI.Gst.Structs.Memory

GstMemory is a lightweight refcounted object that wraps a region of memory. They are typically used to manage the data of a Buffer.

A GstMemory object has an allocated region of memory of maxsize. The maximum size does not change during the lifetime of the memory object. The memory also has an offset and size property that specifies the valid range of memory in the allocated region.

Memory is usually created by allocators with a allocatorAlloc method call. When Nothing is used as the allocator, the default allocator will be used.

New allocators can be registered with allocatorRegister. Allocators are identified by name and can be retrieved with allocatorFind. allocatorSetDefault can be used to change the default allocator.

New memory can be created with memoryNewWrapped that wraps the memory allocated elsewhere.

Refcounting of the memory block is performed with gst_memory_ref() and gst_memory_unref().

The size of the memory can be retrieved and changed with memoryGetSizes and memoryResize respectively.

Getting access to the data of the memory is performed with memoryMap. The call will return a pointer to offset bytes into the region of memory. After the memory access is completed, memoryUnmap should be called.

Memory can be copied with memoryCopy, which will return a writable copy. memoryShare will create a new memory block that shares the memory with an existing memory block at a custom offset and with a custom size.

Memory can be efficiently merged when memoryIsSpan returns True.

Exported types

newtype Memory

Memory-managed wrapper type.

Constructors

Memory (ManagedPtr Memory)

Instances

BoxedObject Memory

Defined in GI.Gst.Structs.Memory

Methods

boxedType :: Memory -> IO GType

tag ~ AttrSet => Constructible Memory tag

Defined in GI.Gst.Structs.Memory

Methods

new :: MonadIO m => (ManagedPtr Memory -> Memory) -> [AttrOp Memory tag] -> m Memory

newZeroMemory :: MonadIO m => m Memory

Construct a Memory struct initialized to zero.

noMemory :: Maybe Memory

A convenience alias for Nothing :: Maybe Memory.

Methods

copy

memoryCopy

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem: a Memory

-> Int64

offset: offset to copy from

-> Int64

size: size to copy, or -1 to copy to the end of the memory region

-> m Memory

Returns: a new Memory.

Return a copy of size bytes from mem starting from offset. This copy is guaranteed to be writable. size can be set to -1 to return a copy from offset to the end of the memory region.

getSizes

memoryGetSizes

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem: a Memory

-> m (Word64, Word64, Word64)

Returns: the current sizes of mem

Get the current size, offset and maxsize of mem.

isSpan

memoryIsSpan

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem1: a Memory

-> Memory

mem2: a Memory

-> m (Bool, Word64)

Returns: True if the memory is contiguous and of a common parent.

Check if mem1 and mem2 share the memory with a common parent memory object and that the memory is contiguous.

If this is the case, the memory of mem1 and mem2 can be merged efficiently by performing memoryShare on the parent object from the returned offset.

isType

memoryIsType

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem: a Memory

-> Text

memType: a memory type

-> m Bool

Returns: True if mem was allocated from an allocator for memType.

Check if mem if allocated with an allocator for memType.

Since: 1.2

makeMapped

memoryMakeMapped

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem: a Memory

-> [MapFlags]

flags: mapping flags

-> m (Maybe Memory, MapInfo)

Returns: a Memory object mapped with flags or Nothing when a mapping is not possible.

Create a Memory object that is mapped with flags. If mem is mappable with flags, this function returns the mapped mem directly. Otherwise a mapped copy of mem is returned.

This function takes ownership of old mem and returns a reference to a new Memory.

map

memoryMap

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem: a Memory

-> [MapFlags]

flags: mapping flags

-> m (Bool, MapInfo)

Returns: True if the map operation was successful.

Fill info with the pointer and sizes of the memory in mem that can be accessed according to flags.

This function can return False for various reasons:

• the memory backed by mem is not accessible with the given flags.
• the memory was already mapped with a different mapping.

info and its contents remain valid for as long as mem is valid and until memoryUnmap is called.

For each memoryMap call, a corresponding memoryUnmap call should be done.

newWrapped

memoryNewWrapped

Arguments

:: (HasCallStack, MonadIO m)

=> [MemoryFlags]

flags: MemoryFlags

-> ByteString

data: data to wrap

-> Word64

maxsize: allocated size of data

-> Word64

offset: offset in data

-> Maybe DestroyNotify

notify: called with userData when the memory is freed

-> m (Maybe Memory)

Returns: a new Memory.

Allocate a new memory block that wraps the given data.

The prefix/padding must be filled with 0 if flags contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

resize

memoryResize

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem: a Memory

-> Int64

offset: a new offset

-> Word64

size: a new size

-> m ()

Resize the memory region. mem should be writable and offset + size should be less than the maxsize of mem.

GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED will be cleared when offset or padding is increased respectively.

share

memoryShare

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem: a Memory

-> Int64

offset: offset to share from

-> Int64

size: size to share, or -1 to share to the end of the memory region

-> m Memory

Returns: a new Memory.

Return a shared copy of size bytes from mem starting from offset. No memory copy is performed and the memory region is simply shared. The result is guaranteed to be non-writable. size can be set to -1 to return a shared copy from offset to the end of the memory region.

unmap

memoryUnmap

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem: a Memory

-> MapInfo

info: a MapInfo

-> m ()

Release the memory obtained with memoryMap

Properties

align

the alignment of the memory

getMemoryAlign :: MonadIO m => Memory -> m Word64

Get the value of the “align” field. When overloading is enabled, this is equivalent to

get memory #align

setMemoryAlign :: MonadIO m => Memory -> Word64 -> m ()

Set the value of the “align” field. When overloading is enabled, this is equivalent to

set memory [ #align := value ]

allocator

pointer to the Allocator

clearMemoryAllocator :: MonadIO m => Memory -> m ()

Set the value of the “allocator” field to Nothing. When overloading is enabled, this is equivalent to

clear #allocator

getMemoryAllocator :: MonadIO m => Memory -> m (Maybe Allocator)

Get the value of the “allocator” field. When overloading is enabled, this is equivalent to

get memory #allocator

setMemoryAllocator :: MonadIO m => Memory -> Ptr Allocator -> m ()

Set the value of the “allocator” field. When overloading is enabled, this is equivalent to

set memory [ #allocator := value ]

maxsize

the maximum size allocated

getMemoryMaxsize :: MonadIO m => Memory -> m Word64

Get the value of the “maxsize” field. When overloading is enabled, this is equivalent to

get memory #maxsize

setMemoryMaxsize :: MonadIO m => Memory -> Word64 -> m ()

Set the value of the “maxsize” field. When overloading is enabled, this is equivalent to

set memory [ #maxsize := value ]

miniObject

parent structure

getMemoryMiniObject :: MonadIO m => Memory -> m MiniObject

Get the value of the “mini_object” field. When overloading is enabled, this is equivalent to

get memory #miniObject

offset

the offset where valid data starts

getMemoryOffset :: MonadIO m => Memory -> m Word64

Get the value of the “offset” field. When overloading is enabled, this is equivalent to

get memory #offset

setMemoryOffset :: MonadIO m => Memory -> Word64 -> m ()

Set the value of the “offset” field. When overloading is enabled, this is equivalent to

set memory [ #offset := value ]

parent

parent memory block

clearMemoryParent :: MonadIO m => Memory -> m ()

Set the value of the “parent” field to Nothing. When overloading is enabled, this is equivalent to

clear #parent

getMemoryParent :: MonadIO m => Memory -> m (Maybe Memory)

Get the value of the “parent” field. When overloading is enabled, this is equivalent to

get memory #parent

setMemoryParent :: MonadIO m => Memory -> Ptr Memory -> m ()

Set the value of the “parent” field. When overloading is enabled, this is equivalent to

set memory [ #parent := value ]

size

the size of valid data

getMemorySize :: MonadIO m => Memory -> m Word64

Get the value of the “size” field. When overloading is enabled, this is equivalent to

get memory #size

setMemorySize :: MonadIO m => Memory -> Word64 -> m ()

Set the value of the “size” field. When overloading is enabled, this is equivalent to

set memory [ #size := value ]