IDirect3DDeviceManager9::LockDevice method (dxva2api.h)

Article
02/22/2024

Gives the caller exclusive access to the Direct3D device.

Syntax

HRESULT LockDevice(
  [in]  HANDLE           hDevice,
  [out] IDirect3DDevice9 **ppDevice,
  [in]  BOOL             fBlock
);

Parameters

[in] hDevice

A handle to the Direct3D device. To get the device handle, call IDirect3DDeviceManager9::OpenDeviceHandle.

[out] ppDevice

Receives a pointer to the device's IDirect3DDevice9 interface.

[in] fBlock

Specifies whether to wait for the device lock. If the device is already locked and this parameter is TRUE, the method blocks until the device is unlocked. Otherwise, if the device is locked and this parameter is FALSE, the method returns immediately with the error code DXVA2_E_VIDEO_DEVICE_LOCKED.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code	Description
S_OK	The method succeeded.
DXVA2_E_NEW_VIDEO_DEVICE	The device handle is invalid.
DXVA2_E_NOT_INITIALIZED	The Direct3D device manager was not initialized. The owner of the device must call IDirect3DDeviceManager9::ResetDevice.
DXVA2_E_VIDEO_DEVICE_LOCKED	The device is locked and fBlock is FALSE.
E_HANDLE	The specified handle is not a Direct3D device handle.

Remarks

When you are done using the Direct3D device, call IDirect3DDeviceManager9::UnlockDevice to unlock to the device.

If the method returns DXVA2_E_NEW_VIDEO_DEVICE, call IDirect3DDeviceManager9::CloseDeviceHandle to close the handle and then call OpenDeviceHandle again to get a new handle. The IDirect3DDeviceManager9::ResetDevice method invalidates all open device handles.

If fBlock is TRUE, this method can potentially deadlock. For example, it will deadlock if a thread calls LockDevice and then waits on another thread that calls LockDevice. It will also deadlock if a thread calls LockDevice twice without calling UnlockDevice in between.

Examples

HRESULT LockDevice(
    IDirect3DDeviceManager9 *pDeviceManager,
    BOOL fBlock,
    IDirect3DDevice9 **ppDevice, // Receives a pointer to the device.
    HANDLE *pHandle              // Receives a device handle.   
    )
{
    *pHandle = NULL;
    *ppDevice = NULL;

    HANDLE hDevice = 0;

    HRESULT hr = pDeviceManager->OpenDeviceHandle(&hDevice);

    if (SUCCEEDED(hr))
    {
        hr = pDeviceManager->LockDevice(hDevice, ppDevice, fBlock);
    }

    if (hr == DXVA2_E_NEW_VIDEO_DEVICE)
    {
        // Invalid device handle. Try to open a new device handle.
        hr = pDeviceManager->CloseDeviceHandle(hDevice);

        if (SUCCEEDED(hr))
        {
            hr = pDeviceManager->OpenDeviceHandle(&hDevice);
        }

        // Try to lock the device again.
        if (SUCCEEDED(hr))
        {
            hr = pDeviceManager->LockDevice(hDevice, ppDevice, TRUE); 
        }
    }

    if (SUCCEEDED(hr))
    {
        *pHandle = hDevice;
    }
    return hr;
}

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	dxva2api.h