Метод ID3D12GraphicsCommandList::Reset (d3d12.h)

Статья
02/29/2024

Сбрасывает список команд в исходное состояние, как если бы новый список команд был только что создан.

Синтаксис

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

Параметры

[in] pAllocator

Тип: ID3D12CommandAllocator*

Указатель на объект ID3D12CommandAllocator , из которой устройство создает списки команд.

[in, optional] pInitialState

Тип: ID3D12PipelineState*

Указатель на объект ID3D12PipelineState , содержащий начальное состояние конвейера для списка команд. Этот параметр является необязательным и может иметь значение NULL. Если значение РАВНО NULL, среда выполнения устанавливает фиктивное начальное состояние конвейера, чтобы драйверы не имели дело с неопределенным состоянием. Затраты на это низкие, особенно для списка команд, для которых общая стоимость записи списка команд, скорее всего, затмевает стоимость одного параметра начального состояния. Поэтому за то, чтобы не задать параметр начального состояния конвейера, если это не удобно, затраты на небольшие затраты.

Для пакетов, с другой стороны, имеет смысл попытаться задать параметр начального состояния, так как пакеты, скорее всего, меньше в целом и могут часто использоваться повторно.

Возвращаемое значение

Тип: HRESULT

Возвращает S_OK в случае успешного выполнения; в противном случае возвращает одно из следующих значений:

E_FAIL , если список команд не находился в состоянии "закрыто" при вызове сброса или превышено ограничение на количество устройств.
E_OUTOFMEMORY , если в операционной системе не хватает памяти.
E_INVALIDARG , используется ли в настоящее время распределитель с другим списком команд в состоянии записи или если указанный распределитель был создан с неправильным типом.

Другие возможные возвращаемые значения см. в разделе Коды возврата Direct3D 12 .

С помощью сброса можно повторно использовать структуры отслеживания списков команд без выделения ресурсов. В отличие от ID3D12CommandAllocator::Reset, можно вызвать reset , пока список команд еще выполняется. Типичным шаблоном является отправка списка команд, а затем его немедленное сброс, чтобы повторно использовать выделенную память для другого списка команд.

Сброс можно использовать как для списков прямых команд, так и для пакетов.

Распределитель команд, который reset принимает в качестве входных данных, может быть связан не более чем с одним списком команд записи за раз. Тип распределителя( прямой список команд или пакет) должен соответствовать типу создаваемого списка команд.

Если в пакете не указана куча ресурсов, он не может вносить изменения в таблицы дескриптора. В любом случае пакеты не могут изменить кучу ресурсов в пакете. Если куча указана для пакета, она должна соответствовать куче вызывающего списка команд "parent".

Проверка среды выполнения

Прежде чем приложение вызовет Reset, список команд должен находиться в состоянии "закрыто". Сброс завершится ошибкой, если список команд не в состоянии "закрыто".

Примечание Если вызов ID3D12GraphicsCommandList::Close завершается сбоем, список команд нельзя сбросить. Вызов сброса приведет к возврату той же ошибки, что и 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.