IDirectDrawSurface7::Lock

The IDirectDrawSurface7::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 the surface that is being locked. If NULL, the entire surface is locked.

lpDDSurfaceDesc

Address of a DDSURFACEDESC2 structure to be filled with the relevant details about the surface.

dwFlags

The following flags are defined:

DDLOCK_DONOTWAIT

On IDirectDrawSurface7 interfaces, the default is DDLOCK_WAIT. If you want to override the default and use time when the accelerator is busy (as denoted by the DDERR_WASSTILLDRAWING return value). use DDLOCK_DONOTWAIT.

DDLOCK_EVENT

Not currently implemented.

DDLOCK_NOOVERWRITE

New for DirectX 7.0. Used only with Direct3D vertex-buffer locks. Indicates that no vertices that were referred to in Draw*PrimitiveVB calls since the start of the frame (or the last lock without this flag) are modified during the lock. This can be useful when you want only to append data to the vertex buffer.

DDLOCK_NOSYSLOCK

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

DDLOCK_DISCARDCONTENTS

New for DirectX 7.0. Used only with Direct3D vertex-buffer locks. Indicates that no assumptions are made about the contents of the vertex buffer during this lock. This enables Direct3D or the driver to provide an alternative memory area as the vertex buffer. This is useful when you plan to clear the contents of the vertex buffer and fill in new data.

DDLOCK_OKTOSWAP

This flag is obsolete and was replaced by the DDLOCK_DISCARDCONTENTS flag.

DDLOCK_READONLY

Indicates that the surface being locked can 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 is write-enabled.

hEvent

Not used and must be set to NULL.

Return Values

If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

Remarks

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

In IDirectDrawSurface7, the default behavior of this method is to wait for the accelator to finish. Therefore, under default conditions, this method never returns DDERR_WASSTILLDRAWING. If you want to see the error codes and not wait until the blit operation succeeds, use the DDLOCK_DONOTWAIT flag.

After retrieving a surface memory pointer, you can access the surface memory until a corresponding IDirectDrawSurface7::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. GDI blit functions also 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 IDirectDrawSurface7::Unlock method. GUI debuggers cannot operate while the Win16Mutex is held.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 98.
  Header: Declared in ddraw.h.

See Also

IDirectDrawSurface7::Unlock, IDirectDrawSurface7::GetDC, IDirectDrawSurface7::ReleaseDC