PFND3DDDI_ALLOCATECB callback function

The pfnAllocateCb function allocates system or video memory.

Syntax


PFND3DDDI_ALLOCATECB pfnAllocateCb;

__checkReturn HRESULT APIENTRY CALLBACK pfnAllocateCb(
  _In_    HANDLE            hDevice,
  _Inout_ D3DDDICB_ALLOCATE *pData
)
{ ... }

Parameters

hDevice [in]

A handle to the display device (graphics context).

pData [in, out]

A pointer to a D3DDDICB_ALLOCATE structure that describes the allocation.

Return value

pfnAllocateCb returns one of the following values:

Return codeDescription
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.

When the driver attempts to create multiple allocations, the driver can associate all of the allocations with a parent resource (for example, when creating a flipping chain in which each backbuffer is an individual allocation). The driver can perform such an association by setting the hResource member of the D3DDDICB_ALLOCATE structure that is pointed to by pData to the value that was passed to the driver's CreateResource, CreateResource(D3D10), or CreateResource(D3D11) function. In response, the Direct3D runtime returns a kernel-mode resource handle (which is of the D3DKMT_HANDLE data type) in the hKMResource member of D3DDDICB_ALLOCATE. The user-mode display driver can subsequently insert this kernel-mode resource handle in the command stream for use by the display miniport driver.

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

Target platform

Desktop

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

D3dumddi.h (include D3dumddi.h)

See also

DxgkDdiCreateAllocation
CreateDevice
CreateDevice(D3D10)
CreateResource
CreateResource(D3D10)
CreateResource(D3D11)
D3DDDICB_ALLOCATE
D3DDDI_ALLOCATIONINFO
D3DDDI_DEVICECALLBACKS
DxgkCbEnumHandleChildren
DxgkCbGetHandleData
DxgkCbGetHandleParent

 

 

Send comments about this topic to Microsoft

Show: