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	multithread_customcmm_transforms
	If `TRUE`, sw_cmm_api::open_transform(), sw_cmm_api::close_transform() and sw_cmm_api::invoke_transform() for CMM custom colorspace transforms may be called from more than one thread at the same time.

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