IDirectDrawSurface::Lock (Compact 2013)
This method obtains a pointer to the surface memory.
HRESULT Lock( LPRECT lpDestRect, LPDDSURFACEDESC lpDDSurfaceDesc, DWORD dwFlags, HANDLE hEvent );
Address of a RECT structure that identifies the region of surface that is being locked. If NULL, the entire surface will be locked.
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.
The following table shows the possible flags.
Indicates that every location within the locked surface will be overwritten (with a write-only operation).
Indicates that the surface being locked will only be read.
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.
Indicates that the surface being locked will be write-enabled.
This parameter is not used and must be set to NULL.
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:
For more information on these error codes see DirectDraw Return Values.
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.