Platforms to show: All Mac Windows Linux Cross-Platform

Back to WindowsICMTransformMBS class.

WindowsICMTransformMBS.CheckColors(InputColors() as WindowsICMColorMBS, ctInput as Integer, Results() as Integer) as boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows ICM MBS Win Plugin 11.1 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
The CheckColors function determines whether the colors in an array lie within the output gamut of a specified transform.

InputColors: an array of colors.
ctInput: Specifies the input color type.
Results: An array of nColors bytes that receives the results of the test.

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

If the input color type is not compatible with the color transform, CheckColors fails.

The function places results of the tests in the array pointed to by paResult. Each byte in the array corresponds to a COLOR element in the array pointed to by paInputColors and has an unsigned value between 0 and 255. The value 0 denotes that the color is in gamut, while a nonzero value denotes that it is out of gamut. For any integer n such that 0 < n < 255, a result value of n+1 indicates that the corresponding color is at least as far out of gamut as would be indicated by a result value of n.

The out-of-gamut information in the gamut tags created in WCS use the perceptual color distance in CIECAM02, which is the mean square root in CIECAM02 Jab space. The distance in the legacy ICC profile gamut tags is the mean square root in CIELAB space. We recommend that you use the CIECAM02 space when it is available because it provides more perceptually accurate distance metrics.

WindowsICMTransformMBS.Constructor(LogColorSpace as WindowsICMLogColorSpaceMBS, DestProfile as WindowsICMProfileMBS, TargetProfile as WindowsICMProfileMBS, Flags as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows ICM MBS Win Plugin 11.1 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
The CreateColorTransform function creates a color transform that applications can use to perform color management.

LogColorSpace: The input colorspace.

DestProfile: The profile of the destination device. The function determines whether the profile contains International Color Consortium (ICC) or Windows Color System (WCS) profile information.

TargetProfile: The profile of the target device. The function determines whether the profile contains ICC or WCS profile information.

Flags: Specifies flags to used control creation of the transform. See Remarks.

On success the handle property is not zero.

If the target profile is nil, 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 Flags 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:

PRESERVEBLACKIf 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_TRANSFORMIf 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_ALWAYSIf this bit is set, even all-ICC transforms will use the WCS code path.

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

See also:

WindowsICMTransformMBS.Constructor(Profiles() as WindowsICMProfileMBS, Intents() as Integer, Flags as Integer, indexPreferredCMM as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows ICM MBS Win Plugin 11.1 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
The CreateMultiProfileTransform function accepts an array of profiles or a single device link profile and creates a color transform that applications can use to perform color mapping.

Profiles: An array of profiles to be used. The function determines whether the HPROFILEs contain International Color Consortium (ICC) or Windows Color System (WCS) profile information and processes them appropriately. When valid WCS profiles are returned by OpenColorProfile, these profiles contain the combination of DMP, CAMP, and GMMP profiles.
Intent: An array of intents to use. Each intent is one of the following values:

INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

GMMPs are a generalization of intents. There are two possible sources of intents: the "destination" profile and the intent list parameter to CreateMultiProfileTransform. The term "destination" is not used since all but two of the profiles in the profile list parameter will serve as first destination and then source.

For more information, see Rendering Intents.

nIntents
Specifies the number of elements in the intents array: can either be 1 or the same value as nProfiles. For profile arrays that contain any WCS profiles, the first rendering intent is ignored and only nProfiles -1 elements are used for these profile arrays. The maximum number of nIntents is 10.

Flags: Specifies flags used to control creation of the transform.

indexPreferredCMM: Specifies the one-based index of the color profile that indicates what color management module (CMM) to use. The application developer may allow Windows to choose the CMM by setting this parameter to INDEX_DONT_CARE. See Using Color Management Modules (CMM) Third party CMMs are only available for ICC workflows. Profile arrays containing WCS profiles will ignore this flag. It is also ignored when only ICC profiles are used and when the WCS_ALWAYS flag is used.

On success the handle property is not zero.

If a device link profile is being used, the function will fail if Profiles contains more than one value.

The array of intents specifies how profiles should be combined. The nth intent is used for combining the nth profile in the array. If only one intent is specified, it is used for the first profile, and all other profiles are combined using Match intent.

The values in Flags 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:

PRESERVEBLACKIf 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_TRANSFORMIf 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_ALWAYSIf this bit is set, even all-ICC transforms will use the WCS code path.

For details, see CMM Transform Creation Flags. All of the flags mentioned there are supported for all types of transforms, except for FAST_TRANSLATE and USE_RELATIVE_COLORIMETRIC, which only work in a pure ICC-to-ICC transform.

The CreateMultiProfileTransform 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.

We recommend that there be only one GMMP between a source and destination DMP. Gamut boundary descriptions (GBDs) are created from the DMP/CAMP combinations. The subsequent GMMPs use the GDBs prior to them in the processing chain until there exists a DMP/CAMP GBD next in the sequence to be used. For example, assume a sequence DMP1, CAMP1, GMMP1, GMMP2, GMMP3, DMP2, CAMP2, GMMP4, GMMP5, CAMP3, DMP3. Then GMMP1, GMMP2 use GBD1 as their source and destination. Then GMMP3 uses GBD1 as source and GBD2 as destination. Then GMMP4 uses GBD2 as source and destination. Finally GMMP5 uses GBD2 as source and GBD3 as destination. This assumes no GMMP is identical to one next to it.

For WCS profiles, we recommend that the rendering intents be set to DWORD_MAX in order to use the GMMP within the WCS profile handle. This is because the array of rendering intents takes precedence over the rendering intents or gamut mapping models specified or contained in the profiles specified by the PROFILEs. The array of rendering intents references the default GMMP for those rendering intents. Ideally, only one gamut mapping is performed between a source and destination device by setting one or the other GMMP to NULL when creating the HPROFILE with WCS profile information. Any legacy application that uses a WCS DMP will invoke a sequence of GMMPs. GDBs are chosen based on DMPs and CAMPs. For intermediate GMMP gamut boundaries, the source and destination GBDs are used.

In summary, if ubound(Intents)=0, then the first GMM is set based on the GMMP that is set as default* for the padwIntent value, unless that value is DWORD_MAX, in which case the embedded GMM information from the second profile is used (The embedded GMM information is either a GMMP or, in the case of an ICC profile, the baseline GMM corresponding to** the intent from the profile header). The remainder of the GMMs are set based on the GMMP that is set as default* for RelativeColorimetric.

If ubound(Intents) = ubound(Profiles) - 1, then each GMM is set based on the GMMP that is set as default* for the value in the padwIntent array at the corresponding index, except where padwIntent values are DWORD_MAX. For values in the padwIntent array that are DWORD_MAX, the GMMs at corresponding positions are set based on the embedded GMM information from the second of the two profiles whose gamuts are mapped by the GMM. (Again, the embedded GMM information is either a GMMP or, in the case of an ICC profile, the baseline GMM corresponding to** the intent from the profile header).

If ubound(Intents) = ubound(Profiles), then first intent is ignored and funtion behaves as it does in the case when ubound(Intents) = ubound(Profiles) - 1.

Any other combination of padwIntents and nIntents will return an error.

  • "set as default" means that the default GMMP is queried using WcsGetDefaultColorProfile with its profileManagementScope parameter set to WCS_PROFILE_MANAGEMENT_SCOPE_CURRENT_USER. This may return either current-user or system-wide defaults as described in the documentation for WcsGetDefaultColorProfile.

  • "GMM corresponding to" does not mean "GMM from the GMMP set as default for". Instead it means "a constant association between ICC profile intents and baseline GMM algorithms."

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

See also:

WindowsICMTransformMBS.GetCMMInfo(what as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows ICM MBS Win Plugin 11.1 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
The GetCMMInfo function retrieves various information about the color management module (CMM) that created the specified color transform.

what: Specifies the information to be retrieved. This parameter can take one of the following constant values.

ValueMeaning
CMM_WIN_VERSIONRetrieves the version of Windows targeted by the color management module (CMM).
CMM_DLL_VERSIONRetrieves the version number of the CMM.
CMM_IDENTRetrieves the CMM signature registered with the International Color Consortium (ICC).

If this function succeeds, the return value is the information specified in What.
If this function fails, the return value is zero.

WindowsICMTransformMBS.TranslateBitmapBits(SrcBits as memoryblock, InputType as Integer, Width as Integer, Height as Integer, InputRowBytes as Integer, DestBits as memoryblock, DestType as Integer, DestRowBytes as Integer) as boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows ICM MBS Win Plugin 11.1 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
The TranslateBitmapBits function translates the colors of a bitmap having a defined format so as to produce another bitmap in a requested format.

SrcBits: Pointer to the bitmap to translate.
InputType: Specifies the format of the input bitmap. Use one of the BM_* constants.
Width: Specifies the number of pixels per scan line in the input bitmap.
Height: Specifies the number of scan lines in the input bitmap.
InputRowBytes: Specifies the number of bytes from the beginning of one scan line to the beginning of the next in the input bitmap; if set to zero, the function assumes that scan lines are padded so as to be DWORD-aligned.
DestBits: Pointer to the buffer in which to place the translated bitmap.
DestType: Specifies the format of the output bitmap. Use one of the BM_* constants.
DestRowBytes: Specifies the number of bytes from the beginning of one scan line to the beginning of the next in the output bitmap; if set to zero, the function assumes that scan lines should be padded to be DWORD-aligned.

If this function succeeds, the return value is TRUE.
If this function fails, the return value is FALSE.

Remarks

If the input and output formats are not compatible with the color transform, this function fails.

When either of the floating point BMFORMATs, BM_32b_scARGB or BM_32b_scRGB are used, the color data being translated should not contain NaN or infinity. NaN and infinity are not considered to represent legitimate color component values, and the result of translating pixels containing NaN or infinity is meaningless in color terms. NaN or infinity values in the color data being processed will be handled silently, and an error will not be returned.

WindowsICMTransformMBS.TranslateColors(InputColors() as WindowsICMColorMBS, ctInput as Integer, OutputColors() as WindowsICMColorMBS, ctOutput as Integer) as boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows ICM MBS Win Plugin 11.1 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
The TranslateColors function translates an array of colors from the source color space to the destination color space as defined by a color transform.

InputColors: The input color.
ctInput: Specifies the input color type.
OutputColors: The output color.
ctOutput: Specifies the output color type.

Returns true on success and false on failure.

Some examples using this method:

WindowsICMTransformMBS.TranslatePictures(InputPicture as picture, OutputPicture as picture) as boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Windows ICM MBS Win Plugin 11.1 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
The TranslateBitmapBits function translates the colors of a bitmap having a defined format so as to produce another bitmap in a requested format.

InputPicture: input picture
OutputPicture: output picture

If this function succeeds, the return value is TRUE.
If this function fails, the return value is FALSE.

Make sure the pictures have the same size.

If the input and output formats are not compatible with the color transform, this function fails.

Some examples using this method:

The items on this page are in the following plugins: MBS Win Plugin.


The biggest plugin in space...