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

Constructors

Memory (ManagedPtr Memory)

Instances

BoxedObject Memory

Methods

boxedType :: Memory -> IO GType

(~) AttrOpTag tag AttrSet => Constructible Memory tag

Methods

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

((~) * info (ResolveMemoryMethod t Memory), MethodInfo * info Memory p) => IsLabel t (Memory -> p)

Methods

fromLabel :: Proxy# Symbol t -> Memory -> p

((~) * info (ResolveMemoryMethod t Memory), MethodInfo * info Memory p) => IsLabelProxy t (Memory -> p)

Methods

fromLabelProxy :: Proxy Symbol t -> Memory -> p

HasAttributeList * Memory

((~) * signature (MapInfo -> m ()), MonadIO m) => MethodInfo * MemoryUnmapMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryUnmapMethodInfo Memory -> signature -> s

((~) * signature (Int64 -> Int64 -> m Memory), MonadIO m) => MethodInfo * MemoryShareMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryShareMethodInfo Memory -> signature -> s

((~) * signature (Int64 -> Word64 -> m ()), MonadIO m) => MethodInfo * MemoryResizeMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryResizeMethodInfo Memory -> signature -> s

((~) * signature ([MapFlags] -> m (Bool, MapInfo)), MonadIO m) => MethodInfo * MemoryMapMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryMapMethodInfo Memory -> signature -> s

((~) * signature ([MapFlags] -> m (Maybe Memory, MapInfo)), MonadIO m) => MethodInfo * MemoryMakeMappedMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryMakeMappedMethodInfo Memory -> signature -> s

((~) * signature (Text -> m Bool), MonadIO m) => MethodInfo * MemoryIsTypeMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryIsTypeMethodInfo Memory -> signature -> s

((~) * signature (Memory -> Word64 -> m Bool), MonadIO m) => MethodInfo * MemoryIsSpanMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryIsSpanMethodInfo Memory -> signature -> s

((~) * signature (Word64 -> Word64 -> m Word64), MonadIO m) => MethodInfo * MemoryGetSizesMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryGetSizesMethodInfo Memory -> signature -> s

((~) * signature (Int64 -> Int64 -> m Memory), MonadIO m) => MethodInfo * MemoryCopyMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryCopyMethodInfo Memory -> signature -> s

type AttributeList Memory

type AttributeList Memory

newZeroMemory :: MonadIO m => m Memory

Construct a Memory struct initialized to zero.

noMemory :: Maybe Memory

Methods

copy

data MemoryCopyMethodInfo

Instances

((~) * signature (Int64 -> Int64 -> m Memory), MonadIO m) => MethodInfo * MemoryCopyMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryCopyMethodInfo Memory -> signature -> s

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

data MemoryGetSizesMethodInfo

Instances

((~) * signature (Word64 -> Word64 -> m Word64), MonadIO m) => MethodInfo * MemoryGetSizesMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryGetSizesMethodInfo Memory -> signature -> s

memoryGetSizes

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem: a Memory

-> Word64

offset: pointer to offset

-> Word64

maxsize: pointer to maxsize

-> m Word64

Returns: the current sizes of mem

Get the current size, offset and maxsize of mem.

isSpan

data MemoryIsSpanMethodInfo

Instances

((~) * signature (Memory -> Word64 -> m Bool), MonadIO m) => MethodInfo * MemoryIsSpanMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryIsSpanMethodInfo Memory -> signature -> s

memoryIsSpan

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem1: a Memory

-> Memory

mem2: a Memory

-> Word64

offset: a pointer to a result offset

-> m Bool

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

data MemoryIsTypeMethodInfo

Instances

((~) * signature (Text -> m Bool), MonadIO m) => MethodInfo * MemoryIsTypeMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryIsTypeMethodInfo Memory -> signature -> s

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

data MemoryMakeMappedMethodInfo

Instances

((~) * signature ([MapFlags] -> m (Maybe Memory, MapInfo)), MonadIO m) => MethodInfo * MemoryMakeMappedMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryMakeMappedMethodInfo Memory -> signature -> s

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

data MemoryMapMethodInfo

Instances

((~) * signature ([MapFlags] -> m (Bool, MapInfo)), MonadIO m) => MethodInfo * MemoryMapMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryMapMethodInfo Memory -> signature -> s

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

data MemoryResizeMethodInfo

Instances

((~) * signature (Int64 -> Word64 -> m ()), MonadIO m) => MethodInfo * MemoryResizeMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryResizeMethodInfo Memory -> signature -> s

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

data MemoryShareMethodInfo

Instances

((~) * signature (Int64 -> Int64 -> m Memory), MonadIO m) => MethodInfo * MemoryShareMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryShareMethodInfo Memory -> signature -> s

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

data MemoryUnmapMethodInfo

Instances

((~) * signature (MapInfo -> m ()), MonadIO m) => MethodInfo * MemoryUnmapMethodInfo Memory signature

Methods

overloadedMethod :: MethodProxy MemoryUnmapMethodInfo Memory -> signature -> s

memoryUnmap

Arguments

:: (HasCallStack, MonadIO m)

=> Memory

mem: a Memory

-> MapInfo

info: a MapInfo

-> m ()

Release the memory obtained with memoryMap

Properties

align

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

memory_align :: AttrLabelProxy "align"

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

allocator

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

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

memory_allocator :: AttrLabelProxy "allocator"

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

maxsize

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

memory_maxsize :: AttrLabelProxy "maxsize"

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

miniObject

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

memory_miniObject :: AttrLabelProxy "miniObject"

offset

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

memory_offset :: AttrLabelProxy "offset"

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

parent

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

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

memory_parent :: AttrLabelProxy "parent"

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

size

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

memory_size :: AttrLabelProxy "size"

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