Package org.freedesktop.gstreamer.gst

Class Memory

java.lang.Object

org.javagi.base.ProxyInstance

org.freedesktop.gstreamer.gst.Memory

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class Memory
extends ProxyInstance

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

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 gst_allocator_alloc() method call. When null is used as the allocator, the default allocator will be used.

New allocators can be registered with gst_allocator_register(). Allocators are identified by name and can be retrieved with gst_allocator_find(). gst_allocator_set_default() can be used to change the default allocator.

New memory can be created with gst_memory_new_wrapped() 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 gst_memory_get_sizes() and gst_memory_resize() respectively.

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

Memory can be copied with gst_memory_copy(), which will return a writable copy. gst_memory_share() 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 gst_memory_is_span() returns true.

Constructor Summary

Constructors

Constructor	Description
Memory()	Allocate a new Memory.
Memory(Arena arena)	Allocate a new Memory.
Memory(MemorySegment address)	Create a Memory proxy instance for the provided memory address.
Memory(MiniObject miniObject, Allocator allocator, Memory parent, long maxsize, long align, long offset, long size)	Allocate a new Memory with the fields set to the provided values.
Memory(MiniObject miniObject, Allocator allocator, Memory parent, long maxsize, long align, long offset, long size, Arena arena)	Allocate a new Memory with the fields set to the provided values.

Method Summary

Modifier and Type	Method	Description
@Nullable Memory	copy(long offset, long size)	Return a copy of size bytes from this Memory starting from offset. This copy is guaranteed to be writable.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
long	getSizes(@Nullable Out<Long> offset, @Nullable Out<Long> maxsize)	Get the current size, offset and maxsize of mem.
static @Nullable Type	getType()	Get the GType of the Memory class
void	init(Set<MemoryFlags> flags, Allocator allocator, Memory parent, long maxsize, long align, long offset, long size)	Initializes a newly allocated this Memory with the given parameters.
void	init(MemoryFlags flags, Allocator allocator, Memory parent, long maxsize, long align, long offset, long size)	Initializes a newly allocated this Memory with the given parameters.
boolean	isSpan(Memory mem2, Out<Long> offset)	Check if this Memory and mem2 share the memory with a common parent memory object and that the memory is contiguous.
boolean	isType(String memType)	Check if this Memory if allocated with an allocator for memType.
@Nullable Memory	makeMapped(MapInfo info, int flags)	Create a GstMemory object that is mapped with flags. If this Memory is mappable with flags, this function returns the mapped this Memory directly.
boolean	map(MapInfo info, int flags)	Fill info with the pointer and sizes of the memory in this Memory that can be accessed according to flags.
long	readAlign()	Read the value of the field align.
Allocator	readAllocator()	Read the value of the field allocator.
long	readMaxsize()	Read the value of the field maxsize.
@Nullable MiniObject	readMiniObject()	Read the value of the field mini_object.
long	readOffset()	Read the value of the field offset.
Memory	readParent()	Read the value of the field parent.
long	readSize()	Read the value of the field size.
Memory	ref()	Increase the refcount of this memory.
void	resize(long offset, long size)	Resize the memory region.
Memory	share(long offset, long size)	Return a shared copy of size bytes from this Memory starting from offset. No memory copy is performed and the memory region is simply shared.
void	unmap(MapInfo info)	Release the memory obtained with gst_memory_map()
void	unref()	Decrease the refcount of a memory, freeing it if the refcount reaches 0.
static Memory	wrapped(Set<MemoryFlags> flags, @org.jspecify.annotations.Nullable byte @Nullable [] data, long maxsize, long offset)	Allocate a new memory block that wraps the given data.
static @Nullable Memory	wrapped(MemoryFlags flags, @org.jspecify.annotations.Nullable byte @Nullable [] data, long maxsize, long offset)	Allocate a new memory block that wraps the given data.
void	writeAlign(long align)	Write a value in the field align.
void	writeAllocator(Allocator allocator)	Write a value in the field allocator.
void	writeMaxsize(long maxsize)	Write a value in the field maxsize.
void	writeMiniObject(@Nullable MiniObject miniObject)	Write a value in the field mini_object.
void	writeOffset(long offset)	Write a value in the field offset.
void	writeParent(Memory parent)	Write a value in the field parent.
void	writeSize(long size)	Write a value in the field size.

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Memory

public Memory(MemorySegment address)

Create a Memory proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Memory

public Memory(Arena arena)

Allocate a new Memory.

Parameters:

arena - to control the memory allocation scope

Memory

public Memory()

Allocate a new Memory. The memory is allocated with Arena.ofAuto().

Memory

public Memory(MiniObject miniObject,
 Allocator allocator,
 Memory parent,
 long maxsize,
 long align,
 long offset,
 long size,
 Arena arena)

Allocate a new Memory with the fields set to the provided values.

Parameters:

miniObject - value for the field miniObject

allocator - value for the field allocator

parent - value for the field parent

maxsize - value for the field maxsize

align - value for the field align

offset - value for the field offset

size - value for the field size

arena - to control the memory allocation scope

Memory

public Memory(MiniObject miniObject,
 Allocator allocator,
 Memory parent,
 long maxsize,
 long align,
 long offset,
 long size)

Allocate a new Memory with the fields set to the provided values. The memory is allocated with Arena.ofAuto().

Parameters:

miniObject - value for the field miniObject

allocator - value for the field allocator

parent - value for the field parent

maxsize - value for the field maxsize

align - value for the field align

offset - value for the field offset

size - value for the field size

Method Details

getType

public static @Nullable Type getType()

Get the GType of the Memory class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

readMiniObject

public @Nullable MiniObject readMiniObject()

Read the value of the field mini_object.

Returns:

The value of the field mini_object

writeMiniObject

public void writeMiniObject(@Nullable MiniObject miniObject)

Write a value in the field mini_object.

Parameters:

miniObject - The new value for the field mini_object

readAllocator

public Allocator readAllocator()

Read the value of the field allocator.

Returns:

The value of the field allocator

writeAllocator

public void writeAllocator(Allocator allocator)

Write a value in the field allocator.

Parameters:

allocator - The new value for the field allocator

readParent

public Memory readParent()

Read the value of the field parent.

Returns:

The value of the field parent

writeParent

public void writeParent(Memory parent)

Write a value in the field parent.

Parameters:

parent - The new value for the field parent

readMaxsize

public long readMaxsize()

Read the value of the field maxsize.

Returns:

The value of the field maxsize

writeMaxsize

public void writeMaxsize(long maxsize)

Write a value in the field maxsize.

Parameters:

maxsize - The new value for the field maxsize

readAlign

public long readAlign()

Read the value of the field align.

Returns:

The value of the field align

writeAlign

public void writeAlign(long align)

Write a value in the field align.

Parameters:

align - The new value for the field align

readOffset

public long readOffset()

Read the value of the field offset.

Returns:

The value of the field offset

writeOffset

public void writeOffset(long offset)

Write a value in the field offset.

Parameters:

offset - The new value for the field offset

readSize

public long readSize()

Read the value of the field size.

Returns:

The value of the field size

writeSize

public void writeSize(long size)

Write a value in the field size.

Parameters:

size - The new value for the field size

wrapped

public static Memory wrapped(Set<MemoryFlags> flags,
 @org.jspecify.annotations.Nullable byte @Nullable [] data,
 long maxsize,
 long offset)

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.

Parameters:

flags - GstMemoryFlags

data - data to wrap

maxsize - allocated size of data

offset - offset in data

Returns:

a new GstMemory.

wrapped

public static @Nullable Memory wrapped(MemoryFlags flags,
 @org.jspecify.annotations.Nullable byte @Nullable [] data,
 long maxsize,
 long offset)

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.

Parameters:

flags - GstMemoryFlags

data - data to wrap

maxsize - allocated size of data

offset - offset in data

Returns:

a new GstMemory.

copy

public @Nullable Memory copy(long offset,
 long size)

Return a copy of size bytes from this Memory 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.

Parameters:

offset - offset to copy from

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

Returns:

a new copy of this Memory if the copy succeeded, null otherwise.

getSizes

public long getSizes(@Nullable Out<Long> offset,
 @Nullable Out<Long> maxsize)

Get the current size, offset and maxsize of mem.

Parameters:

offset - pointer to offset

maxsize - pointer to maxsize

Returns:

the current size of this Memory

init

public void init(Set<MemoryFlags> flags,
 Allocator allocator,
 Memory parent,
 long maxsize,
 long align,
 long offset,
 long size)

Initializes a newly allocated this Memory with the given parameters. This function will call gst_mini_object_init() with the default memory parameters.

Parameters:

flags - GstMemoryFlags

allocator - the GstAllocator

parent - the parent of this Memory

maxsize - the total size of the memory

align - the alignment of the memory

offset - The offset in the memory

size - the size of valid data in the memory

init

public void init(MemoryFlags flags,
 Allocator allocator,
 Memory parent,
 long maxsize,
 long align,
 long offset,
 long size)

Initializes a newly allocated this Memory with the given parameters. This function will call gst_mini_object_init() with the default memory parameters.

Parameters:

flags - GstMemoryFlags

allocator - the GstAllocator

parent - the parent of this Memory

maxsize - the total size of the memory

align - the alignment of the memory

offset - The offset in the memory

size - the size of valid data in the memory

isSpan

public boolean isSpan(Memory mem2,
 Out<Long> offset)

Check if this Memory 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 this Memory and mem2 can be merged efficiently by performing gst_memory_share() on the parent object from the returned offset.

Parameters:

mem2 - a GstMemory

offset - a pointer to a result offset

Returns:

true if the memory is contiguous and of a common parent.

isType

public boolean isType(String memType)

Check if this Memory if allocated with an allocator for memType.

Parameters:

memType - a memory type

Returns:

true if this Memory was allocated from an allocator for memType.

Since:

1.2

makeMapped

public @Nullable Memory makeMapped(MapInfo info,
 int flags)

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

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

Parameters:

info - pointer for info

flags - mapping flags

Returns:

a GstMemory object mapped with flags or null when a mapping is not possible.

map

public boolean map(MapInfo info,
 int flags)

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

This function can return false for various reasons:

• the memory backed by this Memory 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 this Memory is valid and until gst_memory_unmap() is called.

For each gst_memory_map() call, a corresponding gst_memory_unmap() call should be done.

Parameters:

info - pointer for info

flags - mapping flags

Returns:

true if the map operation was successful.

ref

public Memory ref()

Increase the refcount of this memory.

Returns:

this Memory (for convenience when doing assignments)

resize

public void resize(long offset,
 long size)

Resize the memory region. this Memory 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.

Parameters:

offset - a new offset

size - a new size

share

public Memory share(long offset,
 long size)

Return a shared copy of size bytes from this Memory 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.

Parameters:

offset - offset to share from

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

Returns:

a new GstMemory.

unmap

public void unmap(MapInfo info)

Release the memory obtained with gst_memory_map()

Parameters:

info - a GstMapInfo

unref

public void unref()

Decrease the refcount of a memory, freeing it if the refcount reaches 0.