IDirectDrawSurface::Lock

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method obtains a pointer to the surface memory.

Syntax

HRESULT Lock(
  LPRECT lpDestRect, 
  LPDDSURFACEDESC lpDDSurfaceDesc, 
  DWORD dwFlags, 
  HANDLE hEvent
); 

Parameters

• lpDestRect
  Address of a RECT structure that identifies the region of surface that is being locked. If NULL, the entire surface will be locked.

• lpDDSurfaceDesc
  Address of a DDSURFACEDESC structure that will be filled with the relevant details about the surface.

• dwFlags
  The following table shows the possible flags.

  Flag	Description
  DDLOCK_DISCARD	Indicates that every location within the locked surface will be overwritten (with a write-only operation).
  DDLOCK_READONLY	Indicates that the surface being locked will only be read.
  DDLOCK_WAITNOTBUSY	Waits for a previously initiated drawing operation to complete instead of returning immediately with the DDERR_WASSTILLDRAWING return value. If a previous drawing operation is in progress at the time of the call, this flag defers returning from the call until the surface is locked or an error occurs.
  DDLOCK_WRITEONLY	Indicates that the surface being locked will be write-enabled.

• hEvent
  This parameter is not used and must be set to NULL.

Return Value

If the method succeeds, the return value is DD_OK.

If the method fails, the return value may be one of the following error values:

For more information on these error codes see DirectDraw Return Values.

Remarks

For more information on using this method, see Accessing Surface Memory Directly.

After retrieving a surface memory pointer, you can access the surface memory until a corresponding IDirectDrawSurface::Unlock method is called. When the surface is unlocked, the pointer to the surface memory is invalid.

In a change from previous versions of DirectDraw, only one rectangle can be locked per surface, either the entire surface or a subset of the surface. If you try to lock a second section of the surface, the method will return DirectDraw Return Values.

Do not call DirectDraw blit functions to blit from a locked region of a surface. If you do, the blit returns either DirectDraw Return Values or DDERR_LOCKEDSURFACES. Additionally, GDI blit functions will silently fail when used on a locked video memory surface.

Sample Code

An example showing the use of this function can be found in the topic How to use DirectDraw.

Requirements

See Also

Reference

IDirectDrawSurface::Unlock
IDirectDrawSurface::GetDC
IDirectDrawSurface::ReleaseDC