CreateColorTransform
The CreateColorTransform function creates a color transform that applications can use to perform color management.
HTRANSFORM WINAPI CreateColorTransform(
LPLOGCOLORSPACE pLogColorSpace, HPROFILE hDestProfile, HPROFILE hTargetProfile, DWORD dwFlags);
Parameters
- pLogColorSpace
Pointer to the input LOGCOLORSPACE. - hDestProfile
Handle to the profile of the destination device. The function determines whether the HPROFILE contains International Color Consortium (ICC) or Windows Color System (WCS) profile information. - hTargetProfile
Handle to the profile of the target device. The function determines whether the HPROFILE contains ICC or WCS profile information. - dwFlags
Specifies flags to used control creation of the transform. See Remarks.
Return Values
If this function succeeds, the return value is a handle to the color transform.
If this function fails, the return value is NULL. For extended error information, call GetLastError.
Remarks
If the target profile is NULL, the transform goes from the source logical color space to the destination profile. If the target profile is given, the transform goes from the source logical color space to the target profile and then to the destination profile. This allows previewing output meant for the target device on the destination device.
The values in dwFlags are intended as hints only. The color management module must determine the best way to use them.
Windows Vista: Three new flags have been added that can be used with dwFlags:
| PRESERVEBLACK | If this bit is set, the transform engine inserts the appropriate black generation GMMP as the last GMMP in the transform sequence. This flag only works in a pure WCS transform. |
| SEQUENTIAL_TRANSFORM | If this bit is set, each step in the WCS processing pipeline is performed for every pixel in the image and no optimized color transform is built. This flag only works in a pure WCS transform.
Restrictions: A transform created with the SEQUENTIAL_TRANSFORM flag set may only be used in the thread on which it was created and only for one color translation call at a time. COM must be initialized prior to creating the sequential transform and must remain initialized for the lifetime of the transform object. |
| WCS_ALWAYS | If this bit is set, even all-ICC transforms will use the WCS code path. |
Note: SEQUENTIAL_TRANSFORM was inadvertently omitted from the icm.h header in the Windows Vista SDK. If you wish to use the SEQUENTIAL_TRANSFORM flag, define it in your application as follows:
#define SEQUENTIAL_TRANSFORM 0x80800000
For details, see CMM Transform Creation Flags. All of the flags mentioned there are supported for all types of transforms, except for FAST_TRANSLATE, which only works in a pure ICC-to-ICC transform.
The CreateColorTransform function is used outside of a device context. Colors may shift when transforming from a color profile to the same color profile. This is due to precision errors. Therefore, a color transform should not be performed under these circumstances.
The B2Ax tags are required for any profile that is the target of a transform.
WCS transform support for ICC ColorSpace profiles is limited to RGB colorspace profiles. The following ICC profile types cannot be used in a CITE-processed transform, either a mixed WCS/ICC transform or an all-ICC transform with WCS_ALWAYS set:
- Non-RGB ColorSpace profiles
- NamedColor profiles
- n-channel profiles (where n > 8)
- DeviceLink profiles
- Abstract profiles
Requirements
** Windows Vista:** Support for WCS profiles included in Windows Vista and later.
** Windows NT/2000/XP:** Support for ICC profiles included in Windows 2000 and later.
** Windows 95/98/Me:** Support for ICC profiles included in Windows 98 and later.
** Header:** Declared in Icm.h.
** Library:** Use Mscms.lib.
** Unicode:** Implemented as Unicode and ANSI versions on Windows 2000/XP/Vista.