The definition of an implementation of the alternate CMM interface. More...

#include "swcmm.h"

Data Fields
sw_api_info	info
	Version number, name, display name, instance size.

HqBool(*	init )(sw_cmm_api implementation, const sw_cmm_init_params params)
	The init() method is called before any other calls to the implementation. More...

void(*	finish )(sw_cmm_api *implementation)
	The finish() method is called after all calls to the implementation or its instances. More...

sw_cmm_result(*	construct )(sw_cmm_instance *instance)
	This method is used to construct an instance of an alternate CMM implementation. More...

void(*	destruct )(sw_cmm_instance *instance)
	This method is used to destroy an alternate CMM instance. More...

sw_cmm_result(*	open_profile )(sw_cmm_instance instance, sw_blob_instance ICC_profile, sw_cmm_profile *handle)
	Open an ICC profile. More...

void(*	close_profile )(sw_cmm_instance *instance, sw_cmm_profile profile)
	Close an alternate CMM profile. More...

sw_cmm_custom_colorspace (	declare_custom_colorspace )(sw_cmm_instance *instance, uint32 index)
	Declare support for a custom colorspace. More...

sw_cmm_result(*	open_custom_colorspace )(sw_cmm_instance instance, uint32 index, sw_cmm_profile handle)
	Open a custom colorspace profile. More...

sw_cmm_result(*	open_transform )(sw_cmm_instance instance, sw_cmm_profile profiles[], uint32 num_profiles, int32 intents[], HqBool black_point_compensations[], uint32 num_input_channels, uint32 num_output_channels, sw_cmm_transform handle)
	Create a color transformation comprising one or more alternate CMM profiles. More...

void(*	close_transform )(sw_cmm_instance *instance, sw_cmm_transform transform)
	Close a color transformation. More...

sw_cmm_result(*	invoke_transform )(sw_cmm_instance instance, sw_cmm_transform transform, float input_data, float *output_data, uint32 num_pixels)
	Invoke a color transformation. More...

void(*	security )(sw_cmm_instance instance, void buffer, uint32 size)
	A security challenge.

sw_cmm_result(*	open_transform2 )(sw_cmm_instance instance, sw_cmm_profile profiles[], uint32 num_profiles, int32 intents[], HqBool black_point_compensations[], HqBool compositing, sw_cmm_object_type object_type, sw_cmm_color_model color_model, uint32 num_input_channels, uint32 num_output_channels, sw_cmm_transform handle)
	Create a color transformation comprising one or more alternate CMM profiles. More...

Detailed Description

The definition of an implementation of the alternate CMM interface.

The RIP will construct a singleton instance for each implementation registered.

Field Documentation

◆ close_profile

void( * sw_cmm_api::close_profile) (sw_cmm_instance *instance, sw_cmm_profile profile)

Close an alternate CMM profile.

Parameters

[in]	instance	The alternate CMM instance owning the profile.
[in]	profile	A profile handle previous opened by an `open_profile()` or open_custom_colorspace() calls on the same alternate CMM instance. The alternate CMM implementation should discard any resources associated with the profile.

◆ close_transform

void( * sw_cmm_api::close_transform) (sw_cmm_instance *instance, sw_cmm_transform transform)

Close a color transformation.

Parameters

[in]	instance	The alternate CMM instance owning the color transform.
[in]	transform	A valid transform handle created by an `open_transform()` or open_transform2() call on the same alternate CMM instance. The alternate CMM implementation should discard any resources associated with the transform.

◆ construct

sw_cmm_result( * sw_cmm_api::construct) (sw_cmm_instance *instance)

This method is used to construct an instance of an alternate CMM implementation.

Parameters

[in,out] instance An incomplete instance of the sw_cmm_instance structure to complete. The RIP will allocate a structure of the size presented in the implementation's sw_cmm_api::info.instance_size field, fill in the implementation and callback API instance pointers, and then pass it to this routine. The construct() method is expected to fill in the remaining fields. The implementation may sub-class the instance to allocate private workspace by initialising the implementation's sw_cmm_api::info.instance_size larger than the size of the sw_cmm_instance structure, then downcasting the instance pointer in method calls.

Returns: SW_CMM_SUCCESS if the instance is fully constructed, otherwise one of the SW_CMM_RESULT error codes.

◆ declare_custom_colorspace

sw_cmm_custom_colorspace*( * sw_cmm_api::declare_custom_colorspace) (sw_cmm_instance *instance, uint32 index)

Declare support for a custom colorspace.

This method is optional. If this method is not supported, then the open_custom_colorspace() method will never be called.

Parameters

[in]	instance	An alternate CMM instance queried for custom colorspaces.
	index	A zero-based index used to identify the custom colorspaces defined by the alternate CMM instance. When trying to set custom colorspaces, the RIP will call this method with indices starting at 0, and increasing until either a match is found or this method returns `NULL`.

Returns: A pointer to a custom colorspace definition, or NULL if the index is out of the range supported by the alternate CMM implementation.

◆ destruct

void( * sw_cmm_api::destruct) (sw_cmm_instance *instance)

This method is used to destroy an alternate CMM instance.

This method is optional.

The RIP will call the destructors individually for each instance shortly before terminating the RIP. The RIP may also destroy and re-construct alternate CMM instances in low-memory situations.

Parameters

[in] instance An instance of the sw_cmm_api implementation to destroy.

◆ finish

void( * sw_cmm_api::finish) ( sw_cmm_api *implementation)

The finish() method is called after all calls to the implementation or its instances.

The implementation instances should not access any data owned by the RIP after this call, nor should they call any implementation or RIP callback API methods after this call. This method is optional; if not required, set to NULL.

Parameters

implementation A registered alternate CMM implementation to finalise.

◆ init

HqBool( * sw_cmm_api::init) ( sw_cmm_api *implementation, const sw_cmm_init_params *params)

The init() method is called before any other calls to the implementation.

This method may be used to initialise any implementation-specific data. This method is optional; if not required, set to NULL.

Parameters

	implementation	The registered alternate CMM implementation to be initialised.
[in]	params	A structure containing callback APIs and parameters valid for the lifetime of the module. Any parameters that the implementation needs access to should be copied out of this structure into private storage for the registered implementation.

Return values

TRUE	Success, indicating that the implementation is fully initialised.
FALSE	Failure to initialize the implementation. If this is returned, the implementation will not be finalized.

◆ invoke_transform

sw_cmm_result( * sw_cmm_api::invoke_transform) (sw_cmm_instance *instance, sw_cmm_transform transform, float *input_data, float *output_data, uint32 num_pixels)

Invoke a color transformation.

Parameters

[in]	instance	The alternate CMM instance owning the color transform.
[in]	transform	A valid transform handle created by an open_transform() call on the same alternate CMM instance.
[in]	input_data	An array of num_pixels sets of pixel-interleaved color values to transform. Colors are interleaved in the order specified by the input space of the first profile in the transform.
[out]	output_data	An array in which to store num_pixels sets of pixel-interleaved color values. Colors are interleaved in the order specified by the output space of the last profile in the transform.
	num_pixels	The number of sets of input pixel colorvalues to convert from the input space to the output space of the transform.

Returns: SW_CMM_SUCCESS if the invocation succeeded, one of the SW_CMM_RESULT error codes otherwise.

In all cases, both the input and output data should be pixel interleaved with each color value contained in a 32-bit IEEE floating value. The interleaving of the input data is in the same order as that expected by the first profile in a transform and the interleaving of the output data should be in the same order as produced by the last profile in the transform. It is the responsibility of the alternate CMM to marshal the data into and out of the format required for its internal use. As an example, if five pixels of RGB data were to be converted to CMYK, the RIP will arrange the input data as follows:

RGBRGBRGBRGBRGB

and invoke_transform() will produce this arrangement of output data:

CMYKCMYKCMYKCMYKCMYK

The number of channels for each pixel is derived from the first and last profiles in the transform as returned by open_transform().

The memory referenced by input_data and output_data is managed by the RIP and can be assumed to contain valid memory for the appropriate amount of data. The size, in bytes, allocated by the RIP to each is:

input_data: num_pixels * num_input_channels * sizeof(float)
output_data: num_pixels * num_output_channels * sizeof(float)

◆ open_custom_colorspace

sw_cmm_result( * sw_cmm_api::open_custom_colorspace) (sw_cmm_instance *instance, uint32 index, sw_cmm_profile *handle)

Open a custom colorspace profile.

The RIP does not interpret the profile handle returned by this call. The profile handle will be passed back to the alternate CMM implementation as a means of identifying the custom colorspace when creating a transform, or closing the profile.

Parameters

[in]	instance	An alternate CMM instance which previously declared support for the custom colorspace through a call to declare_custom_colorspace().
	index	A zero-based index used to identify the custom colorspace defined by the alternate CMM instance.
[out]	handle	A pointer in which a CMM profile handle is stored. This handle will be used to refer to the profile by close_profile(), open_transform(), and open_transform2().

Returns: SW_CMM_SUCCESS if the profile was successfully opened, in which case a non-NULL profile pointer should have been stored in handle. If the profile could not be opened, one of the SW_CMM_RESULT error codes is returned.

If a valid profile handle is returned, the close_profile() method will be called to destroy the profile later.

◆ open_profile

sw_cmm_result( * sw_cmm_api::open_profile) (sw_cmm_instance *instance, sw_blob_instance *ICC_profile, sw_cmm_profile *handle)

Open an ICC profile.

Parameters

[in]	instance	The alternate CMM implementation instance owning the ICC profile.
[in]	ICC_profile	A blob data source, giving access to the raw ICC profile data through the blob's sw_blob_api implementation methods. This blob will have been opened for non-exclusive read access. If the alternate CMM wishes to use the data source after the open_profile() method returns, it must create a new blob reference using the sw_blob_api::open_blob() method, and use that reference for all access after open_profile() terminates. If a new blob reference is created, the alternate CMM implementation must close that reference when it has finished accessing to it.
[out]	handle	A pointer in which a CMM profile handle is stored. This handle will be used to refer to the profile by close_profile(), open_transform(), and open_transform2().

Returns: SW_CMM_SUCCESS if the profile was successfully opened, in which case a non-NULL profile pointer should have been stored in handle. If the profile could not be opened, one of the SW_CMM_RESULT error codes is returned.

If a valid profile handle is returned, the close_profile() method will be called to destroy the profile later.

◆ open_transform

sw_cmm_result( * sw_cmm_api::open_transform) (sw_cmm_instance *instance, sw_cmm_profile profiles[], uint32 num_profiles, int32 intents[], HqBool black_point_compensations[], uint32 *num_input_channels, uint32 *num_output_channels, sw_cmm_transform *handle)

Create a color transformation comprising one or more alternate CMM profiles.

Parameters

[in]	instance	The alternate CMM instance owning the profiles.
[in]	profiles	An array of num_profiles profile handles, returned by calls to open_profile() or open_custom_colorspace().
	num_profiles	The number of profiles in the transform chain.
[in]	intents	An array of length num_profiles-1 specifying the rendering intents use for color conversions between adjacent profiles in the profiles parameter.
[in]	black_point_compensations	An array of length num_profiles-1 containing boolean flags, indicating if black point compensation is performed when converting colors between adjacent profiles in the profiles parameter.
[out]	num_input_channels	A location for the alternate CMM to fill in the number of color channels in the input space of the first profile in the transform.
[out]	num_output_channels	A location for the alternate CMM to fill in the number of color channels in the output space of the last profile in the transform.
[out]	handle	A pointer in which a CMM transform handle is stored by the alternate CMM implementation. This handle will be used to refer to the transform by close_transform() and invoke_transform() methods.

Returns: SW_CMM_SUCCESS if the transform was successfully opened, in which case a non-NULL transform pointer should have been stored in handle. If the profile could not be opened, one of the SW_CMM_RESULT error codes is returned.

If a valid transform handle is returned, the close_transform() method will be called to destroy the transform later.

◆ open_transform2

sw_cmm_result( * sw_cmm_api::open_transform2) (sw_cmm_instance *instance, sw_cmm_profile profiles[], uint32 num_profiles, int32 intents[], HqBool black_point_compensations[], HqBool compositing, sw_cmm_object_type object_type, sw_cmm_color_model color_model, uint32 *num_input_channels, uint32 *num_output_channels, sw_cmm_transform *handle)

Create a color transformation comprising one or more alternate CMM profiles.

This is essentially a duplicate of open_transform() but with additional parameters for object type, color model, and transparency compositing flag.

Parameters

[in]	instance	The alternate CMM instance owning the profiles.
[in]	profiles	An array of num_profiles profile handles, returned by calls to open_profile() or open_custom_colorspace().
	num_profiles	The number of profiles in the transform chain.
[in]	intents	An array of length num_profiles-1 specifying the rendering intents use for color conversions between adjacent profiles in the profiles parameter.
[in]	black_point_compensations	An array of length num_profiles-1 containing boolean flags, indicating if black point compensation is performed when converting colors between adjacent profiles in the profiles parameter.
[in]	compositing	A boolean flag indicating if this transform is part of transparency compositing. This may also be true for some transforms when OverprintPreview is active.
[in]	object_type	One of the values of sw_cmm_object_type.
[in]	color_model	One of the values of sw_cmm_color_model.
[out]	num_input_channels	A location for the alternate CMM to fill in the number of color channels in the input space of the first profile in the transform.
[out]	num_output_channels	A location for the alternate CMM to fill in the number of color channels in the output space of the last profile in the transform.
[out]	handle	A pointer in which a CMM transform handle is stored by the alternate CMM implementation. This handle will be used to refer to the transform by close_transform() and invoke_transform() methods.

Returns: SW_CMM_SUCCESS if the transform was successfully opened, in which case a non-NULL transform pointer should have been stored in handle. If the profile could not be opened, one of the SW_CMM_RESULT error codes is returned.

If a valid transform handle is returned, the close_transform() method will be called to destroy the transform later.

If both open_transform() and open_transform2() are both present in an implementation, only open_transform2() will be called.

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

lib/interface/swcmm.h

Data Fields

Detailed Description

Field Documentation

◆ close_profile

◆ close_transform

◆ construct

◆ declare_custom_colorspace

◆ destruct

◆ finish

◆ init

◆ invoke_transform

◆ open_custom_colorspace

◆ open_profile

◆ open_transform

◆ open_transform2