DOCUMENT:Q92533  03-NOV-1999  [win16ddk]
TITLE   :Implementing Display Driver Device Bitmaps
PRODUCT :Microsoft Windows Device Driver Kit
PROD/VER::3.1,3.11
OPER/SYS:
KEYWORDS:

======================================================================
-------------------------------------------------------------------------------
The information in this article applies to:

 - Microsoft Windows Device Development Kit (DDK) for Windows, versions 3.1, 3.11 
-------------------------------------------------------------------------------

SUMMARY
=======

The "Microsoft Windows 3.1 Device Driver Kit: Device Driver Adaptation Guide"
(DDAG) documentation on implementing display driver Device Bitmaps is
inconsistent between chapters 2 and 10.

Chapter 10 information for RealizeObject states that you can fail the call to
realize a device bitmap (i.e. when the wStyle parameter is OBJ_PBITMAP). This
information appears to conflict with that found in chapter 2, section 2.1.14.
The information in chapter 2 is correct, and is more specific to display
drivers.

MORE INFORMATION
================

If you implement Device Bitmaps, you can not fail any calls to SelectBitmap(),
BitmapBits(), or RealizeObject(). If you can't find room in off-screen video
memory, you must allocate main system memory with GlobalAlloc().

You can use SelectBitmap as the place to lock-down your huge bitmaps that won't
fit off-screen. However, these bitmaps won't always be selected prior to
MemoryDIBBits() or BitmapBits() (these are the places where the bitmap is passed
through GDI directly rather than indirectly via DCs). Furthermore, bitmaps may
be selected multiple times without being deselected. Additionally, a bitmap may
be freed while it is still selected.

According to the DDK documentation, GDI will leave you to manage your PBITMAP and
its header if the first word is non-zero. (The PBITMAP must still be implemented
as documented on page 504 of the 3.1 DDK DDAG.) There are at least two cases
where this is not true: GDI will periodically overwrite the dword at the bmBits
offset (with seg:0020) and it may also overwrite the bmlpPDevice field. Some
driver developers have used the "reserved" structure members of the PBITMAP to
store the information that should be in the overwritten fields, thus avoiding
the overwrite problem (this does however create version dependence.)

There is also a small memory leak which may be specific to device bitmaps: GDI
will create a bitmap to hold a copy of the bits passed into
CreatePatternBrush(), but it will never free the copy. Excel makes a lot of
these calls when it draws charts, resulting in a pile of orphaned 8x8 brush
copies (which will eventually exhaust GDI's heap!)

Because of these problems, we recommend that Device Bitmaps be implemented as a
SYSTEM.INI option, allowing users to turn them off if they determine Device
Bitmaps are causing problems.

Additional query words: 3.10 3.11

======================================================================
Keywords          :  
Technology        : kbAudDeveloper kbWin3xSearch kbWinDDKSearch kbWinDDK310 kbWinDDK311
Version           : :3.1,3.11

=============================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS
PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.  MICROSOFT DISCLAIMS
ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO
EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR
ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL,
CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF
MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.  SOME STATES DO NOT ALLOW THE EXCLUSION
OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES
SO THE FOREGOING LIMITATION MAY NOT APPLY.

Copyright Microsoft Corporation 1999.