Platform SDK: DirectX

DirectDrawSurface7.Lock

The DirectDrawSurface7.Lock method obtains the surface memory.

object.Lock( _ 
    r As RECT, _ 
    desc As DDSURFACEDESC2, _ 
    flags As CONST_DDLOCKFLAGS, _
    hnd As Long)

Parameters

object
Object expression that resolves to a DirectDrawSurface7 object.
r
RECT type that defines the upper-left and lower-right points of the rectangle that identifies the region of surface that is being locked. If this is an empty RECT, the entire surface is locked.
desc
DDSURFACEDESC2 type to be filled with the relevant details about the surface.
flags
One or more of the constants of the CONST_DDLOCKFLAGS enumeration that describes the type of lock to be performed.
hnd
Not used and must be set to 0.

Error Codes

If the method fails, it raises an error, and Err.Number can be set to one of the following 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 the surface memory, you can access the surface memory until a corresponding DirectDrawSurface7.Unlock method is called. When the surface is unlocked, 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. GDI blit functions also silently fail when used on a locked video-memory surface.

This method often causes DirectDraw to hold the Win16Mutex (also known as Win16Lock) until you call the DirectDrawSurface7.Unlock method. GUI debuggers cannot operate while the Win16Mutex is held.

See Also

DirectDrawSurface7.Unlock, DirectDrawSurface7.GetDC, DirectDrawSurface7.ReleaseDC