Herd Software Development
DaVinci Graphics Library
While the name seems to point to its suitability for generating grayscaled images, this function is far from limited to grayscaling and can be used to output color images. It resembles StretchDIB in its parameters and application, and is recommended for use where high-quality downscaling is desired (e.g. resizing of screenshots for documentation purposes). See remarks for more information.
HDIB FAR PASCAL ScaleToGray(
hDIB Handle of a source DIB at 1, 4, 8, 16, 24 or 32 bit color depth.
The handle of the source DIB remains valid after this operation.
cxDest Width of the new DIB in pixels, must be >0.
cyDest Height of the new DIB in pixels; must be >0.
rc Pointer to a RECT structure specifying the bounding rectangle of the area of the source DIB to be copied. This value can be NULL if the input DIB is to be copied as a whole.
To create a mirror image of the original, specify the bounding rectangle as left>right and bottom>top.
dummy Reserved for future functionality.
The following example demonstrates ScaleToGray's ability to enhance the quality of reduced images.
|Image processed by StretchDIB using a ratio of 1:3||Same image processed by ScaleToGray using a ratio of 1:3|
Returns the handle of the newly created DIB if successful, or NULL if the function fails. The handle must be released by the application using GlobalFree.
If the original DIB was monochrom, the output DIB will always have a color resolution of 8 bits (biBitCount =1) and its palette will consist of grayscales. All other resolutions will return TrueColor (24 bit) dibs.
The original purpose of this function is for reduction of monochrome bitmaps to fit the screen, hence the function's name, but it has applicability far beyond this. While StretchDIB reduces images by discarding pixel color data during the reduction, ScaleToGray generates a mean color value for all pixels, resulting in a much more visually pleasing image in most cases, even using high reduction ratios. Output quality can often be further improved by sharpening the resulting image using CreateSharpenedDIB. This additional sharpening is particularly effective with reductions of line art and sharply outlined images such as screen captures of Windows dialogs.
ScaleToGray requires little memory for its own purposes. Memory requirements for the function are determined primarily by the sizes of the input and output DIBs.
DIBs at 1 bit color depth can be processed directly. However, the output DIB will have 8 bit color depth, so memory requirements will rise if the reduction is correspondingly small. As an example, a 640x480 DIN A4 monochrome fax image at VGA resolution will require approx. 800 KByte.
Since ScaleToGray calculates a value for every pixel of the source bitmap at least once, processing is relatively slow. You should use the functions StretchDIB or the Windows function StrechBlt if rapid processing is required.
DaVinci Professional contains optimized routines for enhanced performance in the following special cases.
Note that if a monochrome bitmap reduction is not 1:2, qualifying it for the first optimized routine, ScaleToGray falls back to the second optimized routine for general-purpose monochrome reduction.