IDirectDrawSurface7::Lock method (ddraw.h)

Article
11/01/2022

Obtains a pointer to the surface memory.

Syntax

HRESULT Lock(
  [in]      LPRECT           unnamedParam1,
  [in, out] LPDDSURFACEDESC2 unnamedParam2,
  [in]      DWORD            unnamedParam3,
  [in]      HANDLE           unnamedParam4
);

Parameters

[in] unnamedParam1

A pointer to a RECT structure that identifies the region of the surface that is being locked. If this parameter is NULL, the entire surface is locked.

[in, out] unnamedParam2

A pointer to a DDSURFACEDESC2 structure that describes relevant details about the surface and that receives information about the surface.

[in] unnamedParam3

A combination of flags that determine how to lock the surface. 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 a draw operation 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 bit block transfer (bitblt) operation is in progress, Lock 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.

[in] unnamedParam4

Handle of the event. This parameter is not currently used and must be set to NULL.

Return value

If the method succeeds, the return value is DD_OK.

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

Remarks

In IDirectDrawSurface7, the default behavior of Lock is to wait for the accelerator to finish. Therefore, under default conditions, Lock never returns DDERR_WASSTILLDRAWING. If you want to see the error codes and not wait until the bitblt 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 bitblt functions to bitblt from a locked region of a surface. If you do, the bitblt 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, Lock 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

Requirement	Value
Target Platform	Windows
Header	ddraw.h
Library	Ddraw.lib
DLL	Ddraw.dll

Share via