ID3D12GraphicsCommandList::ClearUnorderedAccessViewUint method (d3d12.h)

Sets all the elements in a unordered-access view (UAV) to the specified integer values.

Important

This behaves like a compute operation in that it isn't ordered with respect to surrounding work such as Dispatch calls. To ensure ordering, barrier calls must be issued before and/or after the ClearUnorderedAccessViewXxx call as needed. It might appear on some drivers that such barriers aren't necessary. But implicit barriers are not a spec guarantee; so they can't be relied upon. This is in contrast to ClearDepthStencilView and ClearRenderTargetView which (like DrawXxx commands), respect command list ordering.

Syntax

void ClearUnorderedAccessViewUint(
  D3D12_GPU_DESCRIPTOR_HANDLE ViewGPUHandleInCurrentHeap,
  D3D12_CPU_DESCRIPTOR_HANDLE ViewCPUHandle,
  ID3D12Resource              *pResource,
  const UINT [4]              Values,
  UINT                        NumRects,
  const D3D12_RECT            *pRects
);

Parameters

ViewGPUHandleInCurrentHeap

Type: [in] D3D12_GPU_DESCRIPTOR_HANDLE

A D3D12_GPU_DESCRIPTOR_HANDLE that references an initialized descriptor for the unordered-access view (UAV) that is to be cleared. This descriptor must be in a shader-visible descriptor heap, which must be set on the command list via SetDescriptorHeaps.

ViewCPUHandle

Type: [in] D3D12_CPU_DESCRIPTOR_HANDLE

A D3D12_CPU_DESCRIPTOR_HANDLE in a non-shader visible descriptor heap that references an initialized descriptor for the unordered-access view (UAV) that is to be cleared.

Important

This descriptor must not be in a shader-visible descriptor heap. This is to allow drivers that implement the clear as a fixed-function hardware operation (rather than as a dispatch) to efficiently read from the descriptor, as shader-visible heaps may be created in WRITE_BACK memory (similar to D3D12_HEAP_TYPE_UPLOAD heap types), and CPU reads from this type of memory are prohibitively slow.

pResource

Type: [in] ID3D12Resource*

A pointer to the ID3D12Resource interface that represents the unordered-access-view (UAV) resource to clear.

Values

Type: [in] const UINT[4]

A 4-component array that containing the values to fill the unordered-access-view resource with.

NumRects

Type: [in] UINT

The number of rectangles in the array that the pRects parameter specifies.

pRects

Type: [in] const D3D12_RECT*

An array of D3D12_RECT structures for the rectangles in the resource view to clear. If NULL, ClearUnorderedAccessViewUint clears the entire resource view.

Return value

None

Remarks

Runtime validation

Validation failure results in the call to ID3D12GraphicsCommandList::Close returning E_INVALIDARG.

Debug layer

The debug layer issues errors if the input values are outside of a normalized range.

The debug layer issues an error if the subresources referenced by the view aren't in the appropriate state. For ClearUnorderedAccessViewUint, the state must be D3D12_RESOURCE_STATE_UNORDERED_ACCESS.

Requirements

Requirement Value
Target Platform Windows
Header d3d12.h
Library D3d12.lib
DLL D3d12.dll

See also

ID3D12GraphicsCommandList interface