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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `Buffer.ResourceKey`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `kRead_MapMode`
  Maps for reading.
  `static final int`
  `kWriteDiscard_MapMode`
  Maps for writing.
  `protected final long`
  `mSize`
  `protected final int`
  `mUsage`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Buffer(Context context, long size, int usage)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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.
  `final long`
  `getSize()`
  `final int`
  `getUsage()`
  `final boolean`
  `isMapped()`
  Queries whether the buffer has been mapped by `map(long, long)`, this is mostly used for validation.
  `final long`
  `map()`
  Maps the buffer to be read or written by the CPU.
  `final long`
  `map(long offset, long size)`
  Maps the buffer to be read or written by the CPU.
  `protected abstract long`
  `onMap(int mode, long offset, long size)`
  `protected abstract void`
  `onUnmap(int mode, long offset, long size)`
  `final void`
  `unmap()`
  Unmaps the buffer if it is mapped.
  `final void`
  `unmap(long size)`
  Unmaps the buffer if it is mapped.
  `boolean`
  `updateData(int offset, int size, long data)`
  Updates the buffer data.

  ### Methods inherited from class icyllis.arc3d.engine.Resource

  `getContext, getDevice, getKey, getLabel, getMemorySize, getUniqueID, hasAnyRefs, hasCacheRef, hasCommandBufferRef, hasUsageRef, isBudgeted, isDestroyed, isPurgeable, isWrapped, onRelease, onSetLabel, ref, refCommandBuffer, setKey, setLabel, setNonCacheable, unref, unrefCommandBuffer`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### kRead_MapMode

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

  - ### 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:
      - Constant Field Values

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