An instance structure for the CMM API implementation. More...

#include "swcmm.h"

Data Fields
const sw_cmm_api *	implementation
	Pointer to the API implementation. More...

sw_memory_instance *	mem
	A memory allocator instance. More...

HqBool	support_input_profiles
	Does the implementation support ICC input profiles?

HqBool	support_output_profiles
	Does the implementation support ICC output profiles?

HqBool	support_devicelink_profiles
	Does the implementation support ICC devicelink profiles?

HqBool	support_display_profiles
	Does the implementation support ICC display profiles?

HqBool	support_colorspace_profiles
	Does the implementation support ICC colorspace profiles?

HqBool	support_abstract_profiles
	Does the implementation support ICC abstract profiles?

HqBool	support_named_color_profiles
	Does the implementation support ICC named color profiles?

HqBool	support_ICC_v4
	Does the implementation support ICC version 4 profiles? More...

HqBool	support_black_point_compensation
	Does the implementation support black point compensation?

HqBool	support_extra_absolute_intents
	Does the implementation support the extended intents of AbsolutePerceptual and AbsoluteSaturation? More...

uint32	maximum_input_channels
	The maximum number of input channels the implementation supports. More...

uint32	maximum_output_channels
	The maximum number of output channels the implementation supports. More...

HqBool	allow_retry
	If the alternate CMM implementation fails to open a profile or create a transform, this boolean indicates if the RIP should try to handle the transformation itself. More...

HqBool	fallback_to_builtin_cmm
	If `TRUE`, sw_cmm_api::invoke_transform() for an ICC transform may return SW_CMM_SUCCESS_USE_BUILTIN. The RIP will ignore color values returned by sw_cmm_api::invoke_transform() and use the built-in CMM to perform the ICC transform for this color value.

HqBool	multithread_icc_transforms
	If `TRUE`, sw_cmm_api::open_transform(), sw_cmm_api::close_transform() and sw_cmm_api::invoke_transform() for ICC transforms may be called from more than one thread at the same time.

HqBool	deprecated_multithread_customcmm_transforms
	Variable deprecated in SW_CMM_API_VERSION_20250922; custom color spaces are now implemented by sw_ccs_api. This variable slot formerly contained `multithread_customcmm_transforms`. An alternate cmm that was compiled with an earlier version of sw_cmm_api may still be run alongside this version of the RIP. It may also be compiled, but the legacy alternate cmm code must be compiled with swcmm.h from an SDK version prior to SW_CMM_API_VERSION_20250922.

sw_datum	params
	Contains a copy of the key/value pairs in the params dictionary that is optionally passed to the setalternatecmm operator. An alternate cmm accesses these params via swdataapi.

HqBool	uses_object_based_color
	Indicates that this CMM makes use of object-based color, i.e. it makes use of the object_type and/or the color_model params to the open_transform2() interface function. Those CMMs that do use object-based color should set this to TRUE, otherwise unexpected object-based color will be the result. For most other CMMs, this variable will make little difference, but those CMMs for which executing open_transform2() is time consuming, a FALSE value will aid the RIP's performance by enabling it to perform better caching.

Detailed Description

An instance structure for the CMM API implementation.

This is the definition of an alternate CMM instance. The RIP allocates memory for the instances, fills in the implementation and memory instance fields, and calls the implementation's constructor to complete the remaining details. The RIP will construct one instance as a result of using either the setalternatecmm operator, or the setpagedevice operator with the /AlternateCMM key. These are commonly used in the RIP's configuration.

There will normally be at most one CMM instance active on each page. There may be more than one CMM instance active at a time if Harlequin Parallel Pages is in use. While discouraged, it is possible to call setalternatecmm multiple times on the same page; this may result in several CMM instances active on the same page which will have unpredictable results depending on the job structure.

The instance structure may be subclassed to hold private data by defining a subclass structure containing this structure as its first member, and using the size of that structure as the implementation's instance size. Individual methods may then downcast their instance pointer parameters to subclass pointers, and use the private data. e.g.,

typedef struct my_instance {
  sw_cmm_instance super ; // must be first entry
  struct my_data *dynamic ;
  int32 other_fields ;
} my_instance ;
 
static sw_cmm_result RIPCALL my_construct(sw_cmm_instance *inst)
{
  my_instance *myinst = (my_instance *)inst ; // downcast to subclass
  // allocate private data:
  myinst->dynamic = cmmegMemAlloc(inst, sizeof(myinst->dynamic)) ;
  return myinst->dynamic != NULL ? SW_CMM_SUCCESS : SW_CMM_ERROR_MEMORY ;
}
 
static void RIPCALL my_destruct(sw_cmm_instance *inst)
{
  my_instance *myinst = (my_instance *)inst ; // downcast to subclass
  // free allocated data, if necessary:
  cmmegMemFree(inst, myinst->dynamic) ;
}
 
const static sw_cmm_api my_impl = {
  {
    SW_CMM_API_VERSION_20200117,
    (const uint8 *)"myname",
    (const uint8 *)("A long description of my module implementation"
                    "Copyright (C) 2021 Global Graphics Software Ltd."),
    sizeof(my_instance), // RIP will allocate this amount for the subclassed instance
  },
  // ...more of sw_cmm_api definition...
  my_construct,
  my_destruct,
  // ...rest of sw_cmm_api definition...
} ;
 
// use the PostScript fragment:
//   (myname) setalternatecmm
// in the config to create the CMM instance and call my_construct().

The RIP will not touch memory beyond the size of the instance structure for the implementation version registered.

Field Documentation

◆ allow_retry

HqBool sw_cmm_instance::allow_retry

If the alternate CMM implementation fails to open a profile or create a transform, this boolean indicates if the RIP should try to handle the transformation itself.

If set to TRUE, the RIP will retry the color transform using the built-in CMM in the event of an alternate CMM returning an error when opening profiles or transforms. For example, the call to sw_cmm_api::open_profile() may fail because the ICC profile is an unsupported colorspace conversion profile (despite the profile header declaring a different profile class). If allow_retry is FALSE, the RIP will fail the job when encountering such errors.

◆ implementation

const sw_cmm_api* sw_cmm_instance::implementation

Pointer to the API implementation.

API methods for a blob instance should always be called by indirecting through the instance's implementation field.

This field is filled in by the RIP before sw_cmm_api::construct() is called.

◆ maximum_input_channels

uint32 sw_cmm_instance::maximum_input_channels

The maximum number of input channels the implementation supports.

For the device to PCS conversion, the input will be the device and the output the PCS. Vice-versa for the PCS to device conversion. A value of zero means that the RIP should assume there is no maximum value.

Note that the alternate CMM may still reject a profile when an attempt is made to open it.

◆ maximum_output_channels

uint32 sw_cmm_instance::maximum_output_channels

The maximum number of output channels the implementation supports.

For the device to PCS conversion, the output will be the PCS and the input the device. Vice-versa for the PCS to device conversion. A value of zero means that the RIP should assume there is no maximum value.

Note that the alternate CMM may still reject a profile when an attempt is made to open it.

◆ mem

sw_memory_instance* sw_cmm_instance::mem

A memory allocator instance.

This object is supplied by the RIP so that the CMM implementation can allocate memory using the RIP's memory allocator. CMM implementations should use this in preference to malloc() and free(), so that the RIP can track memory allocation and respond to low memory states more effectively.

This field is filled in by the RIP before sw_cmm_api::construct() is called.

◆ support_extra_absolute_intents

HqBool sw_cmm_instance::support_extra_absolute_intents

Does the implementation support the extended intents of AbsolutePerceptual and AbsoluteSaturation?

These extended intents are derived from the Perceptual and Saturation tables of an ICC profile in the same way that AbsoluteColorimetric is derived from RelativeColorimetric, that is, by scaling PCS values to the illuminant XYZ values in the profile.

◆ support_ICC_v4

HqBool sw_cmm_instance::support_ICC_v4

Does the implementation support ICC version 4 profiles?

If it does not, the RIP will use its built-in CMM to transform colors when an ICC v4 profile is required.

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

lib/interface/swcmm.h

Data Fields