ID3D12GraphicsCommandList::ClearDepthStencilView method

Clears the depth-stencil resource.

Syntax

void ClearDepthStencilView(
  D3D12_CPU_DESCRIPTOR_HANDLE DepthStencilView,
  D3D12_CLEAR_FLAGS           ClearFlags,
  FLOAT                       Depth,
  UINT8                       Stencil,
  UINT                        NumRects,
  const D3D12_RECT            *pRects
);

Parameters

DepthStencilView

Type: D3D12_CPU_DESCRIPTOR_HANDLE

Describes the CPU descriptor handle that represents the start of the heap for the depth stencil to be cleared.

ClearFlags

Type: D3D12_CLEAR_FLAGS

A combination of D3D12_CLEAR_FLAGS values that are combined by using a bitwise OR operation. The resulting value identifies the type of data to clear (depth buffer, stencil buffer, or both).

Depth

Type: FLOAT

A value to clear the depth buffer with. This value will be clamped between 0 and 1.

Stencil

Type: UINT8

A value to clear the stencil buffer with.

NumRects

Type: UINT

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

pRects

Type: const D3D12_RECT*

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

Return Value

Returns nothing.

Remarks

ClearDepthStencilView may be used to initialize resources which alias the same heap memory. See CreatePlacedResource for more details.

Runtime validation

For floating-point inputs, the runtime will set denormalized values to 0 (while preserving NANs).

Validation failure will result in the call to Close returning E_INVALIDARG.

Debug layer

The debug layer will issue errors if the input colors are denormalized.

The debug layer will issue an error if the subresources referenced by the view are not in the appropriate state. For ClearDepthStencilView, the state must be in the state D3D12_RESOURCE_STATE_DEPTH_WRITE.

Examples

The D3D12Bundles sample uses ID3D12GraphicsCommandList::ClearDepthStencilView as follows:

C++
// Pipeline objects.
D3D12_VIEWPORT m_viewport;
ComPtr m_swapChain;
ComPtr m_device;
ComPtr m_renderTargets[FrameCount];
ComPtr m_depthStencil;
ComPtr m_commandAllocator;
ComPtr m_commandList;
ComPtr m_commandQueue;
ComPtrm_rootSignature;
ComPtr m_rtvHeap;
ComPtr m_cbvSrvHeap;
ComPtr m_dsvHeap;
ComPtr m_samplerHeap;
ComPtr m_pipelineState1;
ComPtr m_pipelineState2;
D3D12_RECT m_scissorRect;
C++
void D3D12Bundles::PopulateCommandList(FrameResource* pFrameResource)
{
    // Command list allocators can only be reset when the associated
    // command lists have finished execution on the GPU; apps should use
    // fences to determine GPU execution progress.
    ThrowIfFailed(m_pCurrentFrameResource->m_commandAllocator->Reset());
// However, when ExecuteCommandList() is called on a particular command
// list, that command list can then be reset at any time and must be before
// re-recording.
ThrowIfFailed(m_commandList->Reset(m_pCurrentFrameResource->m_commandAllocator.Get(), m_pipelineState1.Get()));

// Set necessary state.
m_commandList->SetGraphicsRootSignature(m_rootSignature.Get());

ID3D12DescriptorHeap* ppHeaps[] = { m_cbvSrvHeap.Get(), m_samplerHeap.Get() };
m_commandList->SetDescriptorHeaps(_countof(ppHeaps), ppHeaps);

m_commandList->RSSetViewports(1, &m_viewport);
m_commandList->RSSetScissorRects(1, &m_scissorRect);

// Indicate that the back buffer will be used as a render target.
m_commandList->ResourceBarrier(1, &CD3DX12_RESOURCE_BARRIER::Transition(m_renderTargets[m_frameIndex].Get(), D3D12_RESOURCE_STATE_PRESENT, D3D12_RESOURCE_STATE_RENDER_TARGET));

CD3DX12_CPU_DESCRIPTOR_HANDLE rtvHandle(m_rtvHeap->GetCPUDescriptorHandleForHeapStart(), m_frameIndex, m_rtvDescriptorSize);
CD3DX12_CPU_DESCRIPTOR_HANDLE dsvHandle(m_dsvHeap->GetCPUDescriptorHandleForHeapStart());
m_commandList->OMSetRenderTargets(1, &rtvHandle, FALSE, &dsvHandle);

// Record commands.
const float clearColor[] = { 0.0f, 0.2f, 0.4f, 1.0f };
m_commandList->ClearRenderTargetView(rtvHandle, clearColor, 0, nullptr);
m_commandList->ClearDepthStencilView(m_dsvHeap->GetCPUDescriptorHandleForHeapStart(), D3D12_CLEAR_FLAG_DEPTH, 1.0f, 0, 0, nullptr);

if (UseBundles)
{
    // Execute the prebuilt bundle.
    m_commandList->ExecuteBundle(pFrameResource->m_bundle.Get());
}
else
{
    // Populate a new command list.
    pFrameResource->PopulateCommandList(m_commandList.Get(), m_pipelineState1.Get(), m_pipelineState2.Get(), m_currentFrameResourceIndex, m_numIndices, &m_indexBufferView,
        &m_vertexBufferView, m_cbvSrvHeap.Get(), m_cbvSrvDescriptorSize, m_samplerHeap.Get(), m_rootSignature.Get());
}

// Indicate that the back buffer will now be used to present.
m_commandList->ResourceBarrier(1, &CD3DX12_RESOURCE_BARRIER::Transition(m_renderTargets[m_frameIndex].Get(), D3D12_RESOURCE_STATE_RENDER_TARGET, D3D12_RESOURCE_STATE_PRESENT));

ThrowIfFailed(m_commandList->Close());

}

The D3D12Multithreading sample uses ID3D12GraphicsCommandList::ClearDepthStencilView as follows:

C++
void FrameResource::Init()
{
    // Reset the command allocators and lists for the main thread.
    for (int i = 0; i < commandlistcount;="" i++)="" {="" throwiffailed(m_commandallocators[i]-="">Reset());
        ThrowIfFailed(m_commandLists[i]->Reset(m_commandAllocators[i].Get(), m_pipelineState.Get()));
    }
// Clear the depth stencil buffer in preparation for rendering the shadow map.
m_commandLists[CommandListPre]->ClearDepthStencilView(m_shadowDepthView, D3D12_CLEAR_FLAG_DEPTH, 1.0f, 0, 0, nullptr);

// Reset the worker command allocators and lists.
for (int i = 0; i < NumContexts; i++)
{
    ThrowIfFailed(m_shadowCommandAllocators[i]->Reset());
    ThrowIfFailed(m_shadowCommandLists[i]->Reset(m_shadowCommandAllocators[i].Get(), m_pipelineStateShadowMap.Get()));

    ThrowIfFailed(m_sceneCommandAllocators[i]->Reset());
    ThrowIfFailed(m_sceneCommandLists[i]->Reset(m_sceneCommandAllocators[i].Get(), m_pipelineState.Get()));
}

}

C++
// Assemble the CommandListPre command list.
void D3D12Multithreading::BeginFrame()
{
    m_pCurrentFrameResource->Init();
// Indicate that the back buffer will be used as a render target.
m_pCurrentFrameResource->m_commandLists[CommandListPre]->ResourceBarrier(1, &CD3DX12_RESOURCE_BARRIER::Transition(m_renderTargets[m_frameIndex].Get(), D3D12_RESOURCE_STATE_PRESENT, D3D12_RESOURCE_STATE_RENDER_TARGET));

// Clear the render target and depth stencil.
const float clearColor[] = { 0.0f, 0.0f, 0.0f, 1.0f };
CD3DX12_CPU_DESCRIPTOR_HANDLE rtvHandle(m_rtvHeap->GetCPUDescriptorHandleForHeapStart(), m_frameIndex, m_rtvDescriptorSize);
m_pCurrentFrameResource->m_commandLists[CommandListPre]->ClearRenderTargetView(rtvHandle, clearColor, 0, nullptr);
m_pCurrentFrameResource->m_commandLists[CommandListPre]->ClearDepthStencilView(m_dsvHeap->GetCPUDescriptorHandleForHeapStart(), D3D12_CLEAR_FLAG_DEPTH, 1.0f, 0, 0, nullptr);

ThrowIfFailed(m_pCurrentFrameResource->m_commandLists[CommandListPre]->Close());

}

// Assemble the CommandListMid command list. void D3D12Multithreading::MidFrame() { // Transition our shadow map from the shadow pass to readable in the scene pass. m_pCurrentFrameResource->SwapBarriers();

ThrowIfFailed(m_pCurrentFrameResource->m_commandLists[CommandListMid]->Close());

}

See Example Code in the D3D12 Reference.

Requirements

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

See Also

ID3D12GraphicsCommandList