ID3D12CommandQueue::UpdateTileMappings method (d3d12.h)

Artikel
08/23/2023

Updates pemetaan lokasi petak peta dalam sumber daya yang dipesan ke lokasi memori dalam timbunan sumber daya.

Sintaks

void UpdateTileMappings(
  [in]           ID3D12Resource                        *pResource,
                 UINT                                  NumResourceRegions,
  [in, optional] const D3D12_TILED_RESOURCE_COORDINATE *pResourceRegionStartCoordinates,
  [in, optional] const D3D12_TILE_REGION_SIZE          *pResourceRegionSizes,
  [in, optional] ID3D12Heap                            *pHeap,
                 UINT                                  NumRanges,
  [in, optional] const D3D12_TILE_RANGE_FLAGS          *pRangeFlags,
  [in, optional] const UINT                            *pHeapRangeStartOffsets,
  [in, optional] const UINT                            *pRangeTileCounts,
                 D3D12_TILE_MAPPING_FLAGS              Flags
);

Parameter

[in] pResource

Penunjuk ke sumber daya yang dipesan.

NumResourceRegions

Jumlah wilayah sumber daya yang dipesan.

[in, optional] pResourceRegionStartCoordinates

Array struktur D3D12_TILED_RESOURCE_COORDINATE yang menjelaskan koordinat awal wilayah sumber daya yang dipesan. Parameter NumResourceRegions menentukan jumlah struktur D3D12_TILED_RESOURCE_COORDINATE dalam array.

[in, optional] pResourceRegionSizes

Array struktur D3D12_TILE_REGION_SIZE yang menjelaskan ukuran wilayah sumber daya yang dipesan. Parameter NumResourceRegions menentukan jumlah struktur D3D12_TILE_REGION_SIZE dalam array.

[in, optional] pHeap

Penunjuk ke timbunan sumber daya.

NumRanges

Jumlah rentang petak peta.

[in, optional] pRangeFlags

Penunjuk ke array nilai D3D12_TILE_RANGE_FLAGS yang menjelaskan setiap rentang petak peta. Parameter NumRanges menentukan jumlah nilai dalam array.

[in, optional] pHeapRangeStartOffsets

Array offset ke dalam tumpukan sumber daya. Ini adalah offset petak peta berbasis 0, dihitung dalam petak peta (bukan byte).

[in, optional] pRangeTileCounts

Array petak peta. Array nilai yang menentukan jumlah petak peta di setiap rentang petak peta. Parameter NumRanges menentukan jumlah nilai dalam array.

Flags

Kombinasi nilai D3D12_TILE_MAPPING_FLAGS yang digabungkan dengan menggunakan operasi OR bitwise.

Nilai kembali

Tidak ada

Keterangan

Gunakan UpdateTileMappings untuk memetakan halaman virtual sumber daya yang dipesan ke halaman fisik timbunan. Pemetaan tidak harus berurutan. Operasi ini mirip dengan ID3D11DeviceContext2::UpdateTileMappings dengan satu perbedaan utama bahwa D3D12 memungkinkan sumber daya yang dipesan memiliki petak dari beberapa timbunan.

Dalam satu panggilan ke UpdateTileMappings, Anda dapat memetakan satu atau beberapa rentang petak peta sumber daya ke satu atau beberapa rentang ubin tumpukan.

Anda dapat mengatur parameter UpdateTileMappings dengan cara berikut untuk melakukan pembaruan:

Sumber daya cadangan yang pemetaannya diperbarui. Pemetaan memulai semua NULL saat sumber daya awalnya dibuat.
Kumpulan wilayah petak peta pada sumber daya yang dipesan yang pemetaannya diperbarui. Anda dapat melakukan satu panggilan UpdateTileMappings untuk memperbarui banyak pemetaan atau beberapa panggilan dengan sedikit lebih banyak overhead panggilan API juga jika itu lebih nyaman.
- NumResourceRegions menentukan berapa banyak wilayah yang ada.
- pResourceRegionStartCoordinates dan pResourceRegionSizes adalah setiap array yang mengidentifikasi lokasi awal dan memperluas setiap wilayah. Jika NumResourceRegions adalah 1, untuk kenyamanan salah satu atau kedua array yang menjelaskan wilayah dapat berupa NULL. NULL untuk pResourceRegionStartCoordinates berarti koordinat mulai adalah semua 0 detik, dan NULL untuk pResourceRegionSizes mengidentifikasi wilayah default yang merupakan sekumpulan petak peta lengkap untuk seluruh sumber daya yang dipesan, termasuk semua mipmap, irisan array, atau keduanya.
- Jika pResourceRegionStartCoordinates bukan NULL dan pResourceRegionSizes adalah NULL, ukuran wilayah default ke 1 petak peta untuk semua wilayah. Ini memudahkan untuk menentukan pemetaan untuk satu set petak masing-masing di lokasi yang berbeda dengan menyediakan array lokasi di pResourceRegionStartCoordinates tanpa harus mengirim array pResourceRegionSizes semuanya diatur ke 1.
Pembaruan diterapkan dari wilayah pertama hingga terakhir; jadi, jika wilayah tumpang tindih dalam satu panggilan, pembaruan nanti dalam daftar menimpa area yang tumpang tindih dengan pembaruan sebelumnya.
Tumpukan yang menyediakan memori di mana pemetaan petak peta dapat pergi. Jika UpdateTileMappings hanya menentukan pemetaan NULL, Anda tidak perlu menentukan heap.
Kumpulan rentang petak peta tempat pemetaan akan dilakukan. Setiap rentang petak peta yang diberikan dapat menentukan salah satu dari beberapa jenis rentang: rentang petak peta dalam timbunan (default), jumlah petak peta dalam sumber daya yang dipesan untuk dipetakan ke satu petak peta dalam tumpukan (berbagi petak peta), hitungan pemetaan petak peta dalam sumber daya yang dipesan untuk dilewati dan dilewati apa adanya, atau hitungan petak peta dalam tumpukan untuk dipetakan ke NULL. NumRanges menentukan jumlah rentang petak peta, di mana total petak peta yang diidentifikasi di semua rentang harus cocok dengan jumlah total petak peta di wilayah petak peta dari sumber daya yang dipesan yang dijelaskan sebelumnya. Pemetaan didefinisikan dengan melakukan iterasi melalui petak peta di wilayah petak peta dalam urutan berurutan - x kemudian y kemudian urutan z untuk wilayah kotak - sambil berjalan melalui serangkaian rentang petak peta dalam urutan berurutan. Perincian wilayah petak peta tidak harus berbaris dengan perincian rentang petak peta, tetapi jumlah total petak peta di kedua sisi harus sama sehingga setiap petak sumber daya cadangan yang ditentukan memiliki pemetaan yang ditentukan.
pRangeFlags, pHeapRangeStartOffsets, dan pRangeTileCounts adalah semua array, dari ukuran NumRanges, yang menjelaskan rentang petak peta. Jika pRangeFlags NULL, semua rentang adalah petak peta berurutan dalam tumpukan; jika tidak, untuk setiap rentang i,pRangeFlags[i] mengidentifikasi cara kerja pemetaan dalam rentang ubin tersebut:
- Jika pRangeFlags[i]D3D12_TILE_RANGE_FLAG_NONE, rentang tersebut menentukan petak peta berurutan dalam tumpukan, dengan jumlah petak peta menjadi pRangeTileCounts[i] dan lokasi awal pHeapRangeStartOffsets[i]. Jika NumRanges adalah 1, pRangeTileCounts dapat berupa NULL dan default ke jumlah total petak peta yang ditentukan oleh semua wilayah petak peta.
- Jika pRangeFlags[i]D3D12_TILE_RANGE_FLAG_REUSE_SINGLE_TILE, pHeapRangeStartOffsets[i] mengidentifikasi petak peta tunggal dalam tumpukan untuk dipetakan, dan pRangeTileCounts[i] menentukan berapa banyak petak peta dari wilayah petak peta untuk dipetakan ke lokasi timbunan tersebut. Jika NumRanges adalah 1, pRangeTileCounts dapat berupa NULL dan default ke jumlah total petak peta yang ditentukan oleh semua wilayah petak peta.
- Jika pRangeFlags[i]D3D12_TILE_RANGE_FLAG_NULL, pRangeTileCounts[i] menentukan berapa banyak petak peta dari wilayah petak peta yang akan dipetakan ke NULL. Jika NumRanges adalah 1, pRangeTileCounts dapat berupa NULL dan default ke jumlah total petak peta yang ditentukan oleh semua wilayah petak peta. pHeapRangeStartOffsets[i] diabaikan untuk pemetaan NULL.
- Jika pRangeFlags[i]D3D12_TILE_RANGE_FLAG_SKIP, pRangeTileCounts[i] menentukan berapa banyak petak peta dari wilayah petak peta yang akan dilewati dan membiarkan pemetaan yang ada tidak berubah. Ini dapat berguna jika wilayah petak peta dengan mudah mengikat area pemetaan petak peta untuk diperbarui kecuali dengan beberapa pengecualian yang perlu dibiarkan sama seperti apa pun yang dipetakan sebelumnya. pHeapRangeStartOffsets[i] diabaikan untuk pemetaan SKIP.

Sumber daya yang dipesan harus mengikuti aturan yang sama untuk alias petak peta, inisialisasi, dan pewarisan data sebagai sumber daya yang ditempatkan. Lihat CreatePlacedResource untuk detail selengkapnya.

Berikut adalah beberapa contoh kasus UpdateTileMappings umum:

Contoh

Contoh mereferensikan struktur dan enum berikut:

Menghapus seluruh pemetaan permukaan ke NULL

// - NULL for pResourceRegionStartCoordinates and pResourceRegionSizes defaults to the entire resource
// - NULL for pHeapRangeStartOffsets since it isn't needed for mapping tiles to NULL
// - NULL for pRangeTileCounts when NumRanges is 1 defaults to the same number of tiles as the resource region (which is
//   the entire surface in this case)
//
UINT RangeFlags = D3D12_TILE_RANGE_FLAG_NULL;
pCommandQueue->UpdateTileMappings(pResource, 1, NULL, NULL, NULL, 1, &RangeFlags, NULL, NULL, D3D12_TILE_MAPPING_FLAG_NONE);

Memetakan wilayah petak peta ke satu petak peta:

// - This maps a 2x3 tile region at tile offset (1,1) in a resource to tile [12] in a heap
// 
D3D12_TILED_RESOURCE_COORDINATE TRC;
TRC.X = 1;
TRC.Y = 1;
TRC.Z = 0;
TRC.Subresource = 0;

D3D12_TILE_REGION_SIZE TRS;
TRS.bUseBox = TRUE;
TRS.Width = 2;
TRS.Height = 3; 
TRS.Depth = 1;
TRS.NumTiles = TRS.Width * TRS.Height * TRS.Depth;

UINT RangeFlags = D3D12_TILE_RANGE_FLAG_REUSE_SINGLE_TILE;
UINT StartOffset = 12;

pCommandQueue->UpdateTileMappings(pResource,1,&TRC,&TRS,pHeap,1,&RangeFlags,&StartOffset,NULL,D3D12_TILE_MAPPING_FLAG_NONE);

Menentukan pemetaan untuk sekumpulan petak peta individual yang terpisah:

// - This can also be accomplished in multiple calls. 
//   A single call to define multiple mapping updates can reduce CPU call overhead slightly,
//   at the cost of having to pass arrays as parameters.
// - Passing NULL for pResourceRegionSizes defaults to each region in the resource
//   being a single tile.  So all that is needed are the coordinates of each one.
// - Passing NULL for pRangeFlags defaults to no flags (since none are needed in this case)
// - Passing NULL for pRangeTileCounts defaults to each range in the heap being size 1.
//   So all that is needed are the start offsets for each tile in the heap
//
D3D12_TILED_RESOURCE_COORDINATE TRC[3];
UINT StartOffsets[3];
UINT NumSingleTiles = 3;
TRC[0].X = 1;
TRC[0].Y = 1; 
TRC[0].Subresource = 0;

StartOffsets[0] = 1;
TRC[1].X = 4;
TRC[1].Y = 7; 
TRC[1].Subresource = 0;
StartOffsets[1] = 4;

TRC[2].X = 2;
TRC[2].Y = 3; 
TRC[2].Subresource = 0;
StartOffsets[2] = 7;

pCommandQueue->UpdateTileMappings(pResource,NumSingleTiles,&TRC,NULL,pHeap,NumSingleTiles,NULL,StartOffsets,
NULL,D3D12_TILE_MAPPING_FLAG_NONE);

Contoh kompleks - menentukan pemetaan untuk wilayah dengan beberapa lompatan, beberapa pemetaan NULL.

// - This complex example hard codes the parameter arrays, whereas in practice the 
//   application would likely configure the parameters programatically or in a data driven way.
// - Suppose we have 3 regions in a resource to configure mappings for, 2x3 at coordinate (1,1),
//   3x3 at coordinate (4,7), and 7x1 at coordinate (20,30)
// - The tiles in the regions are walked from first to last, in X then Y then Z order,
//   while stepping forward through the specified Tile Ranges to determine each mapping.
//   In this example, 22 tile mappings need to be defined.
// - Suppose we want the first 3 tiles to be mapped to a contiguous range in the heap starting at
//   heap location [9], the next 8 to be skipped (left unchanged), the next 2 to map to NULL, 
//   the next 5 to share a single tile (heap location [17]) and the remaining 
//   4 tiles to each map to to unique heap locations, [2], [9], [4] and [17]:
//
D3D12_TILED_RESOURCE_COORDINATE TRC[3];
D3D12_TILE_REGION_SIZE TRS[3];
UINT NumRegions = 3;

TRC[0].X = 1;
TRC[0].Y = 1; 
TRC[0].Subresource = 0;
TRS[0].bUseBox = TRUE;
TRS[0].Width = 2;
TRS[0].Height = 3; 
TRS[0].NumTiles = TRS[0].Width * TRS[0].Height;

TRC[1].X = 4;
TRC[1].Y = 7; 
TRC[1].Subresource = 0;
TRS[1].bUseBox = TRUE;
TRS[1].Width = 3;
TRS[1].Height = 3; 
TRS[1].NumTiles = TRS[1].Width * TRS[1].Height;

TRC[2].X = 20;
TRC[2].Y = 30; 
TRC[2].Subresource = 0;
TRS[2].bUseBox = TRUE;
TRS[2].Width = 7;
TRS[2].Height = 1; 
TRS[2].NumTiles = TRS[2].Width * TRS[2].Height;

UINT NumRanges = 8;
UINT RangeFlags[8];
UINT HeapRangeStartOffsets[8];
UINT RangeTileCounts[8];

RangeFlags[0] = 0;
HeapRangeStartOffsets[0] = 9;
RangeTileCounts[0] = 3;

RangeFlags[1] = D3D12_TILE_RANGE_FLAG_SKIP;
HeapRangeStartOffsets[1] = 0; // offset is ignored for skip mappings
RangeTileCounts[1] = 8;

RangeFlags[2] = D3D12_TILE_RANGE_FLAG_NULL;
HeapRangeStartOffsets[2] = 0; // offset is ignored for NULL mappings
RangeTileCounts[2] = 2;

RangeFlags[3] = D3D12_TILE_RANGE_FLAG_REUSE_SINGLE_TILE;
HeapRangeStartOffsets[3] = 17; 
RangeTileCounts[3] = 5;

RangeFlags[4] = 0;
HeapRangeStartOffsets[4] = 2; 
RangeTileCounts[4] = 1;

RangeFlags[5] = 0;
HeapRangeStartOffsets[5] = 9; 
RangeTileCounts[5] = 1;

RangeFlags[6] = 0;
HeapRangeStartOffsets[6] = 4; 
RangeTileCounts[6] = 1;

RangeFlags[7] = 0;
HeapRangeStartOffsets[7] = 17; 
RangeTileCounts[7] = 1;

pCommandQueue->UpdateTileMappings(pResource,NumRegions,TRC,TRS,pHeap,NumRanges,RangeFlags,
HeapRangeStartOffsets,RangeTileCounts,D3D12_TILE_MAPPING_FLAG_NONE);

Persyaratan


Target Platform	Windows
Header	d3d12.h

Lihat juga

CopyTileMappings

ID3D12CommandQueue

Sumber Daya Berjenjang Volume

Bagikan melalui