IDirectDrawSurface::Lock (Compact 2013)

  • Article

3/26/2014

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.

    You need to initialize this structure's dwSize member to the size, in bytes, of the structure prior to the call. No other preparation is required.

  • 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

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.

Requirements

Header

ddraw.h

Library

ddraw.lib

See Also

Reference

IDirectDrawSurface
DirectDraw Reference
DirectDraw Interfaces
IDirectDrawSurface::Unlock
IDirectDrawSurface::GetDC
IDirectDrawSurface::ReleaseDC

Other Resources

DirectDraw