DXGKCB_ACQUIREHANDLEDATA callback function (d3dkmddi.h)

DxgkcbAcquirehandledata acquires a reference to an allocation.

Syntax

DXGKCB_ACQUIREHANDLEDATA DxgkcbAcquirehandledata;

VOID * DxgkcbAcquirehandledata(
  [in]  IN_CONST_PDXGKARGCB_GETHANDLEDATA unnamedParam1,
  [out] PDXGKARG_RELEASE_HANDLE unnamedParam2
)
{...}

Parameters

[in] unnamedParam1

Pointer to a DXGKARGCB_GETHANDLEDATA structure that describes an allocation handle returned by DxgkcbCreatecontextallocation.

[out] unnamedParam2

Pointer to a release handle for the kernel-mode driver (KMD) to manage the lifetime of the reference to acquired allocation. The KMD uses this handle when it calls DxgkcbReleasehandledata to release the allocation reference.

Return value

DxgkcbAcquirehandledata returns a handle to the allocation that the KMD requested a reference to. The KMD uses this handle for subsequent operations on the allocation or resource.

Remarks

An application or user-mode driver can call D3DKMTDestroyAllocation at any time to destroy an allocation handle. Allocation destruction involves a request to the KMD to delete the allocation object that Dxgkrnl returned to them during allocation creation, so the KMD could end up with a stale pointer to freed memory. DxgkcbAcquirehandledata and DxgkcbReleasehandledata allow the driver to hold a reference on the Dxgkrnl object and ensure that Dxgkrnl doesn't destroy the allocation and the KMD-associated objects until after the release call is made.

DXGKCB_XXX functions are implemented by Dxgkrnl. To use this callback function, set the members of DXGKARGCB_GETHANDLEDATA and then call DxgkCbAcquireHandleData via the DXGKRNL_INTERFACE.

Requirements

See also

DXGKARGCB_GETHANDLEDATA

DxgkcbCreatecontextallocation

DxgkcbReleasehandledata

DXGKRNL_INTERFACE