ID3D12GraphicsCommandList::Reset メソッド (d3d12.h)

  • [アーティクル]

新しいコマンド リストが作成されたかのように、コマンド リストを初期状態に戻します。

構文

HRESULT Reset(
  [in]           ID3D12CommandAllocator *pAllocator,
  [in, optional] ID3D12PipelineState    *pInitialState
);

パラメーター

[in] pAllocator

種類: ID3D12CommandAllocator*

デバイスがコマンド リストを作成する ID3D12CommandAllocator オブジェクトへのポインター。

[in, optional] pInitialState

種類: ID3D12PipelineState*

コマンド リストの初期パイプライン状態を含む ID3D12PipelineState オブジェクトへのポインター。 これは省略可能であり、NULL にすることができます。 NULL の場合、ドライバーが未定義の状態を処理する必要がないように、ランタイムによってダミーの初期パイプライン状態が設定されます。 このためのオーバーヘッドは低く、特にコマンド リストの場合、コマンド リストを記録する全体的なコストは、1 つの初期状態設定のコストを小さくする可能性があります。 そのため、最初のパイプライン状態パラメーターが便利でない場合は、設定しないコストはほとんどありません。

一方、バンドルの場合は、バンドルが全体的に小さくなり、頻繁に再利用できるため、初期状態パラメーターの設定を試みる方が理にかなっている可能性があります。

戻り値

種類: HRESULT

成功した場合 は、S_OK を返します。それ以外の場合は、次のいずれかの値を返します。

  • E_FAILリセット呼び出しが行われたときにコマンド リストが "クローズ" 状態になっていないか、デバイスごとの制限を超えた可能性があります。
  • オペレーティング システムのメモリ不足が発生した場合にE_OUTOFMEMORYします。
  • 現在 、アロケーターが "記録" 状態の別のコマンド リストで使用されている場合、または指定したアロケーターが間違った型で作成された場合にE_INVALIDARGします。
その他の可能な戻り値については、「戻りコードのDirect3D 12」を参照してください。

注釈

Reset を使用すると、割り当てなしでコマンド リスト追跡構造を再利用できます。 ID3D12CommandAllocator::Reset とは異なり、Reset はそのコマンド リストの実行中でも呼び出すことができます。 一般的なパターンは、コマンド リストを提出し、その直後にリセットするというものです。これで、割り当て済みのメモリを他のコマンド リストに再利用できるようになります。

直接コマンド リストとバンドルの両方に Reset を使用できます。

Reset が入力として受け取るコマンド アロケーターは、一度に複数の記録コマンド リストに関連付けることができます。 アロケーターの種類 (直接コマンド リストまたはバンドル) は、作成されるコマンド リストの種類と一致する必要があります。

バンドルでリソース ヒープが指定されていない場合、記述子テーブルをバインドする変更を加えることはできません。 どちらの場合も、バンドルはバンドル内のリソース ヒープを変更できません。 バンドルにヒープが指定されている場合、ヒープは呼び出し元の 'parent' コマンド リストのヒープと一致する必要があります。

ランタイムの検証

アプリが Reset を呼び出す前に、コマンド 一覧が "closed" 状態である必要があります。 コマンド リストが "closed" 状態でない場合、リセットは失敗します。
メモID3D12GraphicsCommandList::Close の呼び出しが失敗した場合、コマンド リストをリセットすることはできません。 Reset を呼び出すと、ID3D12GraphicsCommandList::Close が返されたのと同じエラーが返されます。
 
リセットが成功すると、コマンド リストは "記録" 状態のままになります。 デバイス の作成時に指定された同時記録コマンド リストの上限を超えると、リセットは失敗します。

アプリでは、コマンド リスト アロケーターを指定する必要があります。 ランタイムにより、アロケーターが同時に複数の記録コマンド リストに関連付けられることはありません。

まだ送信されていないコマンド リストによって参照されているバンドルのリセットは失敗します。

デバッグ レイヤー

また、デバッグ レイヤーはグラフィックス処理装置 (GPU) の進行状況を追跡し、コマンド リストの未処理の実行がないことを証明できない場合はエラーを発行します。

例

D3D12HelloTriangle サンプルでは、次のように ID3D12GraphicsCommandList::Reset を使用します。

D3D12_VIEWPORT m_viewport;
D3D12_RECT m_scissorRect;
ComPtr<IDXGISwapChain3> m_swapChain;
ComPtr<ID3D12Device> m_device;
ComPtr<ID3D12Resource> m_renderTargets[FrameCount];
ComPtr<ID3D12CommandAllocator> m_commandAllocator;
ComPtr<ID3D12CommandQueue> m_commandQueue;
ComPtr<ID3D12RootSignature> m_rootSignature;
ComPtr<ID3D12DescriptorHeap> m_rtvHeap;
ComPtr<ID3D12PipelineState> m_pipelineState;
ComPtr<ID3D12GraphicsCommandList> m_commandList;
UINT m_rtvDescriptorSize;


void D3D12HelloTriangle::PopulateCommandList()
{
    // 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_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_commandAllocator.Get(), m_pipelineState.Get()));

    // Set necessary state.
    m_commandList->SetGraphicsRootSignature(m_rootSignature.Get());
    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);
    m_commandList->OMSetRenderTargets(1, &rtvHandle, FALSE, nullptr);

    // Record commands.
    const float clearColor[] = { 0.0f, 0.2f, 0.4f, 1.0f };
    m_commandList->ClearRenderTargetView(rtvHandle, clearColor, 0, nullptr);
    m_commandList->IASetPrimitiveTopology(D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST);
    m_commandList->IASetVertexBuffers(0, 1, &m_vertexBufferView);
    m_commandList->DrawInstanced(3, 1, 0, 0);

    // 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());
}

「D3D12 リファレンス」のコード例を参照してください。

要件

要件 値
対象プラットフォーム Windows
ヘッダー d3d12.h
Library D3d12.lib
[DLL] D3d12.dll

こちらもご覧ください

ID3D12CommandAllocator::Reset

ID3D12Device::CreateCommandList

ID3D12GraphicsCommandList