> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XALLOC_ATTRIBUTES

> XALLOC_ATTRIBUTES

# XALLOC\_ATTRIBUTES

包含描述記憶體配置屬性的值。

<a id="syntaxSection" />

## 語法

```cpp theme={null}
typedef union _XALLOC_ATTRIBUTES {  
    ULONGLONG Attributes;  
    struct {  
        ULONGLONG ObjectType : 14;  
        ULONGLONG PageSize : 2;  
        ULONGLONG AllocatorId : 8;  
        ULONGLONG Alignment : 5;  
        ULONGLONG MemoryType : 4;  
        ULONGLONG Address32BitMapping : 1;  
        ULONGLONG reserved : 30;  
    } s;  
} XALLOC_ATTRIBUTES, *PXALLOC_ATTRIBUTES;  
```

<a id="membersSection" />

### 成員

*Attributes*\
類型：ULONGLONG

記憶體配置的屬性。

*ObjectType*\
類型：ULONGLONG

配置類型，由執行記憶體配置的子系統定義。如需詳細資訊，請參閱 [ObjectType](#objecttypeSection)。

*PageSize*\
類型：ULONGLONG

配置的分頁大小。如需允許值的詳細資訊，請參閱 [PageSize](#pagesizeSection)。

*AllocatorId*\
類型：ULONGLONG

執行配置之子系統的配置器識別碼。每項配置都與一個配置器識別碼相關聯，用來識別要求配置 (或釋放) 記憶體的子系統。配置有三個可能的來源：遊戲、平台和中介軟體元件。如需配置器識別碼的詳細資訊，請參閱 [XALLOC\_ALLOCATOR\_IDS](/zh-TW/reference/system/xmem/enums/xalloc_allocator_ids)。

*Alignment*\
類型：ULONGLONG

配置所需的對齊類型。如需允許值的詳細資訊，請參閱 [Alignment](#alignmentSection)。

*MemoryType*\
類型：ULONGLONG

配置所需的記憶體類型。您可以從數種 GPU 可見的分頁類型和快取行為中選擇其一，或選擇適用於僅限 CPU 記憶體配置的值。如需允許值的詳細資訊，請參閱 [MemoryType](#memorytypeSection)。

*Address32BitMapping*\
類型：ULONGLONG

如果設定為 1，會強制配置取得低於 4GB 的位址 (例如 GPU 所需)。

*reserved*\
類型：ULONGLONG

保留供內部使用。

<a id="remarksSection" />

## 備註

[XMEMALLOC\_ROUTINE](/zh-TW/reference/system/xmem/functions/xmemalloc_routine) 和 [XMEMFREE\_ROUTINE](/zh-TW/reference/system/xmem/functions/xmemfree_routine) 語法定義會分別使用此結構來進行記憶體配置和解除配置。

<Note>
  [XMemAlloc](/zh-TW/reference/system/xmem/functions/xmemalloc) 和 [XMemFree](/zh-TW/reference/system/xmem/functions/xmemfree) 預設實作的原始程式碼會隨 Microsoft Game Development Kit (GDK) 一併安裝。如需詳細資訊，請參閱 `\GXDK\gameKit\Source\amd64\heap.c` 中的 `XMemAllocDefault` 和 `XMemFreeDefault` 函式。
</Note>

下列各節提供允許值和配置詳細資料的詳細資訊。

<a id="objecttypeSection" />

### ObjectType

*ObjectType* 的值由執行配置的配置器定義，您的遊戲可以使用這些值在配置時追蹤不同的物件類型，或依類型改變配置器的行為。

例如，如果您為粒子系統定義了配置器，您可能會為遊戲定義自己的配置器識別碼 `TitleAllocatorID_ParticleSystem` 並將其設定為 4，同時定義一個集區來容納在引擎中只會與地平面碰撞的粒子。此集區的 *ObjectType* 識別碼可能是 2，因為您已經將 0 用於發射器，並將 1 用於會碰撞的粒子。這完全取決於您想要追蹤的確切內容，以及引擎的結構方式。

或者，您也可以不定義如此粗略細微度的識別碼；您可以改為依據配置器識別碼來區分不同的配置行為，並將 *ObjectType* 識別碼純粹用於追蹤用途，讓遊戲中的每個物件類型都有自己的值，而不論子系統為何。

*ObjectType* 的值必須是介於 0 到 16383 之間的整數。

<a id="memorytypeSection" />

### MemoryType

您可以透過設定 *MemoryType* 的值來指定要配置的記憶體類型。*MemoryType* 參數必須設定為下列其中一個值。

| XALLOC\_MEMTYPE | 值 | 描述 |
| :- | :-: | :- |
| XALLOC\_MEMTYPE\_HEAP\_CACHEABLE | 0x0 | 表示記憶體區塊不需要對 GPU 可見，且應該快取。 |
| XALLOC\_MEMTYPE\_GRAPHICS\_WRITECOMBINE | 0x1 | 表示記憶體區塊對應在 GPU 分頁表中，且應作為寫入合併記憶體。 |
| XALLOC\_MEMTYPE\_GRAPHICS\_WRITECOMBINE\_GPU\_READONLY | 0x2 | 表示記憶體區塊為唯讀、對應在 GPU 分頁表中，且應作為寫入合併記憶體。此記憶體不具 GPU 快取一致性。 |
| XALLOC\_MEMTYPE\_GRAPHICS\_CACHEABLE | 0x3 | 表示記憶體區塊對應在 GPU 分頁表中，且應該快取並具 GPU 快取一致性。 |
| XALLOC\_MEMTYPE\_GRAPHICS\_CACHEABLE\_NONCOHERENT\_GPU\_READONLY | 0x4 | 表示記憶體區塊對應在 GPU 分頁表中，雖然有 CPU 快取，但此記憶體不具 GPU 快取一致性。使用此記憶體類型時必須格外小心，以避免在 CPU 或 GPU 上看到過時的快取行。 |
| XALLOC\_MEMTYPE\_GRAPHICS\_COMMAND\_BUFFER\_WRITECOMBINE | 0x5 | 表示記憶體區塊預定用作 GPU 或 DMA 引擎命令緩衝區，且應為寫入合併。此記憶體不具 GPU 快取一致性。 |
| XALLOC\_MEMTYPE\_GRAPHICS\_COMMAND\_BUFFER\_CACHEABLE | 0x6 | 表示記憶體區塊預定用作 GPU 或 DMA 引擎命令緩衝區，且應該快取並具 GPU 快取一致性。 |
| XALLOC\_MEMTYPE\_PHYSICAL\_CACHEABLE | 0x7 | 表示記憶體區塊為實體且可快取。 |
| XALLOC\_MEMTYPE\_PHYSICAL\_WRITECOMBINE | 0x8 | 表示記憶體區塊為實體，且應作為寫入合併記憶體。 |
| XALLOC\_MEMTYPE\_PHYSICAL\_UNCACHED | 0x9 | 表示記憶體區塊為實體且未快取。 |
| XALLOC\_MEMTYPE\_GRAPHICS\_GPU\_UNCACHED | 0xA | 表示記憶體區塊對應在 GPU 分頁表中。GPU 存取此記憶體時不會快取。 |
| XALLOC\_MEMTYPE\_GRAPHICS\_SHADER\_CACHEABLE\_NONCOHERENT | 0xB | 表示記憶體區塊對應在 GPU 分頁表中以供著色器執行 (唯讀)。此記憶體不具 GPU 快取一致性。 |
| XALLOC\_MEMTYPE\_GRAPHICS\_EXECUTABLE\_WRITECOMBINE | 0xC | 表示記憶體區塊對應在 GPU 分頁表中以供間接引數使用。此記憶體為 CPU 寫入合併、GPU 可執行，且不具 GPU 快取一致性。 |

<a id="pagesizeSection" />

### PageSize

您可以透過設定 *PageSize* 的值來指定記憶體配置中使用的分頁大小。此參數可以是下表所示的其中一個值。

| XALLOC\_PAGESIZE | 值 | 描述 |
| :- | :-: | :- |
| XALLOC\_PAGESIZE\_4KB | 0 | 使用 4 KB 分頁配置。 |
| XALLOC\_PAGESIZE\_64KB | 1 | 使用 64 KB 分頁配置。 |
| XALLOC\_PAGESIZE\_2MB | 2 | 使用 2 MB 分頁配置。 |

<a id="alignmentSection" />

### Alignment

透過設定 *Alignment* 的值，您的程式碼會要求傳回的記憶體區塊採用特定對齊方式。您也可以將此參數視為 2*n* 的值，其中 *n* 是所需的對齊方式。它可以是下表所示的值。

<Note>
  預設配置器一律會傳回至少 16 位元組的對齊方式。
</Note>

| XALLOC\_ALIGNMENT |
| :- |
| XALLOC\_ALIGNMENT\_ANY |
| XALLOC\_ALIGNMENT\_4 |
| XALLOC\_ALIGNMENT\_16 |
| XALLOC\_ALIGNMENT\_32 |
| XALLOC\_ALIGNMENT\_64 |
| XALLOC\_ALIGNMENT\_128 |
| XALLOC\_ALIGNMENT\_256 |
| XALLOC\_ALIGNMENT\_512 |
| XALLOC\_ALIGNMENT\_1K |
| XALLOC\_ALIGNMENT\_2K |
| XALLOC\_ALIGNMENT\_4K |
| XALLOC\_ALIGNMENT\_8K |
| XALLOC\_ALIGNMENT\_16K |
| XALLOC\_ALIGNMENT\_32K |
| XALLOC\_ALIGNMENT\_64K |
| XALLOC\_ALIGNMENT\_128K |

<a id="suballocationSection" />

### 非圖形記憶體子配置

非圖形記憶體 (使用 XALLOC\_MEMTYPE\_HEAP\_CACHEABLE 配置的記憶體) 會依據配置的分頁大小和對齊方式進行子配置。

* 4 KB 分頁大小和 16 位元組對齊：
  * 小於 4 KB 的配置會緊密封裝
  * 大於或等於 4 KB 的配置會對齊至 4 KB 的倍數
* 64 KB 或 2 MB 分頁大小，或 16 位元組以外的對齊方式：
  * \<= 4 KB 的配置會無條件進位至 256 位元組的倍數
  * \<= 64 KB 的配置會無條件進位至 2 KB 的倍數
  * \<= 128 KB 的配置會無條件進位至 128 KB
  * 所有其他配置會無條件進位至 2 MB 邊界

<a id="requirementsSection" />

## 需求

**標頭：** xmem.h

**支援的平台：** XBOX One 系列主機和 XBOX Series 主機

<a id="seealsoSection" />

## 另請參閱

[GDK 的圖形記憶體概觀](/zh-TW/build/core-features/graphics/graphics-memory-overview)\
[XALLOC\_ALLOCATOR\_IDS](/zh-TW/reference/system/xmem/enums/xalloc_allocator_ids)\
[XMEMALLOC\_ROUTINE](/zh-TW/reference/system/xmem/functions/xmemalloc_routine)\
[XMEMFREE\_ROUTINE](/zh-TW/reference/system/xmem/functions/xmemfree_routine)\
[XMem](/zh-TW/reference/system/xmem/xmem_members)


## Related topics

- [XALLOC_ALLOCATOR_IDS](/reference/system/xmem/enums/xalloc_allocator_ids.md)
- [XMEMFREE_ROUTINE callback](/reference/system/xmem/functions/xmemfree_routine.md)
- [XMemPreallocateFreeSpace](/reference/system/xmem/functions/xmempreallocatefreespace.md)
- [XMEMALLOC_ROUTINE callback](/reference/system/xmem/functions/xmemalloc_routine.md)
- [Xmemalloc routine](/ko/reference/system/xmem/functions/xmemalloc_routine.md)