WINCAP Windows Screen Capture Sample Application
------------------------------------------------

Wincap Version 3.10 (second version) requires Windows 3.1 to run and the
Windows 3.1 SDK to compile and build.

DESCRIPTION:
------------

WINCAP demonstrates how to capture portions of the screen, specific windows,
or the entire screen and save it to a file or print it. This sample also
defines routines that accomplish common DIB functions, and are referred to as
the DIB API. Wincap uses the DIB API functions to do most of the
capture/printing/saving work. See the file DIBAPI.TXT for a description of the
DIB api functions.

This is the second version, which adds the following:

- New API for displaying DIBs and Bitmaps
- Bug Fixes:
- Fixed calculation of bits for 15-bit display drivers
- Fixed size of output file problem (too many bytes written out)
- Checks for capabilities of display driver
- Can now capture windows with menus pulled-down
- Easier to use interface
- Uses Windows 3.1 Common Dialogs

3.1 specific features: uses new 3.1 keyboard hook functions

OVERVIEW OF TECHNIQUE
---------------------

The preferred way to capture a screen under Windows is to copy the screen
pixels into a device-independent bitmap (DIB), and then to use this DIB in
subsequent operations (for example, to save the bitmap to a file or print the
bitmap).

If a DIB is not used in the intermediate step, the results of the screen print
may be less than desirable.

By using a DIB to hold the screen image, device-dependent information is
removed from the bitmap. This simplifies the process of displaying the image
on devices with different display capabilities. For instance, capturing a
screen from a 24-bit display adapter and printing it on a 1-bit (monochrome)
printer can be done with exceptional results if DIBs are used. Additionally,
many printer drivers implement gray scale dithering; the output on these
printers is also exceptional when DIBs are used.

[Side Note: The BitBlt function should be avoided when printing bitmaps
due to the device-dependency of bitmaps. The type of bitmaps that the
BitBlt function requires are normally in the format of the display driver
rather than the printer driver. Depending on the drivers involved, the
results of using BitBlt to print a bitmap can vary from extrememly poor
output quality to no output at all.

Although all printer drivers are able to BitBlt a monochrome bitmap to
the printer, this technique normally produces poor results because the
printer cannot apply grayscaling to the image.]

This technique of using a DIB to convert a bitmap between display devices with
different capabilities can also be used to convert bitmaps while preserving
the original color information (for example, loading a 256-color bitmap from a
.BMP file and printing it to a 3-color printer or displaying it on a 24-bit
display).

SPECIFICS FOR THIS SAMPLE
-------------------------

This sample is an illustration of the following Windows techniques:

- Capturing the screen (or a specific window) into a DIB
- Capturing the screen to a Bitmap (device-dependent bitmap)
- Printing a DIB using banding
- Loading and Saving a DIB to a disk file (.BMP file)
- Converting between DIBs and DDBs
- Displaying the captured screen DDB

All of these are accomplished with calls to a simple-to-use DIB API. The DIB
API provides the following functions:

BitmapToDIB() - Creates a DIB from a bitmap
ChangeBitmapFormat() - Changes a bitmap to a specified DIB format
ChangeDIBFormat() - Changes a DIB's BPP and/or compression format
CopyScreenToBitmap() - Copies entire screen to a standard Bitmap
CopyScreenToDIB() - Copies entire screen to a DIB
CopyWindowToBitmap() - Copies a window to a standard Bitmap
CopyWindowToDIB() - Copies a window to a DIB
CreateDIBPalette() - Creates a palette from a DIB
CreateDIB() - Creates a new DIB
DestroyDIB() - Deletes DIB when finished using it
DIBError() - Displays message box with error message
DIBHeight() - Gets the DIB height
DIBNumColors() - Calculates number of colors in the DIB's color table
DIBToBitmap() - Creates a bitmap from a DIB
DIBWidth() - Gets the DIB width
FindDIBBits() - Sets pointer to the DIB bits
GetSystemPalette() - Gets the current palette
LoadDIB() - Loads a DIB from a file
PaintBitmap() - Displays standard bitmap in the specified DC
PaintDIB() - Displays DIB in the specified DC
PalEntriesOnDevice() - Gets the number of palette entries
PaletteSize() - Calculates the buffer size required by a palette
PrintDIB() - Prints the specified DIB
PrintScreen() - Prints the entire screen
PrintWindow() - Prints all or part of a window
SaveDIB() - Saves the specified dib in a file

The source code to these functions are included in this sample. You can
easily call these functions from a different application by simply compiling
the enclosed DIBAPI.DLL, and linking with the DIBAPI.LIB import library.
The file DIBAPI.TXT contains more information on the parameters/usage of
these functions. A Windows Help file for the DIB APIs is also included.

NOTE: The above DIB API were not written to support OS/2-style DIBs, although
some of the utility functions (see DIBUTIL.C) will work with either Windows or
OS/2 DIBs.

SOURCE FILE LISTING
-------------------

The following files are a part of the DIB API DLL:

copy.c - CopyWindowToDIB, CopyScreenToDIB, CopyWindowToBitmap,
CopyScreenToBitmap, PaintDIB, PaintBitmap plus
misc utility functions
dibapi.def - DEF file for DIB API DLL
dibapi.h - Header containing constants for DIB errors and
prototypes for the DIB API functions
dibapi.hlp - Windows help file containing full DIB API reference
dibapi.mak - NMAKE Makefile for DIBAPI.DLL
dibapi.rc - Resource file for DIB API DLL
dibapi.txt - Documentation for DIB API functions
dibdll.h - Constants for DLL printing dialog
dibutil.c - More DIB utility functions
dibutil.h - DIB utility constants and macros
dllinit.c - Contains LibMain for DIB API DLL
errors.c - Defines all errors which can be returned from DIB
API functions
file.c - SaveDIB, LoadDIB, and DestroyDIB
print.c - PrintDIB, PrintWindow, and PrintScreen
wepcode.c - Contains WEP for DIB API DLL

The following files are for the WINCAP sample, which uses the DIB API DLL.

dialogs.c - Contains dialog routines for dialog boxes in WINCAP
dialogs.dlg - Dialog templates for WINCAP
dialogs.h - Dialog constants for WINCAP
dlgopen.c - Contains code for "File/Save" dialog box
hook.c - Contains code for keyboard hook
makefile - NMAKE Makefile for WINCAP
wincap.c - Contains WinMain - this is the main program file for
the WINCAP sample
wincap.def - DEF file for WINCAP
wincap.h - Contains WINCAP constants
wincap.rc - Resource file for WINCAP

CREDITS:
--------

Development Team: Mark Bader
Patrick Schreiber
Garrett McAuliffe
Eric Flo
Tony Claflin
Dan Ruder

Written by Microsoft Product Support Services, Developer Support.
Copyright (c) 1991 Microsoft Corporation. All rights reserved.