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 that will be filled with the relevant details about the surface.
dwFlags
Triggers the event when IDirectDrawSurface2::Lock can return the surface memory pointer requested. This flag is set if an event handle is being passed to IDirectDrawSurface2::Lock. If multiple locks of this type are placed on a surface, events are triggered in FIFO order.
Indicates that the surface being locked will only be read from.
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.
Typically, if a lock cannot be obtained because a blit operation is in progress, a DDERR_WASSTILLDRAWING error will be returned immediately. If this flag is set, however, IDirectDrawSurface2::Lock retries until a lock is obtained or another error, such as DDERR_SURFACEBUSY, occurs.
Indicates that the surface being locked will only be written to.
hEvent
Handle of a system event that is triggered when the surface is ready to be locked.
After the pointer is obtained, your application can access the surface memory until the corresponding IDirectDrawSurface2::Unlock method is called. After this method is called, the pointer to the surface memory is no longer valid.
Your application cannot blit from a region of a surface that is locked. If a blit is attempted on a locked surface, the blit returns either a DDERR_SURFACEBUSY or DDERR_LOCKEDSURFACES error value.
Typically, IDirectDrawSurface2::Lock returns immediately with an error when a lock cannot be obtained because a blit is in progress. You can use the DDLOCK_WAIT flag if you want the method to continue trying to obtain a lock.
To prevent display memory from being lost during access to a surface, DirectDraw holds the Win16 lock between IDirectDrawSurface2::Lock and IDirectDrawSurface2::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 stops Windows from running, so IDirectDrawSurface2::Lock/IDirectDrawSurface2::Unlock and IDirectDrawSurface2::GetDC/IDirectDrawSurface2::ReleaseDC periods should be kept short. Unfortunately, because Windows is stopped, GUI debuggers cannot be used between IDirectDrawSurface2::Lock/IDirectDrawSurface2::Unlock or IDirectDrawSurface2::GetDC/IDirectDrawSurface2::ReleaseDC operations.