PFND3DDDI_ALLOCATECB callback function (d3dumddi.h)
The pfnAllocateCb function allocates system or video memory.
Syntax
PFND3DDDI_ALLOCATECB Pfnd3dddiAllocatecb;
HRESULT Pfnd3dddiAllocatecb(
[in] HANDLE hDevice,
D3DDDICB_ALLOCATE *unnamedParam2
)
{...}
Parameters
[in] hDevice
A handle to the display device (graphics context).
unnamedParam2
pData [in, out]
A pointer to a D3DDDICB_ALLOCATE structure that describes the allocation.
Return value
pfnAllocateCb returns one of the following values:
| Return code | Description |
|---|---|
| S_OK | The memory was successfully allocated. |
| E_INVALIDARG | Parameters were validated and determined to be incorrect. |
| E_OUTOFMEMORY | pfnAllocateCb could not allocate memory that was required for it to complete. |
| D3DERR_OUTOFVIDEOMEMORY | pfnAllocateCb could not complete because of insufficient video memory. The video memory manager attempts to virtualize video memory; however, if the virtualization fails (such as, when virtual address space runs out), the memory manager might return this error code. |
| D3DDDIERR_DEVICEREMOVED | pfnAllocateCb could not initiate a call to the display miniport driver's DxgkDdiCreateAllocation function because a Plug and Play (PnP) stop or a Timeout Detection and Recovery (TDR) event occurred. The user-mode display driver function that called pfnAllocateCb (typically, the CreateResource, CreateResource(D3D10), or CreateResource(D3D11) function) must return this error code back to the Direct3D runtime. Direct3D Version 9 Note: For more information about returning error codes, see Returning Error Codes Received from Runtime Functions. Direct3D Versions 10 and 11 Note: If the driver function does not return a value (that is, has VOID for a return parameter type), the driver function calls the pfnSetErrorCb function to send an error code back to the runtime. For more information about handling error codes, see Handling Errors. |
This function might also return other HRESULT values.
Remarks
A user-mode display driver calls pfnAllocateCb to allocate system or video memory (also known as an allocation). The Microsoft DirectX graphics kernel subsystem (Dxgkrnl.sys) then calls the display miniport driver's DxgkDdiCreateAllocation function to interpret and store the private data that was passed in the pfnAllocateCb request. The display miniport driver returns information from the DxgkDdiCreateAllocation call that the video memory manager (which is part of Dxgkrnl.sys) uses to actually allocate the memory.
The user-mode display driver typically creates an allocation in response to a call to its CreateResource, CreateResource(D3D10), or CreateResource(D3D11) function. However, the user-mode display driver can create an allocation at anytime--for example, when the user-mode display driver's CreateDevice, or CreateDevice(D3D10) function creates scratch-pad areas in video memory.
The user-mode display driver can create the following types of allocations:
- System memory allocations in which the Microsoft Direct3D runtime preallocates the system memory. In this situation, the user-mode display driver cannot set alignment or any other parameter. If the user-mode display driver requires preallocated system memory that is accessible by the hardware, it calls pfnAllocateCb. The Direct3D runtime returns the system memory pointer in the pSystemMem member of the D3DDDI_ALLOCATIONINFO structure for elements in the pAllocationInfo member of the D3DDDICB_ALLOCATE structure that is pointed to by pData. If the user-mode display driver does not require preallocated system memory that is accessible by the hardware, it should not call pfnAllocateCb for this type of memory.
- System and video memory allocations in which the user-mode display driver can participate in the creation.
The display miniport driver can call the DxgkCbGetHandleData function on this kernel-mode resource handle (typically within its DxgkDdiRender function) to obtain private data that is associated with the resource, or the display miniport driver can call the DxgkCbEnumHandleChildren function to obtain all of the allocations that are associated with the resource. The display miniport driver can also call the DxgkCbGetHandleParent function to obtain the parent kernel-mode resource handle from a child allocation handle.
Note that if the hResource member of D3DDDICB_ALLOCATE is set to NULL when the user-mode display driver calls pfnAllocateCb, the allocation is associated with the device instead of with a resource. The driver can determine only that the difference is semantic. Associating allocations with a resource is optional but recommended for debugging and diagnostic purposes.
Direct3D Version 9 Note: For more information about creating and destroying resources, see Handling Resource Creation and Destruction.
Direct3D Version 11 Note: For more information about how the driver calls pfnAllocateCb, see Changes from Direct3D 10.
The following code example shows how to allocate memory for a resource.
D3DDDICB_ALLOCATE allocCB;
D3DDDI_ALLOCATIONINFO allocInfo;
HRESULT hr;
memset(&allocInfo, 0, sizeof(allocInfo));
memset(&allocCB, 0, sizeof(allocCB));
// Set the VidPN source ID for the primary and fullscreen back buffer
if (m_dwCurResCaps.Primary) {
allocInfo.Flags.Primary = TRUE;
allocInfo.VidPnSourceId = m_VidPnSourceId;
}
// Check if the allocation is in system memory
if (pSysMem) {
allocInfo.pSystemMem = pSysMem;
}
// Use the runtime handle of the resource being created
// NOTE: This is critical for supporting a shared resource
allocCB.hResource = m_hCurResRuntime;
allocCB.NumAllocations = 1;
allocCB.pAllocationInfo = &allocInfo;
hr = m_d3dCallbacks.pfnAllocateCb(m_hD3D, &allocCB);
if (FAILED(hr)) {
allocInfo.hAllocation = NULL;
}
else {
*phAllocation = allocInfo.hAllocation;
}
return (hr);
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows Vista and later versions of the Windows operating systems. |
| Target Platform | Desktop |
| Header | d3dumddi.h (include D3dumddi.h) |
See also
Direct3D Runtime Functions Called by the User-Mode Display Drivers