IDirectDrawSurface3::Lock

The IDirectDrawSurface3::Lock method obtains a pointer to the surface memory.

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

DDLOCK_EVENT
	This flag is not currently implemented.
DDLOCK_NOSYSLOCK
	If possible, do not take the Win16Lock. This flag is ignored when locking the primary surface.
DDLOCK_READONLY
	Indicates that the surface being locked will only be read from.
DDLOCK_SURFACEMEMORYPTR
	Indicates that a valid memory pointer to the top of the specified rectangle should be returned. If no rectangle is specified, a pointer to the top of the surface is returned. This is the default.
DDLOCK_WAIT
	If a lock cannot be obtained because a blit operation is in progress, the method retries until a lock is obtained or another error occurs, such as DDERR_SURFACEBUSY.
DDLOCK_WRITEONLY
	Indicates that the surface being locked will only be written to.

hEvent

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

Return Values

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:

Remarks

For more information on using this method, see Accessing the Frame-Buffer Directly.

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

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

This method often causes DirectDraw to hold the Win16Lock until you call the IDirectDrawSurface3::Unlock method. GUI debuggers cannot operate while the Win16Lock is held.

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in ddraw.h.
  Import Library: Use ddraw.lib.

See Also

IDirectDrawSurface3::Unlock, IDirectDrawSurface3::GetDC, IDirectDrawSurface3::ReleaseDC