IDirectDrawSurface::Lock (Compact 2013)

3/26/2014

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.

  You need to initialize this structure's dwSize member to the size, in bytes, of the structure prior to the call. No other preparation is required.

• 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

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.

Requirements

See Also

Reference

IDirectDrawSurface
DirectDraw Reference
DirectDraw Interfaces
IDirectDrawSurface::Unlock
IDirectDrawSurface::GetDC
IDirectDrawSurface::ReleaseDC

Other Resources

DirectDraw