AIOverrideColorConversionSuite Struct Reference
[API Suite List]

This suite provides functions that allow you to manage color profiles and perform color conversions between profiles. More...

#include <AIOverrideColorConversion.h>

List of all members.

Public Attributes
AIAPI AIErr(*	GamutRGBToCMYKImage )(void srcBuf, const ASUInt32 numSamples, const ASUInt32 rgbFormat, ASBoolean inGamut)
	Converts RGB image samples into CMYK to determine if any of the samples were out of gamut.
AIAPI AIErr(*	CreateXform )(const AIColorProfile srcProfile, const AIColorProfile destProfile, ai::uintptr *xform)
	Creates a transformation from one profile to another, using the render intent set in the Color Settings dialog.
AIAPI void(*	FreeXform )(const ai::uintptr xform)
	Frees memory for a transformation when it is no longer needed.
AIAPI AIErr(*	ApplyXformSample )(const ai::uintptr xform, ASFixed inColor, ASFixed outColor, const InternalColorTransformType convType, ASBoolean isLAB)
	Applies a transformation to a single color value.
AIAPI AIErr(*	ApplyXformImage )(const ai::uintptr xform, void inBuffer, void outBuffer, const ASUInt32 numPixels, const InternalColorTransformType convType, ASBoolean isLAB, ASInt16 format)
	Applies a transformation to a buffer of image data.
AIAPI AIErr(*	CreateProfileFromTag )(void buffer, const ASUInt32 size, AIColorProfile profile)
	Converts an ICC tag into a color profile.
AIAPI AIErr(*	GetWSProfile )(const ASUInt32 whichProfile, AIColorProfile *profile)
	Creates a current working color profile.
AIAPI void(*	FreeProfile )(AIColorProfile profile)
	Frees the memory associated with a color profile that is no longer needed.
AIAPI ASUInt32(*	GetOpenPolicy )(AIColorProfile *profile, ASUInt32 colorModel, ASBoolean isLink, ASBoolean linkHasMultipleProfiles)
	Retrieves the current color management policy for how to treat color profiles when opening documents.
AIAPI void(*	GetSavePolicy )(const ASUInt32 whichSpace, ASUInt32 policy, ASUInt32 defaultState, ai::UnicodeString &profName)
	Retrieves the current color management policy for how to treat color profiles when saving documents; that is, which profile, if any, should be saved with the document.
AIAPI AIErr(*	GetProfileData )(const AIColorProfile profile, ASUInt32 size, void data)
	Retrieves the tag data for a color profile.
AIAPI AIErr(*	GetProfileName )(const AIColorProfile profile, ai::UnicodeString &profileName)
	Retrieves the description name of a color profile.
AIAPI AIErr(*	CreateInternalTransform )(const InternalColorTransformType whichOne, AIColorProfile scrProfile, AIColorProfile destProfile)
	Creates and caches transforms to be used for all internal color conversions and those performed with the `AIColorConversionSuite`.
AIAPI void(*	FreeAllInternalTransforms )(void)
	Frees memory for all cached transforms.
AIAPI void(*	ProfsEqual )(const AIColorProfile srcProfile, const AIColorProfile destProfile, ASUInt32 *match)
	Reports whether two profiles are the same.
AIAPI void(*	GetInternalTransform )(const InternalColorTransformType whichOne, ai::uintptr *xform)
	Retrieves a transform created by `CreateInternalTransform()`, to use with `ApplyXformSample()` or `ApplyXformImage()`.
AIAPI void(*	BPCOn )(void)
	Turns on Black Point Compensation for all subsequent color transform operations.
AIAPI void(*	RestoreBPC )(void)
	Restores the previous Black Point Compensation setting, after using `BPCOn()`.
AIAPI AIErr(*	MakeProfileFromCalGray )(AIGrayCal grayCal, AIColorProfile profile)
	Constructs a color profile from grayscale calibration information.
AIAPI AIErr(*	MakeProfileFromCalRGB )(AIRGBCal rgbCal, AIColorProfile profile)
	Constructs a color profile from RGB calibration information.
AIAPI AIErr(*	MakeProfileFromCalCMYK )(AICMYKCal cmykCal, AIColorProfile profile)
	Constructs a color profile from CMYK calibration information.
AIAPI AIErr(*	CreateInternalTransform_16Bit )(const InternalColorTransformType whichOne, AIColorProfile srcProfile, AIColorProfile dstProfile, ASUInt8 bitDepth, JPXLabParams jpxLabParams)
	Creates and caches transforms to be used for all internal color conversions and those performed with the `AIColorConversionSuite`.
AIAPI void(*	GetColorSettingsPolicies )(ASBoolean AI6Mode, ColorConvPolicy rgbPolicy, ColorConvPolicy *cmykPolicy)
	Retrieves the color conversion policies and the AI6 mode from the Color Settings dialog.
AIAPI AIRenderingIntent(*	GetColorSettingsRenderIntent )(void)
	Retrieves the render intent from the Color Settings dialog (Note that this function returns a constant value, not an error code.
AIAPI AIBoolean(*	IsBPCOn )()
	Reports whether Black Point Compensation is currently enabled.

Detailed Description

This suite provides functions that allow you to manage color profiles and perform color conversions between profiles.

Typically, you will use CreateInternalTransform() for a source and destination colorspace. After calling AIColorConversionSuite functions with those colorspaces, use FreeAllInternalTransforms() to free the transform memory.

For example, to do a calibrated CMYK to RGB conversion of a single sample:

	CreateInternalTransform(CMYK2RGB, cmykProfile, rgbProfile)
	AIColorConversionSuite::ConvertSampleColor(kAICMYKColorSpace, cmykSample, kAIRGBColorSpace, rgbSample)
	FreeAllInternalTransforms()

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIOverrideColorConversionSuite and kAIOverrideColorConversionVersion.

Member Data Documentation

AIAPI AIErr( * AIOverrideColorConversionSuite::ApplyXformImage)(const ai::uintptr xform, void *inBuffer, void *outBuffer, const ASUInt32 numPixels, const InternalColorTransformType convType, ASBoolean isLAB, ASInt16 format)

Applies a transformation to a buffer of image data.

Parameters:

	xform	The transformation, as created with `CreateXform()`.
	inBuffer	A pointer to the input image data.
	outBuffer	[out] A buffer in which to return the transformed color data.
	numPixels	The number of pixels in the input data. The output buffer must be big enough to hold this many pixels in the new format.
	convType	The type of the specified transformation..
	isLAB	Not used.
	format	The output data format to use when converting to RGB, an `AIRGBPixelFormat` value.

AIAPI AIErr( * AIOverrideColorConversionSuite::ApplyXformSample)(const ai::uintptr xform, ASFixed *inColor, ASFixed *outColor, const InternalColorTransformType convType, ASBoolean isLAB)

Applies a transformation to a single color value.

Parameters:

	xform	The transformation, as created with `CreateXform()`.
	inColor	A pointer to the color value.
	outColor	[out] A buffer in which to return the transformed color value.
	convType	The type of the specified transformation.
	isLAB	Not used.

AIAPI void( * AIOverrideColorConversionSuite::BPCOn)(void)

Turns on Black Point Compensation for all subsequent color transform operations.

This should be used for ADM drawing operations. (Note that this function does not return an error code.)

AIAPI AIErr( * AIOverrideColorConversionSuite::CreateInternalTransform)(const InternalColorTransformType whichOne, AIColorProfile scrProfile, AIColorProfile destProfile)

Creates and caches transforms to be used for all internal color conversions and those performed with the AIColorConversionSuite.

Supply the source and destination profiles for these basic color transform types:
kRGB2RGB
kRGB2CMYK
kCMYK2CMYK
kCMYK2RGB

For other 8-bit transforms to RGB, if the source profile is NULL, the profile of the top document is used, or if that is NULL, the corresponding working space. The destination profile is ignored and is set internally to sRGB.
For a transform from LAB to RGB, the source RGB data is interpreted as LAB. The source profile is ignored and is set internally to LAB. If the destination profile is NULL, the profile of the top document is used, or if that is NULL, the RGB working space.

For example, to convert a sample in the top document from RGB to sRGB:

	CreateInternalTransform(RGB2sRGB, NULL, NULL)
	ConvertSampleColor(kAIRGBColorSpace, rgbSample, kAIRGBColorSpace, sRGBSample)
	FreeAllInternalTransforms()

To convert from LAB to RGB:

	CreateInternalTransform(LAB2RGB, NULL, NULL)
	ConvertSampleColor(kAIRGBColorSpace, labSample, kAIRGBColorSpace, rgbSample)
	FreeAllInternalTransforms()

Parameters:

	whichOne	The predefined 8-bit transform type.
	srcProfile	The source color profile.
	destProfile	The destination profile.

See also:: CreateInternalTransform_16Bit()

AIAPI AIErr( * AIOverrideColorConversionSuite::CreateInternalTransform_16Bit)(const InternalColorTransformType whichOne, AIColorProfile srcProfile, AIColorProfile dstProfile, ASUInt8 *bitDepth, JPXLabParams *jpxLabParams)

Creates and caches transforms to be used for all internal color conversions and those performed with the AIColorConversionSuite.

Use when the source has more than 8 bits per channel, to a maximum of 16 bits per channel. If source has more than 16 bits, you must truncate the data to 16 bits, then use this function.

Parameters:

	whichOne	The predefined 16-bit transform type.
	srcProfile	The source 16-bit color profile. For `kCIELab_16Bit2RGB` color conversion only, can be an 8-bit or 16-bit profile.
	dstProfile	The destination profile.
	bitDepth	An array the size of the number of channels, with the bit depth of each channel.
	jpxLabParams	For `kCIELab_16Bit2RGB` color conversion only, additional parameters required for LAB conversion. `NULL` for other transform types.

See also:: CreateInternalTransform()

AIAPI AIErr( * AIOverrideColorConversionSuite::CreateProfileFromTag)(void *buffer, const ASUInt32 size, AIColorProfile *profile)

Converts an ICC tag into a color profile.

When you create a profile this way, you must free it with FreeProfile() when you no longer need it.

Parameters:

	buffer	The buffer containing the raw ICC tag data.
	size	The number of bytes in the input buffer.
	profile	[out] A buffer in which to return the color profile object.

AIAPI AIErr( * AIOverrideColorConversionSuite::CreateXform)(const AIColorProfile srcProfile, const AIColorProfile destProfile, ai::uintptr *xform)

Creates a transformation from one profile to another, using the render intent set in the Color Settings dialog.

Parameters:

	srcProfile	The source color profile.
	destProfile	The destination profile.
	xform	[out] A buffer in which to return the transformation. Free the memory with `FreeXform()` when it is no longer needed.

See also:: CreateProfileFromTag()

AIAPI void( * AIOverrideColorConversionSuite::FreeAllInternalTransforms)(void)

Frees memory for all cached transforms.

Subsequent color conversion is done using the default transformation. (Note that this function does not return an error code.)

AIAPI void( * AIOverrideColorConversionSuite::FreeProfile)(AIColorProfile profile)

Frees the memory associated with a color profile that is no longer needed.

You can do this after creating the transform with CreateXform(). (Note that this function does not return an error code.)

Parameters:

profile

The profile. Upon return, the reference is no longer valid.

AIAPI void( * AIOverrideColorConversionSuite::FreeXform)(const ai::uintptr xform)

Frees memory for a transformation when it is no longer needed.

(Note that this function does not return an error code.)

Parameters:

xform The transformation, as created with CreateXform().

AIAPI AIErr( * AIOverrideColorConversionSuite::GamutRGBToCMYKImage)(void *srcBuf, const ASUInt32 numSamples, const ASUInt32 rgbFormat, ASBoolean *inGamut)

Converts RGB image samples into CMYK to determine if any of the samples were out of gamut.

Parameters:

	srcBuf	A pointer to the sample data, which must have 8 bits per component.
	numSamples	The number of samples in the source buffer.
	rgbFormat	The RGB format used in the samples, an `AIRGBPixelFormat` value.
	inGamut	[out] A buffer in which to return true if all of the samples are in gamut.

AIAPI void( * AIOverrideColorConversionSuite::GetColorSettingsPolicies)(ASBoolean *AI6Mode, ColorConvPolicy *rgbPolicy, ColorConvPolicy *cmykPolicy)

Retrieves the color conversion policies and the AI6 mode from the Color Settings dialog.

(Note that this function does not return an error code.)

Parameters:

	A16Mode	[out] A buffer in which to return the A16 mode
	rgbPolicy	[out] A buffer in which to return the RGB color conversion policy.
	cmykPolicy	[out] A buffer in which to return the CMYK color conversion policy.

AIAPI AIRenderingIntent( * AIOverrideColorConversionSuite::GetColorSettingsRenderIntent)(void)

Retrieves the render intent from the Color Settings dialog (Note that this function returns a constant value, not an error code.

)

Returns:: The rendering-intent constant.

AIAPI void( * AIOverrideColorConversionSuite::GetInternalTransform)(const InternalColorTransformType whichOne, ai::uintptr *xform)

Retrieves a transform created by CreateInternalTransform(), to use with ApplyXformSample() or ApplyXformImage().

For example:

	CreateInternalTranform(LAB2RGB, NULL, NULL)
	GetInternalTransform(LAB2RGB, &xform);
	ApplyXformSample(xform, incolor, outcolor, KLAB2RGB. false);
	FreeAllInternalTransforms()

Note:: For LAB data, the L value must be scaled from [0..100] to [0..255], and the A and B values must be scaled from [-128..127] to [0..255].

Parameters:

	whichOne	The predefined transform type.
	xform	[out] A buffer in which to return the transform.

AIAPI ASUInt32( * AIOverrideColorConversionSuite::GetOpenPolicy)(AIColorProfile *profile, ASUInt32 colorModel, ASBoolean isLink, ASBoolean linkHasMultipleProfiles)

Retrieves the current color management policy for how to treat color profiles when opening documents.

Also gets a valid profile for the current document, according to that policy. Queries user if needed to determine what profile should be used. (Note that this function returns a constant value, not an error code.)

Parameters:

	profile	[in, out] The embedded color profile for the current document, or `NULL` if the document has no embedded profile or has multiple profiles. If `NULL`, and if the policy indicates that a profile should be assigned, returns that profile assigned by current policy, or by user interaction. Can be `NULL` if color management is turned off, or if the user discards the embedded profile.
	colorModel	The color model of the current document, an `AIDocumentColorModelValue`.
	isLink	When true, get the policy for placing file formats that contain profiles, instead of the open policy.
	linkHasMultipleProfiles	When true, the linked file has more than one profile for a given colorspace. If the linked file contains both RGB and CMYK, call the function once for each colorspace, as the policies can be different.

Returns:: A AIFileOpenColorProfilePolicy value.

AIAPI AIErr( * AIOverrideColorConversionSuite::GetProfileData)(const AIColorProfile profile, ASUInt32 *size, void *data)

Retrieves the tag data for a color profile.

Parameters:

	profile	The color profile.
	size	[out] A buffer in which to return the number of bytes returned in the data buffer, or, if `data` is `NULL`, the size of the buffer needed.
	data	[in, out] `NULL` to retrieve the size of buffer needed, or a buffer in which to return the tag data.

AIAPI AIErr( * AIOverrideColorConversionSuite::GetProfileName)(const AIColorProfile profile, ai::UnicodeString &profileName)

Retrieves the description name of a color profile.

Parameters:

	profile	The color profile.
	profileName	[out] A buffer in which to return the descriptive name string.

AIAPI void( * AIOverrideColorConversionSuite::GetSavePolicy)(const ASUInt32 whichSpace, ASUInt32 *policy, ASUInt32 *defaultState, ai::UnicodeString &profName)

Retrieves the current color management policy for how to treat color profiles when saving documents; that is, which profile, if any, should be saved with the document.

Also reports what profile would be embedded, if any, for the current document, according to that policy. (Note that this function does not return an error code.)

Parameters:

	whichSpace	The working colorspace corresponding to the document color model, an `AIWorkingColorSpace` value.
	policy	[out] A buffer in which to return the policy, an `AIFileSaveColorProfilePolicy` value.
	defaultState	[out] A buffer in which to return the default state of the "Embed profile?" checkbox
	profName	[out] A buffer in which to return the name of the profile to be embedded, if any.

AIAPI AIErr( * AIOverrideColorConversionSuite::GetWSProfile)(const ASUInt32 whichProfile, AIColorProfile *profile)

Creates a current working color profile.

When you create a profile this way, you must free it with FreeProfile() when you no longer need it.

Parameters:

	whichProfile	The colorspace for the profile, an `AIWorkingColorSpace` value.
	profile	[out] A buffer in which to return the color profile.

AIAPI AIBoolean( * AIOverrideColorConversionSuite::IsBPCOn)()

Reports whether Black Point Compensation is currently enabled.

(Note that this function returns a Boolean value, not an error code.)

Returns:: True if BPC is currently enabled, false otherwise.

See also:: BPCOn()

AIAPI AIErr( * AIOverrideColorConversionSuite::MakeProfileFromCalCMYK)(AICMYKCal *cmykCal, AIColorProfile *profile)

Constructs a color profile from CMYK calibration information.

Parameters:

	cmykCal	A pointer to the calibration information.
	profile	[out] A buffer in which to return the color profile.

AIAPI AIErr( * AIOverrideColorConversionSuite::MakeProfileFromCalGray)(AIGrayCal *grayCal, AIColorProfile *profile)

Constructs a color profile from grayscale calibration information.

Parameters:

	grayCal	A pointer to the calibration information.
	profile	[out] A buffer in which to return the color profile.

AIAPI AIErr( * AIOverrideColorConversionSuite::MakeProfileFromCalRGB)(AIRGBCal *rgbCal, AIColorProfile *profile)

Constructs a color profile from RGB calibration information.

Parameters:

	rgbCal	A pointer to the calibration information.
	profile	[out] A buffer in which to return the color profile.

AIAPI void( * AIOverrideColorConversionSuite::ProfsEqual)(const AIColorProfile srcProfile, const AIColorProfile destProfile, ASUInt32 *match)

Reports whether two profiles are the same.

(Note that this function does not return an error code.)

Parameters:

	srcProfile	The first profile.
	destProfile	The second profile.
	match	[out] A buffer in which to return true (non-zero) if the two profiles are the same, false (0) if different or if either is not a valid profile.

AIAPI void( * AIOverrideColorConversionSuite::RestoreBPC)(void)

Restores the previous Black Point Compensation setting, after using BPCOn().

(Note that this function does not return an error code.)

The documentation for this struct was generated from the following file:

AIOverrideColorConversion.h

AIOverrideColorConversionSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIOverrideColorConversionSuite Struct Reference
[API Suite List]