| Microsoft DirectX 9.0 |
The Lock method obtains a valid pointer to the surface memory. DirectDraw relies on the application calling Unlock. It is illegal behavior to Blt from a region of a surface that is locked.
An application should call the Lock method with a RECT structure specifying the rectangle on the surface that the application wants access to. If the application calls Lock with a NULL RECT then the application is assumed to be requesting exclusive access to the entire piece of surface memory.
The Lock method fills in a DDSURFACEDESC structure with the information needed by the application to access the surface memory. This information includes the stride (or pitch) and the pixel format of the surface if it is different from the pixel format of the primary surface. The DDSURFACEDESC structure also contains a pointer to the surface memory. Since it is possible to call Lock multiple times for the same Surface with different destination rectangles, this pointer is used to tie the Lock and Unlock calls together.
Normally, Lock will return immediately with an error when a lock cannot be obtained because a blit is in progress. The DDLOCK_WAIT flag can be used to alter this behavior.
In order to prevent VRAM from being lost during access to a surface, DirectDraw holds the Win16 lock between Lock and Unlock operations. The Win16 lock is the critical section used to serialize access to GDI and USER. Although this technique allows direct access to video memory and prevents other applications from changing the mode during this access, it will stop Windows from running, so Lock/Unlock and GetDC/ReleaseDC periods should be kept short. Unfortunately, because Windows is stopped, GUI debuggers cannot be used in between Lock/Unlock and GetDC/ReleaseDC operations.
Syntax
HRESULT Lock(
LPRECT lpDestRect,
LPDDSURFACEDESC lpDDSurfaceDesc,
DWORD dwFlags,
HANDLE hEvent
);
Parameters
lpDestRect
Points to a RECT structure identifying the region of surface that is being locked.
lpDDSurfaceDesc
Points to a DDSURFACEDESC structure to be filled in with the relevant details about the surface.
dwFlags
One or more of the following flags.
| Value | Description |
| DDLOCK_SURFACEMEMORYPTR | The default. Set to indicate that Lock should return a valid memory pointer to the top of the specified rectangle. If no rectangle is specified then a pointer to the top of the surface is returned. |
| DDLOCK_EVENT | Set if an event handle is being passed to Lock. Lock will trigger the event when it can return the surface memory pointer requested. If multiple locks of this type are placed on a surface, events will be triggered in FIFO order. |
| DDLOCK_WAIT | Normally, if a lock cannot be obtained because a Blt is in progress, a DDERR_WASSTILLDRAWING error will be returned immediately. If this flag is set, however, Lock will retry until a lock is obtained or another error, such as DDERR_SURFACEBUSY, occurs. |
hEvent
Handle to a system event that should be triggered when the surface is ready to be locked.
Return Values
| Value | Description |
| DD_OK | The method succeeded. |
| DDERR_INVALIDPARAMS | One or more of the input parameters is invalid. |
| DDERR_INVALIDOBJECT | DirectDraw received a pointer that was an invalid DirectDraw object. |
| DDERR_SURFACEBUSY | Access to this surface is being refused because the surface is already locked by another thread. |
| DDERR_SURFACELOST | Access to this surface is being refused because the surface memory is gone. The DirectDrawSurface object representing this surface should have Restore called on it. |
| DDERR_WASSTILLDRAWING | Informs DirectDraw that the previous Blt which is transfering information to or from this Surface is incomplete. |
| DDERR_OUTOFMEMORY | DirectDraw does not have enough memory to perform the operation. |
See Also