Home -> IDataArray

Declaration

class IDataArray;

Description

The IDataArray interface defines an array of one or more data structures. This maps to the concept of the StructuredBuffer/RWStructuredBuffer types in the HLSL shader language. Additionally, an IDataArray supports an attached atomic counter value which can be atomically modified within shaders, and easily reset and read back on the CPU. The IDataArray type is also able to act as a source for indirect draw parameters, making it ideal as a buffer to write to from a compute shader for indirect drawing. Low-level atomic operations are also supported on regions of an IDataArray. When used with atomic operations or for indirect drawing, the ByteAddressBuffer/RWByteAddressBuffer HLSL shader types must be used instead. It is also possible to schedule a transfer from one IDataArray to another entirely on the GPU using the QueueDataTransfer method.

ImportantImportant

There are similarities between the IDataArray and the ITexelArray type. Both define potentially very large buffers of data, which can be read and written from both shaders and the CPU. There are distinct differences however. The ITexelArray type defines a regular array of vectors, with a specific list of supported types. Because the type is explicit and known by the hardware, automatic format conversion is supported for many data types when reading or writing from shaders. Additionally, an ITexelArray is able to alias an IIndexBuffer or an IVertexBuffer, allowing these buffers to be written from a shader, such as a compute shader. The IDataArray type on the other hand contains an array of structures, which are an arbitrary block of bytes. These data structures can be mapped to complex struct types within your shader, allowing a potentially large collection of differing types of values to be easily encoded in each entry of the array. The opaque nature of these structures to hardware however, means no automatic format conversion is possible, nor is it possible to alias an IIndexBuffer or IVertexBuffer. On the other hand, IDataArray can be used to perform indirect drawing, and atomic memory operations within shaders. You should consider the structure of your data and the features required, and select the array type which best fits your usage.

Enumerations

Name Description
Public Enum UsageFlags
Flags to inform the renderer on how this data array will be used

Enumerations (Inherited from IResourceArray)

Name Description
Public Enum PerformanceHint
Flags to provide hints to the graphics system about how the application will use this buffer. Correct use of performance hints allows the renderer to optimize the way the data is stored and modified to give the best performance.
Public Enum DataPersistenceFlags
Flags to provide hints to the graphics system about the required lifetime of data stored in this buffer. These flags can be used to reduce memory requirements or increase performance in some circumstances.

Members

Initialization methods

Name Description
Public member Delete
Schedules the object for deletion. After calling this method, the object will be destroyed after the current frame completes drawing.
Public member AllocateMemory
Attempts to allocate memory for the buffer using the defined buffer layout and page settings
Public member SetBufferLayout
Defines the layout of the buffer, and whether it has an attached counter. Must be set before calling AllocateMemory.

Usage methods

Name Description
Public member SetUsageFlags
Informs the renderer on how this buffer will be used. Certain operations are disallowed unless usage flags have been set to inform the renderer in advance that those operations may be requested.

Usage methods (Inherited from IResourceArray)

Name Description
Public member SetPerformanceHints
Provides hints to the renderer about how this object will be used. Correct use of hints is important to optimize performance.
Public member SetDataPersistenceFlags
Provides hints to the graphics system about the required lifetime of data stored in this buffer. This can be used to reduce memory requirements or increase performance in some circumstances.

Data methods

Name Description
Public member SetInitialData
Supplies initial data to use when allocating the buffer. Note that the supplied memory must remain valid and accessible until the AllocateMemory method is called.
Public member QueueDataUpdate
Updates data in the buffer. Unlike the SetInitialData method, the provided memory can be modified or deallocated immediately after this method returns.
Public member QueueDataTransfer
Schedules a transfer from one IDataArray to another, within GPU memory.
Public member UpdateCounterResetValue
Modifies the reset value to use for the counter, if the buffer has been created with one attached.

Output capture methods

Name Description
Public member AddOutputCaptureTarget
Adds the specified output capture target to this data array. This allows data written to the array from within shader programs to be retrieved by the application.
Public member RemoveOutputCaptureTarget
Removes the specified output capture target from this data array.

See also