LockSurfaceDC method

  • Article

Locks a region of the surface and returns an IDXDCLock interface.

Syntax

HRESULT retVal = object.LockSurfaceDC(pBounds, ulTimeOut, dwFlags, ppDCLock);

Parameters

  • pBounds [in]
    Type: const DXBNDS

    Pointer to the region to lock, as specified by the DXBNDS structure. If NULL, the entire surface is locked.

  • ulTimeOut [in]
    Type: unsigned long

    Time, in milliseconds, to wait for the lock to be obtained. You can use INFINITE for this parameter. If the lock fails because of a time-out, the call returns E_ABORT.

  • dwFlags [in]
    Type: DWORD

    DWORD value that indicates the lock type. Specify DXLOCKF_READ for read-only access or DXLOCKF_READWRITE for read/write access to the surface.

  • ppDCLock [out]
    Type: IDXDCLock

    Address of a pointer to the IDXDCLock interface.

Remarks

This method is similar to the IDXSurface::LockSurface but is used to gain access to the surface's handle to a device context (HDC) so that Microsoft Win32 Windows Graphics Device Interface (GDI) operations can be performed on the data. Many surfaces, such as procedural surfaces, will not have an associated HDC, so this call might return E_NOTIMPL. In this case, if an HDC is required, you can use the IDXSurfaceFactory::CopySurfaceToNewFormat method to obtain a DXSurface that supports an HDC.

The locking semantics are similar to IDXSurface::LockSurface, and subregions of the surface can be locked for reading or writing. One important difference is that all HDC locks are not relative to the locked region. In addition, the HDC references the entire surface, regardless of the bounds locked.

The returned interface supports only a single method: IDXDCLock::GetDC, which returns an HDC. The HDC returned is valid for the entire time that a reference is held on the IDXDCLock object. When the object is released by means of Release, the HDC is released and the caller should not use it again.