Class Memory

java.lang.Object
org.javagi.base.ProxyInstance
org.freedesktop.gstreamer.gst.Memory
All Implemented Interfaces:
Proxy
@Generated("org.javagi.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 @Nullable Memory
    wrapped(Set<MemoryFlags> flags, @Nullable byte @Nullable [] data, long maxsize, long offset)
    Allocate a new memory block that wraps the given data.
    static @Nullable Memory
    wrapped(MemoryFlags flags, @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 ProxyInstance

    equals, handle, hashCode

    Methods inherited from class 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 @Nullable Memory wrapped(Set<MemoryFlags> flags, @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, @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.