ID3D12Device::CreateCommittedResource-Methode (d3d12.h)

Artikel
07/16/2024

Erstellt sowohl eine Ressource als auch einen impliziten Heap, sodass der Heap groß genug ist, um die gesamte Ressource zu enthalten, und die Ressource wird dem Heap zugeordnet.

Syntax

HRESULT CreateCommittedResource(
  [in]            const D3D12_HEAP_PROPERTIES *pHeapProperties,
  [in]            D3D12_HEAP_FLAGS            HeapFlags,
  [in]            const D3D12_RESOURCE_DESC   *pDesc,
  [in]            D3D12_RESOURCE_STATES       InitialResourceState,
  [in, optional]  const D3D12_CLEAR_VALUE     *pOptimizedClearValue,
  [in]            REFIID                      riidResource,
  [out, optional] void                        **ppvResource
);

Parameter

[in] pHeapProperties

Typ: const D3D12_HEAP_PROPERTIES*

Ein Zeiger auf eine D3D12_HEAP_PROPERTIES Struktur, die Eigenschaften für den Heap der Ressource bereitstellt.

[in] HeapFlags

Typ: D3D12_HEAP_FLAGS

Heapoptionen als bitweise OR'd-Kombination aus D3D12_HEAP_FLAGS Enumerationskonstanten.

[in] pDesc

Typ: const D3D12_RESOURCE_DESC*

Ein Zeiger auf eine D3D12_RESOURCE_DESC Struktur, die die Ressource beschreibt.

[in] InitialResourceState

Typ: D3D12_RESOURCE_STATES

Der Anfangszustand der Ressource als bitweise OR'd-Kombination aus D3D12_RESOURCE_STATES Enumerationskonstanten.

Wenn Sie eine Ressource zusammen mit einem D3D12_HEAP_TYPE_UPLOAD Heap erstellen, müssen Sie InitialResourceState- auf D3D12_RESOURCE_STATE_GENERIC_READfestlegen.

Wenn Sie eine Ressource zusammen mit einem D3D12_HEAP_TYPE_READBACK Heap erstellen, müssen Sie InitialResourceState- auf D3D12_RESOURCE_STATE_COPY_DESTfestlegen.

[in, optional] pOptimizedClearValue

Typ: D3D12_CLEAR_VALUE*

Gibt eine D3D12_CLEAR_VALUE Struktur an, die den Standardwert für eine klare Farbe beschreibt.

pOptimizedClearValue gibt einen Wert an, für den klare Vorgänge am besten geeignet sind. Wenn die erstellte Ressource eine Textur mit dem D3D12_RESOURCE_FLAG_ALLOW_RENDER_TARGET oder D3D12_RESOURCE_FLAG_ALLOW_DEPTH_STENCIL Flags ist, sollten Sie den Wert auswählen, mit dem der clear-Vorgang am häufigsten aufgerufen wird. Sie können den eindeutigen Vorgang mit anderen Werten aufrufen, diese Vorgänge sind jedoch nicht so effizient, wie wenn der Wert dem wert entspricht, der an die Ressourcenerstellung übergeben wird.

Wenn Sie D3D12_RESOURCE_DIMENSION_BUFFERverwenden, müssen Sie pOptimizedClearValue- auf nullptrfestlegen.

[in] riidResource

Typ: REFIID-

Ein Verweis auf den global eindeutigen Bezeichner (GUID) der Ressourcenschnittstelle, die in ppvResource-zurückgegeben werden soll.

Während riidResource- am häufigsten die GUID-ID3D12Resource-ist, kann es sich um die GUID- jeder Schnittstelle handelt. Wenn das Ressourcenobjekt die Schnittstelle für diese GUID-nicht unterstützt, schlägt die Erstellung mit E_NOINTERFACEfehl.

[out, optional] ppvResource

Typ: void**

Ein optionaler Zeiger auf einen Speicherblock, der den angeforderten Schnittstellenzeiger auf das erstellte Ressourcenobjekt empfängt.

ppvResource- kann nullptrwerden, um Funktionstests zu ermöglichen. Wenn ppvResource-nullptrist, wird kein Objekt erstellt, und S_FALSE wird zurückgegeben, wenn pDesc- gültig ist.

Rückgabewert

Typ: HRESULT-

Wenn die Funktion erfolgreich ist, wird S_OKzurückgegeben. Andernfalls wird ein HRESULT-Fehlercodezurückgegeben.

Rückgabewert	Beschreibung
E_OUTOFMEMORY	Es ist nicht genügend Arbeitsspeicher vorhanden, um die Ressource zu erstellen.

Weitere mögliche Rückgabewerte finden Sie unter Direct3D 12-Rückgabecodes.

Bemerkungen

Diese Methode erstellt sowohl eine Ressource als auch einen Heap, sodass der Heap groß genug ist, um die gesamte Ressource zu enthalten, und die Ressource wird dem Heap zugeordnet. Der erstellte Heap wird als impliziter Heap bezeichnet, da das Heap-Objekt nicht von der Anwendung abgerufen werden kann. Bevor Sie den endgültigen Verweis auf die Ressource freigeben, muss Ihre Anwendung sicherstellen, dass die GPU diese Ressource nicht mehr lesen oder schreiben wird.

Der implizite Heap wird für den GPU-Zugriff resident, bevor die Methode die Steuerung an Ihre Anwendung zurückgibt. Siehe auch Residency.

Die GPU-VA-Zuordnung der Ressource kann nicht geändert werden. Siehe ID3D12CommandQueue::UpdateTileMappings und volume tiled resources.

Diese Methode kann von mehreren Threads gleichzeitig aufgerufen werden.

Beispiele

Im beispiel D3D12Bundles wird ID3D12Device::CreateCommittedResource wie folgt verwendet:

Erstellen Sie einen Vertexpuffer.

auto heapProperties = CD3DX12_HEAP_PROPERTIES(D3D12_HEAP_TYPE_DEFAULT);
auto resourceDesc = CD3DX12_RESOURCE_DESC::Buffer(SampleAssets::VertexDataSize);
ThrowIfFailed(m_device->CreateCommittedResource(
    &heapProperties,
    D3D12_HEAP_FLAG_NONE,
    &resourceDesc,
    D3D12_RESOURCE_STATE_COPY_DEST,
    nullptr,
    IID_PPV_ARGS(&m_vertexBuffer)));

Siehe Beispielcode in der Direct3D 12-Referenz.