IDirectDrawSurface4::Lock

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

HRESULT Lock(
  LPRECT lpDestRect,                
  LPDDSURFACEDESC2 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 DDSURFACEDESC2 structure that will be filled with the relevant details about the surface.

dwFlags

DDLOCK_EVENT

This flag is not currently implemented.

DDLOCK_NOSYSLOCK

Do not take the Win16Mutex (also known as Win16Lock). This flag is ignored when locking the primary surface.

DDLOCK_READONLY

Indicates that the surface being locked will only be read.

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 be write enabled.

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 Surface Memory Directly.

After retrieving a surface memory pointer, you can access the surface memory until a corresponding IDirectDrawSurface4::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.

Unless you include the DDLOCK_NOSYSLOCK flag, this method causes DirectDraw to hold the Win16Mutex (also known as Win16Lock) until you call the IDirectDrawSurface4::Unlock method. GUI debuggers cannot operate while the Win16Mutex is held.

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in ddraw.h.
  Import Library: Use ddraw.lib.

See Also

IDirectDrawSurface4::Unlock, IDirectDrawSurface4::GetDC, IDirectDrawSurface4::ReleaseDC