PFND3DDDI_ALLOCATECB función de devolución de llamada (d3dumddi.h)

Artículo
02/26/2024

La función pfnAllocateCb asigna memoria de sistema o vídeo.

Sintaxis

PFND3DDDI_ALLOCATECB Pfnd3dddiAllocatecb;

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

Parámetros

[in] hDevice

Identificador del dispositivo de visualización (contexto de gráficos).

unnamedParam2

pData [in, out]

Puntero a una estructura D3DDDICB_ALLOCATE que describe la asignación.

Valor devuelto

pfnAllocateCb devuelve uno de los siguientes valores:

Código devuelto	Descripción
S_OK	La memoria se asignó correctamente.
E_INVALIDARG	Los parámetros se validaron y determinaron que son incorrectos.
E_OUTOFMEMORY	pfnAllocateCb no pudo asignar memoria necesaria para que se completara.
D3DERR_OUTOFVIDEOMEMORY	pfnAllocateCb no se pudo completar debido a una memoria de vídeo insuficiente. El administrador de memoria de vídeo intenta virtualizar la memoria de vídeo; sin embargo, si se produce un error en la virtualización (por ejemplo, cuando se agota el espacio de direcciones virtuales), el administrador de memoria podría devolver este código de error.
D3DDDIERR_DEVICEREMOVED	pfnAllocateCb no pudo iniciar una llamada a la función DxgkDdiCreateAllocation del controlador de miniporte de pantalla porque se produjo una detención de Plug and Play (PnP) o un evento de detección y recuperación de tiempo de espera (TDR). La función de controlador de visualización en modo de usuario que llamó a pfnAllocateCb (normalmente, la función CreateResource, CreateResource(D3D10) o CreateResource(D3D11) debe devolver este código de error al tiempo de ejecución de Direct3D. Direct3D versión 9 Nota: Para obtener más información sobre cómo devolver códigos de error, vea Devolver códigos de error recibidos de funciones en tiempo de ejecución. Versiones 10 y 11 de Direct3D Nota: Si la función del controlador no devuelve un valor (es decir, tiene VOID para un tipo de parámetro de valor devuelto), la función de controlador llama a la función pfnSetErrorCb para enviar un código de error de vuelta al tiempo de ejecución. Para obtener más información sobre el control de códigos de error, consulte Control de errores.

Esta función también podría devolver otros valores HRESULT.

Comentarios

Un controlador de pantalla en modo de usuario llama a pfnAllocateCb para asignar memoria de sistema o vídeo (también conocida como asignación). El subsistema del kernel de gráficos de Microsoft DirectX (Dxgkrnl.sys) llama a la función DxgkDdiCreateAllocation del controlador de miniporte de pantalla para interpretar y almacenar los datos privados que se pasaron en la solicitud pfnAllocateCb . El controlador de minipuerto de pantalla devuelve información de la llamada DxgkDdiCreateAllocation que usa el administrador de memoria de vídeo (que forma parte de Dxgkrnl.sys) para asignar realmente la memoria.

El controlador de visualización en modo de usuario normalmente crea una asignación en respuesta a una llamada a su función CreateResource, CreateResource(D3D10) o CreateResource(D3D11). Sin embargo, el controlador de pantalla en modo de usuario puede crear una asignación en cualquier momento, por ejemplo, cuando la función CreateDevice del controlador de pantalla en modo de usuario o CreateDevice(D3D10) crea áreas de panel temporal en la memoria de vídeo.

El controlador de visualización en modo de usuario puede crear los siguientes tipos de asignaciones:

Asignaciones de memoria del sistema en las que el tiempo de ejecución de Microsoft Direct3D asigna previamente la memoria del sistema. En esta situación, el controlador de pantalla en modo de usuario no puede establecer la alineación ni ningún otro parámetro. Si el controlador de pantalla en modo de usuario requiere memoria del sistema asignada previamente a la que puede acceder el hardware, llama a pfnAllocateCb. El tiempo de ejecución de Direct3D devuelve el puntero de memoria del sistema en el miembro pSystemMem de la estructura D3DDDI_ALLOCATIONINFO para los elementos del miembro pAllocationInfo de la estructura D3DDDICB_ALLOCATE a la que apunta pData. Si el controlador de pantalla en modo de usuario no requiere memoria del sistema asignada previamente a la que puede acceder el hardware, no debe llamar a pfnAllocateCb para este tipo de memoria.
Asignaciones de memoria de sistema y vídeo en las que el controlador de pantalla en modo de usuario puede participar en la creación.

Cuando el controlador intenta crear varias asignaciones, el controlador puede asociar todas las asignaciones a un recurso primario (por ejemplo, al crear una cadena de volteo en la que cada búfer es una asignación individual). El controlador puede realizar esta asociación estableciendo el miembro hResource de la estructura D3DDDICB_ALLOCATE a la que apunta pData en el valor que se pasó a la función CreateResource, CreateResource(D3D10) del controlador o CreateResource(D3D11). En respuesta, el tiempo de ejecución de Direct3D devuelve un identificador de recursos en modo kernel (que es del tipo de datos D3DKMT_HANDLE) en el miembro hKMResource de D3DDDICB_ALLOCATE. El controlador de pantalla en modo de usuario puede insertar posteriormente este identificador de recursos en modo kernel en el flujo de comandos para que lo use el controlador de minipuerto de pantalla.

El controlador de minipuerto de pantalla puede llamar a la función DxgkCbGetHandleData en este controlador de recursos en modo kernel (normalmente dentro de su función DxgkDdiRender ) para obtener datos privados asociados al recurso, o el controlador de miniporte de pantalla puede llamar a la función DxgkCbEnumHandleChildren para obtener todas las asignaciones asociadas al recurso. El controlador de minipuerto de pantalla también puede llamar a la función DxgkCbGetHandleParent para obtener el identificador de recursos del modo kernel primario de un identificador de asignación secundario.

Tenga en cuenta que si el miembro hResource de D3DDDICB_ALLOCATE se establece en NULL cuando el controlador de pantalla en modo de usuario llama a pfnAllocateCb, la asignación se asocia con el dispositivo en lugar de con un recurso. El controlador solo puede determinar que la diferencia es semántica. La asociación de asignaciones con un recurso es opcional, pero se recomienda para fines de depuración y diagnóstico.

Nota de Direct3D versión 9: Para obtener más información sobre cómo crear y destruir recursos, consulte Control de la creación y destrucción de recursos.

Nota de Direct3D versión 11: Para obtener más información sobre cómo el controlador llama a pfnAllocateCb, consulta Cambios de Direct3D 10.

En el ejemplo de código siguiente se muestra cómo asignar memoria para un recurso.

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

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows Vista y versiones posteriores de los sistemas operativos Windows.
Plataforma de destino	Escritorio
Encabezado	d3dumddi.h (incluya D3dumddi.h)