Herd Software Development
DaVinci Graphics Library
DaVinci Documentation

Leonardo: The ScaleToGray function

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	hDIB,
int	cxDest,
int	cyDest,
LPRECT	rc
DWORD	dummy);

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.

Example

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

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.

Remarks

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.

Memory requirements

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.

Computing speed

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.

Optimization

DaVinci Professional contains optimized routines for enhanced performance in the following special cases.

• Reduction of monochrome DIB by an exact ratio 1:2
  
  
• Reduction of a monochrome DIB by any ratio

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.