The IDirectDrawSurface3::Lock 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
| DDLOCK_EVENT | ||
| This flag is not currently implemented. | ||
| DDLOCK_NOSYSLOCK | ||
| If possible, do not take the Win16Lock. This flag is ignored when locking the primary surface. | ||
| DDLOCK_READONLY | ||
| Indicates that the surface being locked will only be read from. | ||
| 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 blit operation is in progress, the method retries until a lock is obtained or another error occurs, such as DDERR_SURFACEBUSY. | ||
| DDLOCK_WRITEONLY | ||
| Indicates that the surface being locked will only be written to. | ||
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 the Frame-Buffer Directly.
After retrieving a surface memory pointer, you can access the surface memory until a corresponding IDirectDrawSurface3::Unlock method is called. When the surface is unlocked, the pointer to 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. Additionally, GDI blit functions will silently fail when used on a locked video memory surface.
This method often causes DirectDraw to hold the Win16Lock until you call the IDirectDrawSurface3::Unlock method. GUI debuggers cannot operate while the Win16Lock is held.
QuickInfo
Windows NT: Use version 5.0 or later.
Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.
See Also
IDirectDrawSurface3::Unlock, IDirectDrawSurface3::GetDC, IDirectDrawSurface3::ReleaseDC