IDirectDrawSurface::Lock

HRESULT Lock(LPRECT lpDestRect,

LPDDSURFACEDESC lpDDSurfaceDesc,

DWORD dwFlags, HANDLE hEvent);

Obtains a pointer to the surface memory.

·Returns DD_OK if successful, or one of the following error values otherwise:

lpDestRect

Address of a RECT structure that identifies the region of surface that is being locked.

lpDDSurfaceDesc

Address of a DDSURFACEDESC structure to be filled with the relevant details about the surface.

dwFlags

DDLOCK_EVENT

Triggers the event when IDirectDrawSurface::Lock can return the surface memory pointer requested. Set if an event handle is being passed to IDirectDrawSurface::Lock. If multiple locks of this type are placed on a surface, events will be triggered in FIFO order.

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

Typically, if a lock cannot be obtained because a blit is in progress, a DDERR_WASSTILLDRAWING error will be returned immediately. If this flag is set, however, IDirectDrawSurface::Lock will retry until a lock is obtained or another error, such as DDERR_SURFACEBUSY, occurs.

DDLOCK_WRITEONLY

Indicates that the surface being locked will only be written to.

hEvent

Handle to a system event that is triggered when the surface is ready to be locked.

Once the pointer is obtained, the surface memory can be accessed by your application until the corresponding the IDirectDrawSurface::Unlock method is called. Once this occurs, the pointer to the surface memory is no longer valid.

It is illegal to blit from a region of a surface that is locked. If a blit is attempted on a locked surface, the blit will return either a DDERR_SURFACEBUSY or DDERR_LOCKEDSURFACES error value.

Typically, IDirectDrawSurface::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 set to continue trying to obtain a lock.

To prevent VRAM from being lost during access to a surface, DirectDraw holds the Win16 lock between IDirectDrawSurface::Lock and IDirectDrawSurface::Unlock operations. The Win16 lock is the critical section that serializes access to GDI and USER. Although this technique allows direct access to display memory and prevents other applications from changing the mode during this access, it will stop Windows from running, so IDirectDrawSurface::Lock/IDirectDrawSurface::Unlock and IDirectDrawSurface::GetDC/IDirectDrawSurface::ReleaseDC periods should be kept short. Unfortunately, because Windows is stopped, GUI debuggers cannot be used in between IDirectDrawSurface::Lock/IDirectDrawSurface::Unlock or IDirectDrawSurface::GetDC/IDirectDrawSurface::ReleaseDC operations.