PS device for setting parameters used by the Pure Color CMM example

The %cmmparams% example PostScript device for setting configuration parameters used by the PureColor CMM example. More...

Files
file	cmm_params.c
	The %cmmparams% example PostScript device for setting configuration parameters used by the PureColor CMM example.
file	cmm_params.h
	Interface to the %cmmparams% example PostScript device.

Functions
HqBool	purecolor_register_params (void)
	Register the CMM_PARAMS_DEVICE_TYPE PostScript device type. More...
static int32	cmmSetParam (DEVICELIST *dev, DEVICEPARAM *param)
	Set a %cmmparams% device param with a new value. More...
static int32	cmmStartParam (DEVICELIST *dev)
	Prepare the device for a set of calls to cmmGetParam() as part of currentdevparams. More...
static int32	cmmGetParam (DEVICELIST *dev, DEVICEPARAM *param)
	Retrieve the current value of a %cmmparams% device param. More...

Detailed Description

The %cmmparams% example PostScript device for setting configuration parameters used by the PureColor CMM example.

Most of the PostScript device interface functions are inactive. The principle behaviour is in the cmmSetParam() function. It also implements the cmmStartParam() and cmmGetParam() functions to retrieve the parameters.

Note

This code should be used for reference purposes only.

Function Documentation

cmmGetParam()

static int32 cmmGetParam ( DEVICELIST *  dev, DEVICEPARAM *  param  )

static

Retrieve the current value of a %cmmparams% device param.

Parameters

dev	The current device.
param	A structure in which to store the parameter value. If the paramname field is NULL, then store the next parameter in an iteration, otherwise store the value of the requested parameter.

Returns

One of the values: ParamIgnored, ParamAccepted, ParamError (or -1).

This routine has two functions. If the DEVICEPARAM::paramname field of the param argument is NULL when it is called, the next parameter name and value in an iteration started by DEVICELIST_START_PARAM should be returned through the DEVICEPARAM structure. If the DEVICEPARAM::paramname field is not NULL then the value of that specific parameter name should be returned through the DEVICEPARAM structure.

In the second case if the parameter name is not recognized the routine should return ParamIgnored, otherwise it should return ParamAccepted. If an error occurs, ParamError should be returned and the DEVICELIST_LAST_ERROR method should return an appropriate error code.

If not returning ParamIgnored, the DEVICEPARAM::type field must be set to one of DEVICEPARAM_type values. The appropriate union field and length if necessary should be set to the value of the parameter. If a string value is returned, the string value field should point to the device's local copy of the string. The RIP will copy the string into its own storage. If returning a composite object (an array or a dictionary), the implementation may allocate memory for the DEVICEPARAM array representing the composite object and store the memory pointer in the DEVICEPARAM::paramval.compobval field. The RIP will copy the value into its own storage as necessary. This memory should be freed by the device type implementation on the next call to DEVICELIST_GET_PARAM or DEVICELIST_START_PARAM. The client is required to call DEVICELIST_START_PARAM if the final call it made to DEVICELIST_GET_PARAM returned a composite object.

If returning the next parameter (DEVICEPARAM::paramname is NULL on function entry) the DEVICEPARAM::paramname field should be set to point to the name of the parameter being returned, and the DEVICEPARAM::paramnamelen field set to the length of that name.

Note

The iteration may not be thread-safe, so can generally only be used from PostScript language code, or code called from the PostScript language.

The Harlequin RIP SDK provides some utility routines to assist writing parameter methods:

• param_match_name() and param_match_cname() can be used to match parameter names.
• param_store_name() can be used to store the parameter name for enumerations.
• param_store_string() can be used to store string values for retrieval.

See also

cmmStartParam(), cmmSetParam()

cmmSetParam()

static int32 cmmSetParam ( DEVICELIST *  dev, DEVICEPARAM *  param  )

static

Set a %cmmparams% device param with a new value.

Parameters

dev	The current device.
param	A structure describing the parameter to set and its value.

Returns

One of the values: ParamAccepted, ParamTypeCheck, ParamRangeCheck, ParamConfigError, ParamIgnored, ParamError (or -1).

The PostScript language operator setdevparams will call this device routine. The param argument specifies the device parameter name and its value in the DEVICEPARAM structure. Parameters are always named by a string, specified by DEVICEPARAM::paramname and DEVICEPARAM::paramnamelen, and accessible through theIDevParamName() and theIDevParamNameLen() macros. Note that the parameter name is not necessarily zero-terminated, the parameter length should always be checked when accessing the parameter name.

The DEVICEPARAM::type field indicates the type of the parameter to set. This will be one of:

ParamBoolean

A boolean value is stored in the DEVICEPARAM::paramval.boolval union field, accessible through theIDevParamBoolean() macro.

ParamInteger

An integer value is stored in the DEVICEPARAM::paramval.intval union field, accessible through theIDevParamInteger() macro.

ParamFloat

A real value is stored in the DEVICEPARAM::paramval.floatval union field, accessible through theIDevParamFloat() macro.

ParamNull

No value is stored. The interpretation of a null parameter depends on the device type.

ParamString

A real value is stored in the DEVICEPARAM::paramval.strval union field and the DEVICEPARAM::paramval.strvallen length, accessible through theIDevParamString() and theIDevParamStringLength() macros. Note that this string value is not necessarily zero-terminated, the string length should always be checked when accessing string values.

Strings set using this method are stored in the Harlequin Core internal memory which may be re-used; therefore, if the device needs to keep referring to the string, it must copy it into its own memory.

ParamArray

An array of DEVICEPARAM structures are stored in the DEVICEPARAM::paramval.compobval union field and the DEVICEPARAM::paramval.strvallen length, accessible through theIDevParamArray() and theIDevParamArrayLen() macros. The DEVICEPARAM structures in this array (and any sub-objects in them) are only guaranteed to remain valid for the duration of this method invocation. Therefore, if the device needs to keep referring to them, it must copy them into its own memory or unpack them into device-specific structures. The parameter name fields of the array of DEVICEPARAM structures are not used, and should not be dereferenced.

ParamDict

An array of DEVICEPARAM structures (arranged in pairs) are stored in the DEVICEPARAM::paramval.compobval union field and the DEVICEPARAM::paramval.strvallen length, accessible through theIDevParamDict() and theIDevParamDictLen() macros. The array of DEVICEPARAM structures is twice the length of theIDevParamDictLen(). The first structure in each pair represents a dictionary key; the second structure in each pair represents a dictionary value. The DEVICEPARAM structures in this array (and any sub-objects in them) are only guaranteed to remain valid for the duration of this method invocation. Therefore, if the device needs to keep referring to them, it must copy them into its own memory or unpack them into device-specific structures. The parameter name fields of the array of DEVICEPARAM structures are not used, and should not be dereferenced.

This method returns a code to indicate the success or failure of setting the parameter:

ParamAccepted

The value ParamAccepted means that the parameter has been set successfully. This does not necessarily mean the exact value was used, or that the parameter will read back with the value just set: these are implementation defined.

ParamTypeCheck

ParamTypeCheck means the value set was an incorrect type for the parameter of that name.

ParamRangeCheck

ParamRangeCheck indicates that the value was unreasonable for the device parameter.

ParamConfigError

ParamConfigError indicates that the value of the parameter was reasonable, but not achievable with this implementation.

ParamIgnored

If the parameter name is not supported by this device, ParamIgnored should be returned.

ParamError

ParamError means that some other error occurred for example, this error might be that configuring underlying hardware failed. If ParamError is returned, the DEVICELIST_LAST_ERROR method should return an appropriate error code.

The following device parameters are valid for all devices, and are not passed to the device. They are handled internally by the Harlequin Core:

/Password

See the description of setdevparams in [RB3].

/DeviceType

Binds an uninitialized device mount to a particular device type, and initializes an instance of the device.

/Enable

If set to true, permits file system operations on that device. An invalidaccess error is generated if the device's type has not been set yet.

The Harlequin RIP SDK provides some utility routines to assist writing parameter methods:

• param_match_name() and param_match_cname() can be used to match parameter names.

See also

cmmGetParam(), cmmStartParam()

cmmStartParam()

static int32 cmmStartParam ( DEVICELIST *  dev )

static

Prepare the device for a set of calls to cmmGetParam() as part of currentdevparams.

Parameters

dev	The current device.

Returns

The number of device parameters to enumerate (this may be 0 if there are no device parameters), or -1 for failure.

This routine is called by the PostScript language operator currentdevparams to determine how many parameters will be returned, and to start enumerating them. The number returned need not be the same as the number of device parameter names recognized by the device, because some device parameters can be write only, or a parameter may only be returned once a value has been set for it. The number excludes the parameters that are handled by the interpreter itself (/Password, /DeviceType, /Enable). Following this call, DEVICELIST_GET_PARAM will be called multiple times with a NULL DEVICEPARAM::paramname field to get each of the parameters.

If there are no such device parameters, 0 should be returned. If an error occurs, -1 should be returned.

Note

The iteration may not be thread-safe, so can generally only be used from PostScript language code, or code called from the PostScript language.

See also

cmmGetParam(), cmmSetParam()

purecolor_register_params()

HqBool purecolor_register_params

(

void

)

Register the CMM_PARAMS_DEVICE_TYPE PostScript device type.

Returns

Bool for successful registration of the CMM Params PS device.

If compiled normally, the "clrip" application layer registers this devide during RIP startup. CMM module examples may be excluded from "clrip" by building with NO_CMMEG defined.