XMemVirtualAlloc

保留、認可或變更呼叫處理序之虛擬位址空間中某個分頁區域的狀態。

與標準 Win32 VirtualAlloc 不同，此函式所配置的記憶體_不_保證會自動初始化為零。

語法

PVOID XMemVirtualAlloc(  
         PVOID BaseAddress,  
         SIZE_T Size,  
         DWORD AllocationType,  
         ULONGLONG XMemFlags,  
         DWORD PageProtection  
)  

參數

BaseAddress _In_opt_
類型：PVOID 要配置之區域的起始位址。如果正在保留記憶體，指定的位址會無條件捨去至配置細微度 (在 XBOX 上為 4K、64K 或 2MB) 最接近的倍數。如果記憶體已保留且正在認可，則位址會無條件捨去至下一個分頁邊界。如果此參數為 NULL，系統會決定要在何處配置區域。
Size _In_
類型：SIZE_T 區域的大小 (以位元組為單位)。如果 BaseAddress 參數為 NULL，此值會無條件進位到下一個分頁邊界。否則，配置的分頁會包含在 BaseAddress 到 BaseAddress+Size 範圍內含有一或多個位元組的所有分頁。這表示跨越分頁邊界的 2 位元組範圍會導致兩個分頁都包含在配置的區域中。
AllocationType _In_
類型：DWORD 記憶體配置的類型。此參數必須包含下列其中一個值。

值	意義
MEM_COMMIT 0x00001000	為指定的保留記憶體分頁配置記憶體費用 (從記憶體的整體大小中扣除)。若要一步完成保留和認可分頁，請以 `MEM_COMMIT	MEM_RESERVE` 呼叫 XMemVirtualAlloc。除非整個範圍都已保留，否則嘗試透過指定 MEM_COMMIT (不含 MEM_RESERVE) 和非 NULL 的 BaseAddress 來認可特定位址範圍將會失敗。產生的錯誤碼為 ERROR_INVALID_ADDRESS。嘗試認可已認可的分頁不會導致函式失敗。這表示您可以認可分頁，而不需要先判斷每個分頁目前的認可狀態。
MEM_RESERVE 0x00002000	保留處理序虛擬位址空間的範圍，而不在記憶體中配置任何實際的實體儲存體。您可以在後續呼叫 XMemVirtualAlloc 函式時認可保留的分頁，或使用 XMemMapPhysicalPages 直接對應實體分頁。其他記憶體配置函式 (例如 malloc 和 new) 在保留的記憶體範圍釋放之前無法使用該範圍。請注意，XBOX 上 Microsoft Game Development Kit (GDK) 中的新記憶體管理員需要在保留時設定分頁保護和快取一致性，這是與舊版 XBOX OS 不同之處。
MEM_RESERVE_PLACEHOLDER 0x00040000	預留位置會保留虛擬位址，但不會將 VA 鎖定為特定的分頁大小或分頁保護。分頁大小和分頁保護會在使用 MEM_REPLACE_PLACEHOLDER 以實際保留或認可取代預留位置時選取。若要建立預留位置，請以 MEM_RESERVE \| MEM_RESERVE_PLACEHOLDER 呼叫 XMemVirtualAlloc，並將 PageProtection 設定為 PAGE_NOACCESS。使用 MEM_RESERVE_PLACEHOLDER 一律會傳回 2MB 對齊的位址，以確保日後可與 MEM_2MB_PAGES 搭配使用。不過，一旦保留之後，便可使用 VirtualFree 搭配 MEM_RELEASE \| MEM_PRESERVE_PLACEHOLDER，以任何細微度 (4K、64K 或 2MB) 分割預留位置。
MEM_REPLACE_PLACEHOLDER 0x00004000	以一般私人配置取代預留位置。取代預留位置時，BaseAddress 和 Size 必須與預留位置的值完全相符。以私人配置取代預留位置後，若要將該配置釋放回預留位置，請參閱 VirtualFree 和 VirtualFreeEx 的 dwFreeType 參數。

此參數也可以指定下列值，如下所示。

值	意義
MEM_2MB_PAGES 0x20000000	指定 2MB 的分頁大小。
MEM_64K_PAGES 0x20400000	指定 64K 的分頁大小。

對於 ERA 遊戲，MEM_LARGE_PAGES 代表 64K 分頁，而在 Windows 桌面上代表 2MB 分頁。由於有此歧義，Microsoft Game Development Kit (GDK) 已將其移除。

XMemFlags _In_
類型：ULONGLONG 在 XBOX 上用來取得特定的特殊記憶體類型。此參數必須包含下列其中一個值。

值	意義
XMEM_CPU 0x00000001	配置只有 CPU 可存取的記憶體。
XMEM_GRAPHICS 0x00000003	配置 CPU 和 GPU 都可存取的記憶體。任何以 XMEM_GRAPHICS 認可的記憶體都會對應到 GPU 的分頁表中。
XMEM_GRAPHICS_32BIT_ADDRESS 0x00000007	指定自動指派的位址位於位址空間的低 4GB 中。使用此旗標認可的記憶體也可供 GPU 存取。

在 XBOX 上，可以配置具有受限虛擬記憶體位址的記憶體，以保證不會使用高位元。使用下列任一值會將位址限制為只使用指定的位元數。XMEM_40BIT_ADDRESS (0x00007000ULL)、XMEM_41BIT_ADDRESS (0x00006000ULL)、XMEM_42BIT_ADDRESS (0x00005000ULL)、XMEM_43BIT_ADDRESS (0x00004000ULL)、XMEM_44BIT_ADDRESS (0x00003000ULL)、XMEM_45BIT_ADDRESS (0x00002000ULL)、XMEM_46BIT_ADDRESS (0x00001000ULL)。

在建立 D3D12Device 或呼叫 D3DConfigureVirtualMemory 之前，無法配置圖形記憶體。如果要求的記憶體將對 GPU 可見，遊戲_必須_同時指定明確的圖形分頁保護旗標，不再有依據 CPU 分頁保護設定的預設值。這是與舊版 XBOX OS 不同之處。

此參數也可以指定下列值，如下所示。

值	意義
XMEM_TOOL 0x00000010	指定配置計入工具分割區，而非遊戲分割區。此旗標需要在 AllocationType 參數上指定 MEM_2MB_PAGES 或 MEM_64K_PAGES。
XMEM_MAPPABLE 0x00000020	指定配置是要透過 XMemMapPhysicalPages 用於實體分頁對應的位址保留。此旗標需要在 AllocationType 參數上指定 MEM_RESERVE 以及 MEM_2MB_PAGES 或 MEM_64K_PAGES。

在 Anaconda 裝置以及模擬 Anaconda 的 Dante 裝置上，使用進階遊戲記憶體模式時，也可以套用下列參數。在所有其他情況下，這些參數都會被忽略。

這些旗標是選擇性的。如果未指定，所有圖形配置預設都會使用 XMEM_GPU_OPTIMAL_BANDWIDTH_PREFERRED，而所有其他配置預設都會使用 XMEM_STANDARD_BANDWIDTH_PREFERRED。

值	意義
XMEM_STD_BW_REQ 或 XMEM_STANDARD_BANDWIDTH_REQUIRED 0x00000080	指定配置必須使用標準頻寬記憶體來滿足。
XMEM_STD_BW_PREF 或 XMEM_STANDARD_BANDWIDTH_PREFERRED 0x00000180	指定配置應優先使用標準頻寬記憶體，只有在標準頻寬記憶體耗盡時才使用 GPU 最佳頻寬記憶體。
XMEM_GPU_OPTBW_REQ 或 XMEM_GPU_OPTIMAL_BANDWIDTH_REQUIRED 0x00000280	指定配置必須使用 GPU 最佳頻寬記憶體來滿足。
XMEM_GPU_OPTBW_PREF 或 XMEM_GPU_OPTIMAL_BANDWIDTH_PREFERRED 0x00000380	指定配置應優先使用 GPU 最佳頻寬記憶體，只有在 GPU 最佳頻寬記憶體耗盡時才使用標準頻寬記憶體。

XMemFlags 參數包含選擇性的四字元代碼標籤。字元可以是 a-z、A-Z、0-9 和 $ 中的任一字元。可使用 XMemMakeTag 函式，在正確的位元位置建構正確編碼的標籤值。標籤只能與已認可的記憶體區域建立關聯，而不能與保留建立關聯。此四字元代碼標籤會由參數的高 24 位元表示。標籤可透過 XMemVirtualQuery 擷取，也會顯示在 PIX 記憶體分析中。範例：

PVOID mem = XMemVirtualAlloc(NULL, size, MEM_64K_PAGES | MEM_COMMIT, XMemMakeTag('Fred') | XMEM_CPU, PAGE_READWRITE);

PageProtection _In_
類型：DWORD 要配置之分頁區域的記憶體保護。如果正在認可分頁，您可以指定任一記憶體保護常數。 PageProtection 參數允許使用下列 XBOX 專屬值，且指定 XMEM_GRAPHICS 或 XMEM_GRAPHICS_32BIT_ADDRESS 時必須指定其中一個值。此需求是與舊版 XBOX OS 不同之處。對於以 XMEM_GRAPHICS 配置之範圍內的記憶體位址，這些值也可以指定給其他記憶體管理函式 (例如 VirtualProtect)。

值	意義
PAGE_GRAPHICS_NOACCESS 0x0800	指定記憶體在 GPU 上無法存取。
PAGE_GRAPHICS_READONLY 0x1000	指定記憶體在 GPU 上為唯讀。
PAGE_GRAPHICS_READWRITE 0x2000	指定記憶體在 GPU 上為可讀寫。
PAGE_GRAPHICS_EXECUTE 0x4000 GRAPHICS_EXECUTE_READ 0x8000 PAGE_GRAPHICS_EXECUTE_READWRITE 0x10000	指定記憶體在 GPU 上為可執行。命令緩衝區需要此設定。

此參數也可以指定下列值，如下所示。

值	意義
PAGE_GRAPHICS_COHERENT 0x20000	指定與 GPU 共用的記憶體在 CPU 和 GPU 快取之間會保持一致。
PAGE_GRAPHICS_NOCACHE 0x40000	指定 GPU 存取記憶體時不會快取記憶體。此旗標僅適用於 XBOX Series X\|S 主機。

傳回值

類型：PVOID 如果函式成功，傳回值為所配置分頁區域的基底位址。如果函式失敗，傳回值為 NULL。若要取得延伸錯誤資訊，請呼叫 GetLastError。

備註

每個分頁都有相關聯的分頁狀態。XMemVirtualAlloc 函式可以執行下列作業：

認可保留分頁的區域
保留可用分頁的區域
同時保留和認可可用分頁的區域

XMemVirtualAlloc 無法保留已保留的分頁。它可以認可已認可的分頁。這表示您可以認可某個範圍的分頁，無論這些分頁是否已認可，函式都不會失敗。您可以使用 XMemVirtualAlloc 保留一個分頁區塊，然後再呼叫 XMemVirtualAlloc 來認可保留區塊中的個別分頁。這可讓處理序保留其虛擬位址空間的範圍，而在需要之前不會耗用實體儲存體。如果 BaseAddress 參數不是 NULL，函式會使用 BaseAddress 和 Size 參數來計算要配置的分頁區域。整個分頁範圍目前的狀態必須與 AllocationType 參數所指定的配置類型相容。否則，函式會失敗，且不會配置任何分頁。如前所述，此相容性需求並不排除認可已認可的分頁。 XMemVirtualAlloc 函式可用於在呼叫處理序的虛擬位址空間內保留指定用來對應實體分頁的記憶體區域。接著，此記憶體區域便可依應用程式的需要，用來將實體分頁對應進出虛擬記憶體。必須在 AllocationType 參數中設定 MEM_RESERVE 和 MEM_64K_PAGES 值；不得設定 MEM_COMMIT 值。必須在 XMemFlags 參數上設定 XMEM_MAPPABLE。以此方式保留的位址空間是使用 XMemMapPhysicalPages API 來認可。 VirtualFree 函式可以解除認可已認可的分頁並釋放該分頁的儲存體，也可以同時解除認可並釋放已認可的分頁。它也可以釋放保留的分頁，使其成為可用分頁。除了提供 XBOX 專屬記憶體特性的延伸之外，此 API 與 VirtualAlloc 的差異在於，它不強制保證傳回的記憶體會初始化為零。XMemVirtualAlloc 也不保證會保留先前的記憶體內容。遊戲中 XMemVirtualAlloc 的大多數使用案例涉及取得圖形記憶體 (通常不會因初始化為零而受益)，或將記憶體新增至堆積實作 (從零初始化中獲得的實用價值很少)。此外，呼叫端可以輕易地在自己選擇的時間實作將傳回的記憶體初始化為零。由於不強制 VirtualAlloc 的這項保證，XMemVirtualAlloc 的實作有更大的彈性，能夠提供更高的效能。 XMemVirtualAlloc 與 VirtualAlloc 的另一個差異在於，透過此 API 呼叫取得的記憶體可以立即使用。相較之下，VirtualAlloc 傳回的記憶體位址只會在第一次存取時，透過代價高昂的分頁錯誤作業填入實體分頁。以 XMemVirtualAlloc 配置的記憶體應使用 VirtualFree 釋放。 PAGE_NOCACHE 和 PAGE_WRITECOMBINE 分頁保護旗標會在記憶體保留時固定，無法在之後的認可要求期間變更。認可記憶體時嘗試變更這些旗標其中之一的狀態，將會被無聲地忽略。記憶體認可會成功，但記憶體的這些旗標仍會保持原始狀態。範例：

// Allocate standard CPU only memory, using default (4K) pages
PVOID cpuMemory = XMemVirtualAlloc (NULL,
                                    1024 * 1024,
                                    MEM_RESERVE | MEM_COMMIT,
                                    XMEM_CPU,
                                    PAGE_READWRITE);

// Allocate 1MB of tooling memory using 64K pages
PVOID cpu64kmemory = XMemVirtualAlloc (NULL,
                                       1024 * 1024,
                                       MEM_64K_PAGES | MEM_RESERVE | MEM_COMMIT,
                                       XMEM_TOOL | XMEM_CPU,
                                       PAGE_READWRITE);

// Allocate 2MB graphics memory
PVOID gfx64kmemory = XMemVirtualAlloc (NULL,
                                       2 * 1024 * 1024,
                                       MEM_2MB_PAGES | MEM_RESERVE | MEM_COMMIT,
                                       XMEM_GRAPHICS,
                                       PAGE_READWRITE | PAGE_GRAPHICS_READONLY);

// Allocate 1MB of graphics memory using 64K pages in 32b address space
PVOID gfxmemory32b = XMemVirtualAlloc (NULL,
                                       1024 * 1024,
                                       MEM_64K_PAGES | MEM_RESERVE | MEM_COMMIT,
                                       XMEM_GRAPHICS_32BIT_ADDRESS,
                                       PAGE_READONLY | PAGE_GRAPHICS_READWRITE);

// Reserve 1GB of CPU visible VA space using 64K pages
PVOID cpuReserve = XMemVirtualAlloc (NULL,
                                     1024 * 1024 * 1024,
                                     MEM_64K_PAGES | MEM_RESERVE,
                                     XMEM_CPU,
                                     PAGE_READWRITE);

// Now commit the first 2MB of the reservation
PVOID cpuCommit = XMemVirtualAlloc (cpuReserve,
                                    2 * 1024 * 1024,
                                    MEM_COMMIT,
                                    XMEM_CPU,
                                    PAGE_READWRITE);

// Reserve 4MB of visible VA space intended for direct physical page mapping
// Note that physical pages are always 64KB and this reservation assumes
// any allocations will be in 32 or 64 page (2MB\4MB) blocks
PVOID physicalReserve = XMemVirtualAlloc (NULL,
                                          4 * 1024 * 1024,
                                          MEM_2MB_PAGES | MEM_RESERVE,
                                          XMEM_GRAPHICS | XMEM_MAPPABLE,
                                          PAGE_READONLY | PAGE_GRAPHICS_COHERENT | PAGE_GRAPHICS_READWRITE);

需求

標頭： xmem.h 程式庫： xmem.lib 支援的平台： XBOX One 系列主機和 XBOX Series 主機

另請參閱

XMem 參考
XMemMapPhysicalPages
VirtualFree

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

XMemVirtualAlloc

XMemVirtualAlloc

語法

參數

傳回值

備註

需求

另請參閱

​XMemVirtualAlloc

​語法

​參數

​傳回值

​備註

​需求

​另請參閱

XMemVirtualAlloc

語法

參數

傳回值

備註

需求

另請參閱