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.


  LPRECT lpDestRect,
  DWORD dwFlags,
  HANDLE hEvent



Points to a RECT structure identifying the region of surface that is being locked.


Points to a DDSURFACEDESC structure to be filled in with the relevant details about the surface.


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.


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