D3DKMTCreateAllocation 함수(d3dkmthk.h)

아티클
01/23/2024

D3DKMTCreateAllocation 함수는 시스템 또는 비디오 메모리 할당을 만들거나 추가합니다. 사용자 모드 그래픽 클라이언트 드라이버는 D3DKMTCreateAllocation2 를 대신 호출해야 합니다(설명 참조).

구문

NTSTATUS D3DKMTCreateAllocation(
  D3DKMT_CREATEALLOCATION *unnamedParam1
);

매개 변수

unnamedParam1

[in, out] pData: 할당을 만들기 위한 정보를 포함하는 D3DKMT_CREATEALLOCATION 구조체에 대한 포인터입니다.

반환 값

D3DKMTCreateAllocation 은 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 다음 값 중 하나와 같은 NTSTATUS 코드를 반환할 수 있습니다.

반환 코드	설명
STATUS_DEVICE_REMOVED	그래픽 어댑터가 중지되었거나 디스플레이 디바이스가 다시 설정되었습니다.
STATUS_INVALID_PARAMETER	매개 변수의 유효성이 검사되었고 잘못된 것으로 확인되었습니다.
STATUS_NO_MEMORY	시스템 메모리가 부족하여 이 루틴을 완료할 수 없습니다.
STATUS_NO_VIDEO_MEMORY	비디오 메모리가 부족하여 이 루틴을 완료할 수 없습니다. 비디오 메모리 관리자는 비디오 메모리를 가상화하려고 시도합니다. 그러나 가상화가 실패하는 경우(예: 가상 주소 공간이 부족할 때) 메모리 관리자는 이 오류 코드를 반환할 수 있습니다.

설명

사용자 모드 그래픽 클라이언트 드라이버는 D3DKMTCreateAllocation2 를 대신 호출해야 합니다. 한 가지 이유는 WSL(Linux용 Windows 하위 시스템)이 D3DKMTCreateAllocation(nf-d3dkmthk-d3dkmtcreateallocation2.md)을 지원하지 않기 때문입니다.

사용자 모드(이 경우 D3D 런타임)는 D3DKMTCreateAllocation 을 호출하여 할당 및 리소스를 만듭니다. 할당은 리소스와 연결되거나 독립 실행형일 수 있습니다.

사용자 모드가 D3DKMTCreateAllocation을 호출하면 UMD는 할당을 설명하는 프라이빗 드라이버 데이터를 제공합니다. Dxgkrnl 은 이 프라이빗 드라이버 데이터를 가져와 KMD에 전달한 다음 VidMm에서 이해하는 방식으로 각 할당에 대한 설명을 작성합니다. UMD 데이터에는 리소스 종류(텍스처, 스왑 체인 등)와 같은 정보가 포함됩니다. KMD는 이 데이터를 크기, 맞춤, 할당을 배치할 수 있는 메모리 세그먼트 집합, 이러한 세그먼트에 대한 기본 설정 등으로 변환합니다.

D3DKMTCreateAllocation 을 호출하여 언제든지 리소스에 추가 할당을 추가할 수도 있습니다. 유일한 제한 사항은 모든 공유 할당을 리소스와 연결해야 하며 추가 할당을 기존 공유 리소스에 추가할 수 없다는 것입니다.

예제

리소스와 연결되지 않은 비디오 메모리에 독립 실행형 할당 만들기

다음 코드 예제에서는 D3DKMTCreateAllocation 을 사용하여 리소스와 연결되지 않은 비디오 메모리에 독립 실행형 할당을 만드는 방법을 보여 줍니다.

D3DKMT_HANDLE CreateStandAloneAllocation(D3DKMT_HANDLE hDevice, VOID* pPrivateAllocationInfo, UINT Size)
{
    D3DKMT_CREATEALLOCATION CreateAllocation;
    D3DDDI_ALLOCATIONINFO AllocationInfo;

    memset(&CreateAllocation, 0, sizeof(CreateAllocation));
    CreateAllocation.hDevice = hDevice;
    CreateAllocation.NumAllocations = 1;
    CreateAllocation.pAllocationInfo = &AllocationInfo;

    AllocationInfo.hAllocation = NULL;
    AllocationInfo.pSystemMem = NULL;  // Vidmem allocation
    AllocationInfo.pPrivateDriverData = pPrivateAllocationInfo;  // Contains format, size, and so on.
    AllocationInfo.PrivateDriverDataSize = Size;

    if (NT_SUCCESS((*pfnKTCreateAllocation)(&CreateAllocation))) {
        return AllocationInfo.hAllocation;
    }
    return 0;
}

단일 시스템 메모리 할당을 사용하여 리소스 만들기

다음 코드 예제에서는 D3DKMTCreateAllocation 을 사용하여 단일 시스템 메모리 할당을 사용하여 리소스를 만드는 방법을 보여 줍니다.

HRESULT CreateSysmemResource(D3DKMT_HANDLE hDevice, 
                             UINT AllocationSize, 
                             VOID* pResourceData, 
                             UINT ResourceDataSize,
                             VOID* pAllocationData, 
                             UINT AllocationDataSize,
                             D3DKMT_HANDLE* phResource,
                             D3DKMT_HANDLE* phAllocation)
{
    D3DKMT_CREATEALLOCATION CreateAllocation;
    D3DDDI_ALLOCATIONINFO AllocationInfo;
    VOID* pSysMem;

    *phResource = NULL;
    *phAllocation = NULL;

    // For a sysmem allocation, preallocate the memory.
    pSysMem = MemAlloc(AllocationSize);
    if (pSysMem == NULL) {
        return E_OUTOFMEMORY;
    }
 
    memset(&CreateAllocation, 0, sizeof(CreateAllocation));
    CreateAllocation.hDevice = hDevice;
    CreateAllocation.Flags.CreateResource = TRUE;
    CreateAllocation.pPrivateDriverData = pResourceData;
    CreateAllocation.PrivateDriverDataSize = ResourceDataSize;
    CreateAllocation.NumAllocations = 1;
    CreateAllocation.pAllocationInfo = &AllocationInfo;

    AllocationInfo.hAllocation = NULL;
    AllocationInfo.pSystemMem = pSysMem;
    AllocationInfo.pPrivateDriverData = pAllocationData;
    AllocationInfo.PrivateDriverDataSize = AllocationDataSize;

    if (NT_SUCCESS((*pfnKTCreateAllocation)(&CreateAllocation))) {
        *phResource = CreateAllocation.hResource;
        *phAllocation = AllocationInfo.hAllocation;
        return S_OK;
    }
    MemFree(pSysMem);
    return E_FAIL;
}

ExistingSysMem을 사용하여 표준 할당 만들기

다음 코드 예제에서는 ExistingSysMem을 사용하여 표준 할당을 만들기 위해 D3DKMTCreateAllocation에 전달할 인수를 보여 줍니다. 런타임이 커널에 제공하는 기존 시스템 메모리 버퍼는 페이지 정렬과 페이지 크기의 배수여야 합니다. 그렇지 않으면 커널이 호출에 실패합니다.

    UINT PrivateDriverDataEstimate = 2048;

    D3DDDI_ALLOCATIONINFO2 AllocInfo = {};
    AllocInfo.pSystemMem = SomeValidPageAlignedSysMem;
    AllocInfo.VidPnSourceId = SomeVidPnSourceId;

    D3DKMDT_CREATESTANDARDALLOCATION StandardAlloc = {};
    StandardAlloc.Type = D3DKMT_STANDARDALLOCATIONTYPE_EXISTINGHEAP;
    StandardAlloc.ExistingHeapData.Size = SizeOfSystemMemBuffer; // Multiple of PAGE SIZE

    D3DKMT_CREATEALLOCATION CreateAlloc = {};
    CreateAlloc.hDevice = SomeDevice;
    CreateAlloc.NumAllocations = 1;
    CreateAlloc.pAllocationInfo2 = &AllocInfo;
    CreateAlloc.pStandardAllocation = &StandardAlloc;
    CreateAlloc.Flags.ExistingSysMem = TRUE;

    ntStatus = D3DKMTCreateAllocation(&CreateAlloc);

D3DKMTCreateAllocation에 대한 인수 제한 사항:

ExistingSysMem (또는 ExistingSection)은 StandardAllocation 에서만 지원되며 그 반대의 경우도 마찬가지입니다.
지원되는 NumAllocations 는 1입니다.
ExistingSysMem 또는 ExistingSection 중 하나만 설정할 수 있습니다.
StandardAllocation을 만들 때 CreateShared 및 CrossAdapter 플래그는 항상 설정되어야 합니다.
ExistingSysMem (또는 ExistingSection)은 기존 리소스(D3DKMT_CREATALLOCATION::hResource)에 대해 만들 수 없습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista
대상 플랫폼	유니버설
헤더	d3dkmthk.h(D3dkmthk.h 포함)
라이브러리	Gdi32.lib
DLL	Gdi32.dll

추가 정보

D3DKMT_CREATEALLOCATION

D3DKMTCreateAllocation2

다음을 통해 공유