IDirectDrawSurface::Lock
This method obtains a pointer to the surface memory.
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 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_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 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 reurn DDERR_SURFACEBUSY.
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. Additionally, GDI blit functions will silently fail when used on a locked video memory surface.
Requirements
Pocket PC: Windows Mobile 5.0 and later
Smartphone: Windows Mobile 5.0 and later
OS Versions: Windows CE 5.01 and later
Header: Ddraw.h.
Library: Ddraw.lib.
See Also
IDirectDrawSurface::Unlock | IDirectDrawSurface::GetDC | IDirectDrawSurface::ReleaseDC
Send Feedback on this topic to the authors