You can directly access the frame buffer or off-screen surface memory by using the IDirectDrawSurface7::Lock method. When you call this method, the lpDestRect parameter is a pointer to a RECT structure that describes the rectangle on the surface you want to access directly. To request that the entire surface be locked, set lpDestRect to NULL. Also, you can specify a RECT that covers only a portion of the surface. Providing that no two rectangles overlap, two threads or processes can simultaneously lock multiple rectangles in a surface.

The Lock method fills a DDSURFACEDESC2 structure with all the information you need to properly access the surface memory. The structure includes information about the pitch (or stride) and the pixel format of the surface, if different from the pixel format of the primary surface. When you finish accessing the surface memory, call the IDirectDrawSurface7::Unlock method to unlock it.

While you have a surface locked, you can directly manipulate the contents. The following list describes some tips for avoiding common problems with directly rendering surface memory.

• Never assume a constant display pitch. Always examine the pitch information returned by the IDirectDrawSurface7::Lock method. This pitch can vary for a number of reasons, including the location of the surface memory, the type of display card, or even the version of the DirectDraw driver. For more information, see Width vs. Pitch.
• Make certain you blit to unlocked surfaces. DirectDraw blit methods will fail, returning DDERR_SURFACEBUSY or DDERR_LOCKEDSURFACES, if called on a locked surface. Similarly, GDI blit functions fail without returning error values if called on a locked surface that exists in display memory.
• Limit your application's activity while a surface is locked. While a surface is locked, DirectDraw often holds the Win16Mutex (also known as the Win16Lock) so that gaining access to surface memory can occur safely. The Win16Mutex serializes access to GDI and USER dynamic-link libraries, shutting down Windows for the duration between the IDirectDrawSurface7::Lock and IDirectDrawSurface7::Unlock calls. The IDirectDrawSurface7::GetDC method implicitly calls Lock, and the IDirectDrawSurface7::ReleaseDC implicitly calls Unlock.
• Always copy data aligned to display memory. (Windows 95 and Windows 98 use a page fault handler, Vflatd.386, to implement a virtual flat-frame buffer for display cards with bank-switched memory. The handler allows these display devices to present a linear frame buffer to DirectDraw. Copying data unaligned to display memory can cause the system to suspend operations if the copy spans memory banks.)

Unless you include the DDLOCK_NOSYSLOCK flag when you call the Lock method, locking the surface typically causes DirectDraw to take the Win16Mutex. During the Win16Mutex all other applications, including Windows, cease execution. Since the Win16Mutex stops applications from executing, standard debuggers cannot be used while the lock is held. Kernel debuggers can be used during this period. DirectDraw always takes the Win16Mutex when locking the primary surface.

If a blit is in progress when you call IDirectDrawSurface7::Lock, the method will return immediately with an error, as a lock cannot be obtained. To prevent the error, use the DDLOCK_WAIT flag to cause the method to wait until a lock can be successfully obtained.

Locking portions of the primary surface can interfere with the display of a software cursor. If the cursor intersects the locked rectangle, it is hidden for the duration of the lock. If it doesn't intersect the rectangle, it is frozen for the duration of the lock. Neither of these effects occurs if the entire surface is locked.

You can directly access the frame buffer or off-screen surface memory by using the DirectDrawSurface7.Lock method. When you call this method, the r parameter is a RECT type that describes the rectangle on the surface you want to access directly. To request that the entire surface be locked, pass an empty RECT. Also, you can specify a RECT that covers only a portion of the surface.

The Lock method fills a DDSURFACEDESC2 type with all the information you need to properly access the surface memory. The structure includes information about the pitch (or stride) and the pixel format of the surface, if different from the pixel format of the primary surface. When you finish accessing the surface memory, call the DirectDrawSurface7.Unlock method to unlock it.

While you have a surface locked, you can directly manipulate the contents. The following list describes some tips for avoiding common problems with directly rendering surface memory.

• Never assume a constant display pitch. Always examine the pitch information returned by the DirectDrawSurface7.Lock method. This pitch can vary for a number of reasons, including the location of the surface memory, the type of display card, or even the version of the DirectDraw driver. For more information, see Width vs. Pitch.
• Make certain you blit to unlocked surfaces. DirectDraw blit methods will fail, raising DDERR_SURFACEBUSY or DDERR_LOCKEDSURFACES, if called on a locked surface. Similarly, GDI blit functions fail without returning error values if called on a locked surface that exists in display memory.
• Limit your application's activity while a surface is locked. While a surface is locked, DirectDraw often holds the Win16Mutex (also known as the Win16Lock) so that gaining access to surface memory can occur safely. The Win16Mutex serializes access to GDI and USER dynamic-link libraries, shutting down Windows for the duration between the DirectDrawSurface7.Lock and DirectDrawSurface7.Unlock calls. The DirectDrawSurface7.GetDC method implicitly calls Lock, and the DirectDrawSurface7.ReleaseDC implicitly calls Unlock.
• Always copy data aligned to display memory. (Windows 95 and Windows 98 use a page fault handler, Vflatd.386, to implement a virtual flat-frame buffer for display cards with bank-switched memory. The handler allows these display devices to present a linear frame buffer to DirectDraw. Copying data unaligned to display memory can cause the system to suspend operations if the copy spans memory banks.)

Unless you include the DDLOCK_NOSYSLOCK flag when you call the Lock method, locking the surface typically causes DirectDraw to take the Win16Mutex. During the Win16Mutex all other applications, including Windows, cease execution. Since the Win16Mutex stops applications from executing, standard debuggers cannot be used while the lock is held. Kernel debuggers can be used during this period. DirectDraw always takes the Win16Mutex when locking the primary surface.

If a blit is in progress when you call DirectDrawSurface7.Lock, the method will return immediately with an error, as a lock cannot be obtained. To prevent the error, use the DDLOCK_WAIT flag to cause the method to wait until a lock can be successfully obtained.

Locking portions of the primary surface can interfere with the display of a software cursor. If the cursor intersects the locked rectangle, it is hidden for the duration of the lock. If it doesn't intersect the rectangle, it is frozen for the duration of the lock. Neither of these effects occurs if the entire surface is locked.