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.
Important
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 | |
|---|---|---|
| UsageFlags |
Flags to inform the renderer on how this data array will be used
|
Enumerations (Inherited from IResourceArray)
| Name | Description | |
|---|---|---|
| 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.
|
|
| 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 | |
|---|---|---|
| Delete |
Schedules the object for deletion. After calling this method, the object will be destroyed after the current
frame completes drawing.
|
|
| AllocateMemory |
Attempts to allocate memory for the buffer using the defined buffer layout and page settings
|
|
| SetBufferLayout |
Defines the layout of the buffer, and whether it has an attached counter. Must be set before calling AllocateMemory.
|
Usage methods
| Name | Description | |
|---|---|---|
| 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 | |
|---|---|---|
| SetPerformanceHints |
Provides hints to the renderer about how this object will be used. Correct use of hints is important to optimize performance.
|
|
| 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 | |
|---|---|---|
| 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.
|
|
| QueueDataUpdate |
Updates data in the buffer. Unlike the SetInitialData method, the provided memory can be
modified or deallocated immediately after this method returns.
|
|
| QueueDataTransfer |
Schedules a transfer from one IDataArray to another, within GPU memory.
|
|
| UpdateCounterResetValue |
Modifies the reset value to use for the counter, if the buffer has been created with one attached.
|
Output capture methods
| Name | Description | |
|---|---|---|
| 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.
|
|
| RemoveOutputCaptureTarget |
Removes the specified output capture target from this data array.
|