Creates a dithered pattern brush based on the WinG halftone palette.
HBRUSH WinGCreateHalftoneBrush(HDC hdc, COLORREF Color, enum WING_DITHER_TYPE DitherType)
Parameters
| hdc | Specifies the DC with which the brush should be compatible. |
| Color | Specifies the color to be approximated by the brush. |
| DitherType | Specifies the dither pattern for the brush. Can be one of:
WING_DISPERSED_4x4 WING_DISPERSED_8x8 WING_CLUSTERED_4x4 |
Return Value
Returns a handle to a GDI brush if successful. Otherwise, WinGCreateHalftoneBrush returns 0.
Comments
This API is intended for simulating true color on 8-bit devices. It will create a patterned brush using colors from the halftone palette regardless of the color resolution of the target device. If hdc refers to a 24-bit device, WinGCreateHalftoneBrush will not return a solid brush of the given color, it will return a colored dither pattern using colors that appear in the halftone palette. On true-color devices, creating a solid brush that exactly matches the desired color is simple; WinGCreateHalftoneBrush lets you use the halftone patterns instead if you so desire.
A halftone brush approximates the requested Color using combinations of colors in the halftone palette. Larger dither patterns give a better approximation of the desired color but require more area to show the approximation. Quality is subjective, so programmers should experiment with different dither types to find the one that suits their needs.
If the target DC is a palette device, the WinG halftone palette must be selected into it and realized as an identity palette for correct visual results (See ClearSystemPalette). Use the WinGCreateHalftonePalette function to create a copy of the halftone palette, then select and realize it before using a halftone brush on a palette device.
The WING_DISPERSED_nxn dither types create nxn patterns that approximate Color with a dispersed dot ordered dither.
The WING_CLUSTERED_4x4 dither type creates a 4x4 pattern that approximates Color with a clustered dot ordered dither.
Always free GDI objects such as brushes by calling DeleteObject when the object is no longer needed.
Maximizing Performance
Avoid redundant creation, selection, and deletion of identical brushes as much as possible. If an application will be using the same brush repeatedly, it should create the brush once and save it for later use, deleting it when the application is complete.
Example
The CUBE sample application (in the SAMPLES\CUBE directory of the WinG Development Kit) allows the user to select the dither type for creating shaded brushes and provides a good experiment in using the different dither types.
See Also
WinGCreateHalftonePalette WING_DITHER_TYPE CreateDIBPatternBrush CreateSolidBrush Halftoning With WinG Using GDI With WinGDCs Code Samples