Share via


IDirectDrawSurface5::Lock

This 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
    The following table shows the possible flags.
    Flag Description
    DDLOCK_EVENT This flag is not currently implemented. Triggers the event when IDirectDrawSurface5::Lock can return the surface memory pointer requested. This flag is set if an event handle is being passed to IDirectDrawSurface5::Lock. If multiple locks of this type are placed on a surface, events are triggered in FIFO order.
    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.
    DDLOCK_NOSYSLOCK This flag is not supported in Windows CE.
  • 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:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

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 IDirectDrawSurface5::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.

Requirements

OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later.
Header: Ddraw.h.
Link Library: Ddraw.lib.

See Also

IDirectDrawSurface5::Unlock | IDirectDrawSurface5::GetDC | IDirectDrawSurface5::ReleaseDC

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.