ID3D12GraphicsCommandList::Metode reset (d3d12.h)

Artikel
08/23/2023

Mereset daftar perintah kembali ke status awal seolah-olah daftar perintah baru baru saja dibuat.

Sintaks

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

Parameter

[in] pAllocator

Jenis: ID3D12CommandAllocator*

Penunjuk ke objek ID3D12CommandAllocator tempat perangkat membuat daftar perintah.

[in, optional] pInitialState

Jenis: ID3D12PipelineState*

Penunjuk ke objek ID3D12PipelineState yang berisi status alur awal untuk daftar perintah. Ini bersifat opsional dan dapat berupa NULL. Jika NULL, runtime mengatur status alur awal dummy sehingga driver tidak perlu berurusan dengan status yang tidak terdefinisi. Overhead untuk ini rendah, terutama untuk daftar perintah, yang biaya keseluruhan merekam daftar perintah kemungkinan mengerdilkan biaya satu pengaturan status awal. Jadi ada sedikit biaya dalam tidak mengatur parameter status alur awal jika tidak nyaman.

Untuk bundel di sisi lain, mungkin lebih masuk akal untuk mencoba mengatur parameter status awal karena bundel kemungkinan lebih kecil secara keseluruhan dan dapat sering digunakan kembali.

Mengembalikan nilai

Jenis: HRESULT

Mengembalikan S_OK jika berhasil; jika tidak, mengembalikan salah satu nilai berikut:

E_FAIL jika daftar perintah tidak dalam status "tertutup" saat panggilan Reset dilakukan, atau batas per perangkat akan terlampaui.
E_OUTOFMEMORY jika sistem operasi kehabisan memori.
E_INVALIDARG jika alokator saat ini sedang digunakan dengan daftar perintah lain dalam status "perekaman" atau jika alokator yang ditentukan dibuat dengan jenis yang salah.

Lihat Kode Pengembalian Direct3D 12 untuk kemungkinan nilai pengembalian lainnya.

Keterangan

Dengan menggunakan Reset, Anda dapat menggunakan kembali struktur pelacakan daftar perintah tanpa alokasi apa pun. Tidak seperti ID3D12CommandAllocator::Reset, Anda dapat memanggil Reset saat daftar perintah masih dijalankan. Pola umumnya adalah mengirimkan daftar perintah dan kemudian segera mengatur ulang untuk menggunakan kembali memori yang dialokasikan untuk daftar perintah lain.

Anda dapat menggunakan Reset untuk daftar perintah langsung dan bundel.

Alokator perintah yang Reset ambil sebagai input dapat dikaitkan dengan tidak lebih dari satu daftar perintah perekaman sekaligus. Jenis alokator, daftar perintah langsung atau bundel, harus cocok dengan jenis daftar perintah yang sedang dibuat.

Jika bundel tidak menentukan tumpukan sumber daya, bundel tidak dapat membuat perubahan pada tabel deskriptor mana yang terikat. Bagaimanapun, bundel tidak dapat mengubah tumpukan sumber daya dalam bundel. Jika heap ditentukan untuk bundel, heap harus cocok dengan timbunan daftar perintah 'induk' panggilan.

Validasi runtime

Sebelum aplikasi memanggil Reset, daftar perintah harus dalam status "tertutup". Reset akan gagal jika daftar perintah tidak dalam status "tertutup".

Catatan Jika panggilan ke ID3D12GraphicsCommandList::Close gagal, daftar perintah tidak pernah dapat diatur ulang. Reset Panggilan akan mengakibatkan kesalahan yang sama dikembalikan bahwa ID3D12GraphicsCommandList::Close dikembalikan.

Setelah Reset berhasil, daftar perintah dibiarkan dalam status "perekaman". Reset akan gagal jika akan menyebabkan batas daftar perintah perekaman secara bersamaan maksimum, yang ditentukan pada pembuatan perangkat, terlampaui.

Aplikasi harus menentukan alokator daftar perintah. Runtime akan memastikan bahwa alokator tidak pernah dikaitkan dengan lebih dari satu daftar perintah perekaman secara bersamaan.

Reset gagal untuk bundel yang direferensikan oleh daftar perintah yang belum dikirimkan.

Lapisan debug

Lapisan debug juga akan melacak kemajuan unit pemrosesan grafis (GPU) dan mengeluarkan kesalahan jika tidak dapat membuktikan bahwa tidak ada eksekusi luar biasa dari daftar perintah.

Contoh

Sampel D3D12HelloTriangle menggunakan ID3D12GraphicsCommandList::Reset sebagai berikut:

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

Lihat Contoh Kode di Referensi D3D12.