PFND3DDDI_UNLOCKCB callback function (d3dumddi.h)

Article
04/01/2021

The pfnUnlockCb function unlocks an allocation that was locked by a call to the pfnLockCb function.

Syntax

PFND3DDDI_UNLOCKCB Pfnd3dddiUnlockcb;

HRESULT Pfnd3dddiUnlockcb(
  HANDLE hDevice,
  const D3DDDICB_UNLOCK *unnamedParam2
)
{...}

Parameters

hDevice

A handle to the display device (graphics context).

unnamedParam2

pData [in]

A pointer to a D3DDDICB_UNLOCK structure that describes the allocation to unlock.

Return value

pfnUnlockCb returns one of the following values:

Return code	Description
S_OK	The allocation was successfully unlocked.
E_OUTOFMEMORY	pfnUnlockCb could not complete because of insufficient memory. (This error occurs when the system is in an extreme low memory situation and there is not sufficient space to allocate the array of pages.)
E_INVALIDARG	Parameters were validated and determined to be incorrect.

This function might also return other HRESULT values.

Remarks

The user-mode display driver must call the pfnUnlockCb function to unlock an allocation that was previously locked in a call to the pfnLockCb function. If the driver does not call pfnUnlockCb, coordination between the Microsoft Direct3D runtime, the user-mode display driver, and the display miniport driver is lost.

The user-mode display driver typically calls pfnUnlockCb in response to a call to its Unlock or ResourceUnmap function (or other variations of ResourceUnmap such as DynamicIABufferUnmap) to unlock a resource or a surface within the resource. Before returning from the Unlock or ResourceUnmap call, the user-mode display driver must first map the resource or surface to the appropriate allocation and then call pfnUnlockCb to unlock the allocation.

The user-mode display driver can also call pfnUnlockCb in response to a call to its DestroyDevice or DestroyDevice(D3D10) function to free all of the resources that it allocated for the device. In the lifetime of a device, every call to pfnLockCb to lock an allocation must be paired with a call to the pfnUnlockCb function to unlock the allocation.

The user-mode display driver can unlock multiple allocations in one call to pfnUnlockCb by setting the NumAllocations member of the D3DDDICB_UNLOCK structure to the number of allocations in the array that is specified by the phAllocations member of D3DDDICB_UNLOCK.

The user-mode display driver should call pfnUnlockCb to unlock all of the allocations that are referred to in the command stream before calling the pfnRenderCb function. The driver could have allocations locked to support--for example, the NoOverwrite bit-field flag. If the driver does not unlock all of these allocations, the video memory manager might be required to place these allocations in AGP memory.

The user-mode display driver should not call pfnUnlockCb to unlock an allocation that an application could be using. The driver is notified that the application is no longer reading from or writing to the allocation when the driver receives a call to its Unlock or ResourceUnmap function on the corresponding resource.

Examples

The following code example shows how to unlock an allocation.

HRESULT CD3DContext::SyncEnginesUsingLock(VOID) {
    HRESULT hr;
    D3DDDICB_LOCK   lockCB;
    D3DDDICB_UNLOCK Unlock;

    memset(&lockCB, 0, sizeof(D3DDDICB_LOCK));
    lockCB.hAllocation = m_HandleUsedInLastSubmit;
    lockCB.PrivateDriverData = 0;                       
    hr = m_d3dCallbacks.pfnLockCb(m_hD3D, &lockCB);
    if (FAILED(hr)) {
        DBG_BREAK;
        return hr;
    }
    Unlock.NumAllocations = 1;
    Unlock.phAllocations = &m_HandleUsedInLastSubmit;
    m_d3dCallbacks.pfnUnlockCb(m_hD3D, &Unlock);   
    return hr;
}

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of the Windows operating systems.
Target Platform	Desktop
Header	d3dumddi.h (include D3dumddi.h)