[This is preliminary documentation and subject to change.]
The SetICMMode function causes Image Color Management to be enabled, disabled, or queried on a given device context (DC).
int WINAPI SetICMMode(
HDC hDC,
int iEnableICM
);
Constant | Meaning |
---|---|
ICM_ON | Turns on color management. Turns off old-style color correction of halftones. |
ICM_OFF | Turns off color management. Turns on old-style color correction of halftones. |
ICM_QUERY | Queries the current state of color management. |
ICM_DONE_OUTSIDEDC | Turns off color management inside DC. Under Windows NT 5.0 or later, also turns off old-style color correction of halftones. Not supported under Windows 95. |
If this function succeeds, the return value is a nonzero value.
If this function fails, the return value is zero.
If ICM_QUERY is specified and the function succeeds, the nonzero value returned is ICM_ON or ICM_OFF to indicate the current mode.
If the system cannot find an ICC color profile to match the state of the device, SetICMMode fails and returns zero.
Once ICM is enabled for a device context (DC), colors passed into the DC using most Win32 API functions are color matched. The primary exceptions are BitBlt and StretchBlt. The assumption is that when performing a bit block transfer (blit) from one DC to another, the two DCs are already compatible and need no color correction. If this is not the case, color correction may be performed. Specifically, if a device independent bitmap (DIB) is used as the source for a blit, and the blit is performed into a DC that has ICM enabled, color matching will be performed. If this is not what you want, turn ICM off for the destination DC by calling SetICMMode before calling BitBlt or StretchBlt.
If the CreateCompatibleDC function is used to create a bitmap in a DC, it is possible for the bitmap to be color matched twice, once when it is created and once when a blit is performed. The reason is that a bitmap in a DC created by the CreateCompatibleDC function acquires the current brush, pens, and palette of the source DC. However, ICM will be disabled by default for the new DC. If ICM is later enabled for the new DC by using the SetICMMode function, a color correction will be done. To prevent double color corrections through the use of the CreateCompatibleDC function, use the SetICMMode function to turn ICM off for the source DC before the CreateCompatibleDC function is called.
When a compatible DC is created from a printer's DC (see CreateCompatibleDC), the default is for color matching to always be performed if it is enabled for the printer's DC. The default color profile for the printer is used when a blit is performed into the printer's DC using SetDIBitsToDevice or StretchDIBits. If this is not what you want, turn ICM off for the printer's DC by calling SetICMMode before calling SetDIBitsToDevice or StretchDIBits.
Also, when printing to a printer's DC with ICM turned on, the SetICMMode function needs to be called after every call to the StartPage function to turn back on ICM. The StartPage function calls the RestoreDC and SaveDC functions, which result in ICM being turned off for the printer's DC.
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.
Color Management Overview, ICM 2.0 Functions, BitBlt, StretchBlt, CreateCompatibleDC, SetDIBitsToDevice, StretchDIBits, StartPage