IDirectDrawSurface5::Lock

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The IDirectDrawSurface5::Lockmethod obtains a pointer to the surface memory.

HRESULT Lock(
LPRECT
lpDestRect
,
LPDDSURFACEDESC2
lpDDSurfaceDesc
,
DWORD
dwFlags
,
HANDLE
hEvent
);

Parameters

lpDestRect

Address of a RECTstructure that identifies the region of surface that is being locked. If NULL, the entire surface will be locked.

lpDDSurfaceDesc

Address of a DDSURFACEDESC2structure that will be filled with the relevant details about the surface.

dwFlags

DDLOCK_EVENT	This flag is not currently implemented.Triggers the event when IDirectDrawSurface5::Lockcan 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_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::Unlockmethod 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_SURFACEBUSYor 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 IDirectDrawSurface5::Unlockmethod. GUI debuggers cannot operate while the Win16Mutex is held.

Requirements

Runs on	Versions	Declared in	Link to
Windows CE OS	2.12 or later. Version 2.12 requires DXPAK 1.0 or later.	ddraw.h	ddraw.lib