PFND3DDDI_ALLOCATECB 콜백 함수(d3dumddi.h)

아티클
02/26/2024

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	pnAllocateCb는 플러그 앤 플레이(PnP) 중지 또는 TDR(시간 제한 검색 및 복구) 이벤트가 발생했기 때문에 디스플레이 미니포트 드라이버의 DxgkDdiCreateAllocation 함수에 대한 호출을 시작할 수 없습니다. pfnAllocateCb(일반적으로 CreateResource, CreateResource (D3D10) 또는 CreateResource(D3D11) 함수)를 호출한 사용자 모드 표시 드라이버 함수는 이 오류 코드를 Direct3D 런타임으로 다시 반환해야 합니다. Direct3D 버전 9 참고: 오류 코드 반환에 대한 자세한 내용은 런타임 함수에서 받은 오류 코드 반환을 참조하세요. Direct3D 버전 10 및 11 참고: 드라이버 함수가 값을 반환하지 않는 경우(즉, 반환 매개 변수 형식에 대한 VOID가 있음) 드라이버 함수는 pfnSetErrorCb 함수를 호출하여 오류 코드를 런타임으로 다시 보냅니다. 오류 코드 처리에 대한 자세한 내용은 오류 처리를 참조하세요.

이 함수는 다른 HRESULT 값을 반환할 수도 있습니다.

설명

사용자 모드 디스플레이 드라이버는 pfnAllocateCb 를 호출하여 시스템 또는 비디오 메모리(할당이라고도 함)를 할당합니다. Microsoft DirectX 그래픽 커널 하위 시스템(Dxgkrnl.sys)은 디스플레이 미니포트 드라이버의 DxgkDdiCreateAllocation 함수를 호출하여 pfnAllocateCb 요청에 전달된 개인 데이터를 해석하고 저장합니다. 디스플레이 미니포트 드라이버는 비디오 메모리 관리자(Dxgkrnl.sys일부)가 실제로 메모리를 할당하는 데 사용하는 DxgkDdiCreateAllocation 호출에서 정보를 반환합니다.

사용자 모드 표시 드라이버는 일반적으로 CreateResource, CreateResource (D3D10) 또는 CreateResource(D3D11 ) 함수에 대한 호출에 대한 응답으로 할당을 만듭니다. 그러나 사용자 모드 디스플레이 드라이버는 사용자 모드 디스플레이 드라이버의 CreateDevice 또는 CreateDevice(D3D10) 함수가 비디오 메모리에 스크래치 패드 영역을 만드는 경우와 같이 언제든지 할당을 만들 수 있습니다.

사용자 모드 표시 드라이버는 다음과 같은 유형의 할당을 만들 수 있습니다.

Microsoft Direct3D 런타임이 시스템 메모리를 미리 할당하는 시스템 메모리 할당입니다. 이 경우 사용자 모드 표시 드라이버는 맞춤 또는 다른 매개 변수를 설정할 수 없습니다. 사용자 모드 디스플레이 드라이버에 하드웨어에서 액세스할 수 있는 미리 할당된 시스템 메모리가 필요한 경우 pfnAllocateCb를 호출합니다. Direct3D 런타임은 pData가 가리키는 D3DDDICB_ALLOCATE 구조체의 pAllocationInfo 멤버에 있는 요소에 대해 D3DDDI_ALLOCATIONINFO 구조체의 pSystemMem 멤버에 시스템 메모리 포인터를 반환합니다. 사용자 모드 디스플레이 드라이버에 하드웨어에서 액세스할 수 있는 미리 할당된 시스템 메모리가 필요하지 않은 경우 이 유형의 메모리에 대해 pfnAllocateCb 를 호출하면 안 됩니다.
사용자 모드 디스플레이 드라이버가 생성에 참여할 수 있는 시스템 및 비디오 메모리 할당입니다.

드라이버가 여러 할당을 만들려고 하면 드라이버는 모든 할당을 부모 리소스와 연결할 수 있습니다(예: 각 백버퍼가 개별 할당인 대칭 이동 체인을 만들 때). 드라이버는 pData가 가리키는 D3DDDICB_ALLOCATE 구조체의 hResource 멤버를 드라이버의 CreateResource, CreateResource (D3D10) 또는 CreateResource(D3D11) 함수에 전달된 값으로 설정하여 이러한 연결을 수행할 수 있습니다. 이에 대한 응답으로 Direct3D 런타임은 D3DDDICB_ALLOCATE hKMResource 멤버에 커널 모드 리소스 핸들(D3DKMT_HANDLE 데이터 형식)을 반환합니다. 사용자 모드 디스플레이 드라이버는 이후에 이 커널 모드 리소스 핸들을 명령 스트림에 삽입하여 디스플레이 미니포트 드라이버에서 사용할 수 있습니다.

디스플레이 미니포트 드라이버는 이 커널 모드 리소스 핸들(일반적으로 DxgkDdiRender 함수 내)에서 DxgkCbGetHandleData 함수를 호출하여 리소스와 연결된 개인 데이터를 가져오거나 디스플레이 미니포트 드라이버가 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 포함)