IDirectDrawSurface::Lock

Artigo
11/18/2015

A version of this page is also available for

4/8/2010

This method obtains a pointer to the surface memory.

Syntax

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
The following table shows the possible flags.

Flag	Description
DDLOCK_DISCARD	Indicates that every location within the locked surface will be overwritten (with a write-only operation).
DDLOCK_READONLY	Indicates that the surface being locked will only be read.
DDLOCK_WAITNOTBUSY	Waits for a previously initiated drawing operation to complete instead of returning immediately with the DDERR_WASSTILLDRAWING return value. If a previous drawing operation is in progress at the time of the call, this flag defers returning from the call until the surface is locked or an error occurs.
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 Value

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

For more information on these error codes see DirectDraw Return 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 IDirectDrawSurface::Unlock method is called. When the surface is unlocked, the pointer to the surface memory is invalid.

In a change from previous versions of DirectDraw, only one rectangle can be locked per surface, either the entire surface or a subset of the surface. If you try to lock a second section of the surface, the method will return DirectDraw Return Values.

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

Sample Code

An example showing the use of this function can be found in the topic How to use DirectDraw.

Requirements

Header	ddraw.h
Library	ddraw.lib
Windows Embedded CE	Windows Embedded CE 6.0 and later
Windows Mobile	Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later

Compartilhar via