PFND3DDDI_ALLOCATECB回调函数 (d3dumddi.h)

项目
08/07/2023

pfnAllocateCb 函数分配系统或视频内存。

语法

PFND3DDDI_ALLOCATECB Pfnd3dddiAllocatecb;

HRESULT Pfnd3dddiAllocatecb(
  [in] HANDLE hDevice,
       D3DDDICB_ALLOCATE *unnamedParam2
)
{...}

参数

[in] hDevice

显示设备的句柄 (图形上下文) 。

unnamedParam2

pData [in， out]

指向描述分配的D3DDDICB_ALLOCATE 结构的指针。

返回值

pfnAllocateCb 返回以下值之一：

返回代码	说明
S_OK	已成功分配内存。
E_INVALIDARG	参数已验证，确定为不正确。
E_OUTOFMEMORY	pfnAllocateCb 无法分配完成该操作所需的内存。
D3DERR_OUTOFVIDEOMEMORY	由于视频内存不足，pfnAllocateCb 无法完成。视频内存管理器尝试虚拟化视频内存;但是，如果虚拟化失败 (例如，当虚拟地址空间用完) 时，内存管理器可能会返回此错误代码。
D3DDDIERR_DEVICEREMOVED	pfnAllocateCb 无法启动对显示微型端口驱动程序的 DxgkDdiCreateAllocation 函数的调用，因为发生了即插即用 (PnP) 停止或超时检测和恢复 (TDR) 事件。通常，调用 pfnAllocateCb 的用户模式显示驱动程序函数 (CreateResource、 CreateResource (D3D10) 或 CreateResource (D3D11) 函数) 必须将此错误代码返回给 Direct3D 运行时。 Direct3D 版本 9 注意：有关返回错误代码的详细信息，请参阅返回从运行时函数收到的错误代码。 Direct3D 版本 10 和 11 注意：如果驱动程序函数未返回值 (即，具有返回参数类型) 的 VOID，则驱动程序函数调用 pfnSetErrorCb 函数以将错误代码发送回运行时。有关处理错误代码的详细信息，请参阅处理错误。

此函数还可能返回其他 HRESULT 值。

注解

用户模式显示驱动程序调用 pfnAllocateCb 来分配系统内存或视频内存 (也称为分配) 。 Microsoft DirectX 图形内核子系统 (Dxgkrnl.sys) 然后调用显示微型端口驱动程序的 DxgkDdiCreateAllocation 函数来解释和存储 pfnAllocateCb 请求中传递的私有数据。显示微型端口驱动程序从 DxgkDdiCreateAllocation 调用返回信息，视频内存管理器 (该调用是) 实际分配内存 Dxgkrnl.sys 的一部分。

用户模式显示驱动程序通常会创建分配，以响应对其 CreateResource、 CreateResource (D3D10) 或 CreateResource (D3D11) 函数的调用。但是，用户模式显示驱动程序可以随时创建分配，例如，当用户模式显示驱动程序的 CreateDevice 或 CreateDevice (D3D10) 函数在视频内存中创建暂存板区域时。

用户模式显示驱动程序可以创建以下类型的分配：

Microsoft Direct3D 运行时在其中预分配系统内存的系统内存分配。在这种情况下，用户模式显示驱动程序无法设置对齐方式或任何其他参数。如果用户模式显示驱动程序需要硬件可访问的预分配系统内存，它将调用 pfnAllocateCb。对于 pData 指向的 D3DDDICB_ALLOCATE 结构的 pAllocationInfo 成员中的元素，Direct3D 运行时返回 D3DDDI_ALLOCATIONINFO 结构的pSystemMem 成员中的系统内存指针。如果用户模式显示驱动程序不需要硬件可访问的预分配系统内存，则它不应为这种类型的内存调用 pfnAllocateCb 。
用户模式显示驱动程序可以参与创建的系统和视频内存分配。

当驱动程序尝试创建多个分配时，驱动程序可以将所有分配与父资源关联 (例如，在创建翻转链时，其中每个反缓冲区都是单个分配) 。驱动程序可以通过将 pData 指向的 D3DDDICB_ALLOCATE 结构的 hResource 成员设置为传递给驱动程序的 CreateResource、CreateResource (D3D10) 或 CreateResource (D3D11) 函数的值来执行此类关联。作为响应，Direct3D 运行时返回内核模式资源句柄 (该句柄属于 D3DDDICB_ALLOCATE 的 hKMResource 成员中的D3DKMT_HANDLE数据类型) 。用户模式显示驱动程序随后可以在命令流中插入此内核模式资源句柄，以供显示微型端口驱动程序使用。

显示微型端口驱动程序可以在此内核模式资源句柄上调用 DxgkCbGetHandleData 函数， (通常在其 DxgkDdiRender 函数) 中调用，以获取与资源关联的专用数据，或者显示微型端口驱动程序可以调用 DxgkCbEnumHandleChildren 函数以获取与资源关联的所有分配。显示微型端口驱动程序还可以调用 DxgkCbGetHandleParent 函数，以从子分配句柄获取父内核模式资源句柄。

请注意，如果在用户模式显示驱动程序调用 pfnAllocateCb 时将 D3DDDICB_ALLOCATE 的 hResource 成员设置为 NULL，则分配与设备而不是资源相关联。驱动程序只能确定差异是否为语义。将分配与资源关联是可选的，但建议用于调试和诊断目的。

Direct3D 版本 9 注意： 有关创建和销毁资源的详细信息，请参阅处理资源创建和销毁。

Direct3D 版本 11 注意： 有关驱动程序如何调用 pfnAllocateCb 的详细信息，请参阅 Direct3D 10 中的更改。

下面的代码示例演示如何为资源分配内存。

    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);

要求

要求	值
最低受支持的客户端	在 Windows Vista 和更高版本的 Windows 操作系统中可用。
目标平台	桌面
标头	d3dumddi.h (包括 D3dumddi.h)