IGpuBuffer

Description

interface Tinman.Terrain.Rendering.IGpuBuffer

Derived from

ICapacity
INativeHandle
IResource

Extended by

GpuBufferBase abstract
IIndexBuffer
IVertexBuffer

A GPU buffer, storing elements of fixed size, typically stored in high-performance memory.

Buffer data is written in binary form, usually in a structured format (for example, a vertex buffer). A buffer may have an element size of zero (see ElementSize). In this case, the buffer has an undefined structure and is used as a raw byte buffer. The behaviour of buffer updates depends on the ResourceAccessPattern of the buffer and the used GpuUpdateFlag:

         | Discard | NoOverwrite
---------+---------+------------
Static   |    -    |     -
---------+---------+------------
Dynamic  |   (A)   |    (A)
---------+----------------------
Mappable |   (B)   |    (C)

Buffer updates behave like this:

  • (A)
    Only the content in the update region is discarded. All other content remains valid.

  • (B)
    The whole content is discarded and must be specified again subsequently.

  • (C)
    The existing content remains valid and may be updated without stalling the GPU. However, the application must ensure that no data gets updated while the GPU is still using it.

When creating a non-static GPU buffer, the specified GpuBufferFlags fully determine the ResourceAccessPattern:

Static GPU buffers are immutable and always have the resource access pattern ResourceAccessPattern.Static.

Public / Methods

Buffer​Map

public method BufferMap → (2)

flag in : GpuUpdateFlag

The update flag to apply. Will be ignored for ResourceAccessPattern.Dynamic buffers. Using GpuUpdateFlag.Discard with ResourceAccessPattern.Mappable buffers allows the implementation to discard the content of the whole buffer.

maximum opt : int32 = -1

[-1..ICapacity.Capacity]
Maximum value that will be passed to the count parameter of BufferPrepare. If -1, ICapacity.Capacity will be used.

returns → ByteBuffer

The byte buffer to use for writing updated values: the position is 0 (which points to the start of the first element resp. byte in this GPU buffer), the capacity encompasses at least maximum opt elements resp. bytes and the limit is 0. Before any data may be written, BufferPrepare must be called in order to prepare the returned buffer.

Maps a region of this buffer for writing.

This is the preferred way of updating a GPU buffer with ResourceAccessPattern.Mappable access.

This method can also be used on GPU buffers with ResourceAccessPattern.Dynamic access. In this case, the implementing class will transparently map the API calls to BufferUpdate, doing one call per consecutive run of prepared buffer ranges, see BufferPrepare.

See also

IGpuBuffer.BufferUnmap

Buffer​Prepare

public method BufferPrepare → (2)

first opt : int32 = 0

[0..ICapacity.Capacity]
Index of the first element resp. byte in this buffer to update.

count opt : int32 = -1

[-1..ICapacity.Capacity-first]
Total number of elements resp. bytes to update in this buffer. If -1, the value min(countMax,Capacity-first) will be used, where countMax is the maximum count that has been passed to BufferMap.

Prepares the buffer that has been returned by BufferMap for writing to a range of elements resp. bytes.

This method may only be called between calls to BufferMap and BufferUnmap.

See also

IGpuBuffer.ElementSize

Buffer​Unmap

public method BufferUnmap → ()

Unmaps a this buffer.

Calling BufferUnmap on an immutable buffer or without a prior call to BufferMap does not have any effect, the method just returns silently.

See also

IGpuBuffer.BufferMap

Buffer​Update

public method BufferUpdate → (5)

first in : int32

[>=0]
Index of the first element resp. byte in this buffer to update.

values in : ByteBuffer

[not-null]
A buffer holding the updated elements resp. bytes. The buffer position and limit will neither be modified nor taken into account by this method.

offset in : int32

[>=0]
Offset into values in to first element resp. byte to read.

count in : int32

[>=0]
Total number of elements resp. bytes to update in this buffer.

flag opt : GpuUpdateFlag = GpuUpdateFlag.Discard

The update flag to apply. Will be ignored for ResourceAccessPattern.Dynamic buffers. Using GpuUpdateFlag.Discard with ResourceAccessPattern.Mappable buffers allows the implementation to discard the content of the whole buffer.

Updates a range of elements in the buffer.

To prevent an overflow in the GPU buffer, the given data will be truncated by reducing the count in parameter, if necessary. The calling code is responsible for preventing a buffer underflow of values in.

This is the preferred way of updating a GPU buffer with ResourceAccessPattern.Dynamic access.

This method can also be used on GPU buffers with ResourceAccessPattern.Mappable access. In this case, the implementing class will transparently map the API calls to BufferMap, BufferPrepare and BufferUnmap.

See also

IGpuBuffer.ElementSize

Buffer​Update​Array

public method BufferUpdateArray → (5)

first in : int32

[>=0]
Index of the first 32-bit integer value in the buffer to update.

values in : int32 [ ]

[not-null]
An array holding the updated 32-bit integer values.

offset in : int32

[>=0]
Offset into values in to first 32-bit integer value to read.

count in : int32

[>=0]
Total number of 32-bit integer values to copy from values in to this buffer.

flag opt : GpuUpdateFlag = GpuUpdateFlag.Discard

The update flag to apply. Will be ignored for ResourceAccessPattern.Dynamic buffers. Using GpuUpdateFlag.Discard with ResourceAccessPattern.Mappable buffers allows the implementation to discard the content of the whole buffer.

Updates a range of 32-bit integer values in the buffer.

This method assumes that this buffer has an element size of 4 bytes. If the buffer has a different element size, it will return silently. This method is usually used in conjunction with IIndexBuffers, which always have an element size of 4 bytes.

To prevent an overflow in the GPU buffer, the given data will be truncated by reducing the count in parameter, if necessary. The calling code is responsible for preventing a buffer underflow of values in.

This is the preferred way of updating a GPU buffer with ResourceAccessPattern.Dynamic access.

This method can also be used on GPU buffers with ResourceAccessPattern.Mappable access. In this case, the implementing class will transparently map the API calls to BufferMap, BufferPrepare and BufferUnmap.

Public / Attributes

Element​Size

[Constant]
public attribute ElementSize → (get)

value : int32

[>=0]
The element size, in bytes; always a multiple of four. Will be 0 iff this buffer has an undefined structure and is used as a raw byte buffer. In this case, the capacity will give the buffer size in bytes (also always a multiple of four), instead of the element count.

The fixed element size of this buffer.