Package icyllis.arc3d.engine

Class Buffer

java.lang.Object
icyllis.arc3d.engine.Resource
icyllis.arc3d.engine.Buffer
All Implemented Interfaces:
RefCounted
Direct Known Subclasses:
GLBuffer, VulkanBuffer
public abstract class Buffer extends Resource
Represents a single device-visible memory region that may be used as mesh buffers and staging buffers. A buffer cannot be accessed by both CPU and GPU simultaneously, it's either mapped by client pipeline or executing in command buffer.

  • Field Details

    • kRead_MapMode

      public static final int kRead_MapMode
      Maps for reading. The effect of writes is undefined.
      See Also:

    • kWriteDiscard_MapMode

      public static final int kWriteDiscard_MapMode
      Maps for writing. The existing contents are discarded and the initial contents of the buffer. Reads (even after overwriting initial contents) should be avoided for performance reasons as the memory may not be cached.
      See Also:

    • mSize

      protected final long mSize

    • mUsage

      protected final int mUsage

  • Constructor Details

    • Buffer

      protected Buffer(Context context, long size, int usage)

  • Method Details

    • getSize

      public final long getSize()
      Returns:
      allocation size of the buffer in bytes

    • getUsage

      public final int getUsage()
      Returns:
      Engine.BufferUsageFlags

    • map

      public final long map()
      Maps the buffer to be read or written by the CPU.

      Mapping works only for Engine.BufferUsageFlags.kHostVisible buffers. Writing to or reading from a buffer that is currently executing in command buffer results in undefined behavior. It is an error to draw from the buffer while it is mapped or transfer to/from the buffer, no matter whether it's persistently mapped or not.

      If the buffer is of type Engine.BufferUsageFlags.kReadback then it is mapped for reading only. Otherwise it is mapped writing only. Writing to a buffer that is mapped for reading or vice versa produces undefined results. If the buffer is mapped for writing then the buffer's previous contents are invalidated.

      Returns:
      a valid pointer to the mapped data, or nullptr if map failed

    • map

      public final long map(long offset, long size)
      Maps the buffer to be read or written by the CPU.

      Mapping works only for Engine.BufferUsageFlags.kHostVisible buffers. Writing to or reading from a buffer that is currently executing in command buffer results in undefined behavior. It is an error to draw from the buffer while it is mapped or transfer to/from the buffer, no matter whether it's persistently mapped or not.

      If the buffer is of type Engine.BufferUsageFlags.kReadback then it is mapped for reading only. Otherwise it is mapped writing only. Writing to a buffer that is mapped for reading or vice versa produces undefined results. If the buffer is mapped for writing then the buffer's previous contents are invalidated.

      Parameters:
      offset - the map offset
      size - the map size
      Returns:
      a valid pointer to the mapped data, or nullptr if map failed

    • unmap

      public final void unmap()
      Unmaps the buffer if it is mapped.

      The pointer returned by the previous map() will no longer be valid.

    • unmap

      public final void unmap(long size)
      Unmaps the buffer if it is mapped.

      The pointer returned by the previous map(long, long) will no longer be valid. The size can be smaller than that of the previous map(long, long) call. If it is 0, then any modification to the mapped buffer may not flush into the buffer at all.

    • onMap

      protected abstract long onMap(int mode, long offset, long size)

    • onUnmap

      protected abstract void onUnmap(int mode, long offset, long size)

    • isMapped

      public final boolean isMapped()
      Queries whether the buffer has been mapped by map(long, long), this is mostly used for validation.
      Returns:
      true if the buffer is mapped, false otherwise.

    • getMappedBuffer

      public final long getMappedBuffer()
      Queries the pointer returned by the previous map(long, long) if isMapped() returns true, otherwise the pointer is invalid, this is mostly used for validation.
      Returns:
      the pointer to the mapped buffer if mapped.

    • updateData

      public boolean updateData(int offset, int size, long data)
      Updates the buffer data.

      The size of the buffer will be preserved. The src data will be placed at offset. If preserve is false then any remaining content before/after the range [offset, offset+size) becomes undefined.

      The buffer must not be mapped.

      Fails for Engine.BufferUsageFlags.kReadback.

      Note that buffer updates do not go through Context and therefore are not serialized with other operations.

      Returns:
      returns true if the update succeeds, false otherwise.