(v13) The rasterFormat structure

This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core

The plugin fills in the rasterFormat structure to describe to the RIP what sort of color raster formats it supports. It is defined in the header file gdevdefs.h . It is sent as an argument by the selectors D_GET_RASTER_FORMAT and D_WHICH_RASTER_FORMAT .

The raster format supports arbitrary numbers of colorants using a further plugin selector and additional structures. Each device type still supplies a set of raster formats in response to the D_GET_RASTER_FORMAT call as in earlier versions, but we still recommend that only one is used for each device type . If there is more than one, they must be distinct.

The fields are analogous to those in the pageHeader structure.

    typedef struct rasterFormat {
      int32 version;
      int32 colorType;
      int32 colorBits[4];
      int32 colorValues[4];
      int32 runLength;
      int32 screensRequired;
      int32 interleavingStyle;
      int32 deliveryStyle;
      int32 rasterDepth;
      int32 numFixedColorants;
      int32 numAliases;
      uint8 * pColorantFamily;
      int32 maxExtraSpotColorants;
      int32 minExtraSpotColorants;
      int32 separationOrdering;
      uint8 * pCustomConversions;
      uint8 * pCalibrationColorantFamily;
      int32 calibrationAsPress;
    } rasterFormat;

The values of the fields in rasterFormat are reflected in the RIP user interface, particularly in the page setup and subsidiary dialog boxes. The details vary between versions of the RIP. The effects are also seen in the Edit Style dialog box where there are effects on the ability to re‐order or add separations, and to have user control over screening.

Selections of color profiles, calibration targets, and similar behind‐the‐scenes details are also affected by the raster format.

version (rasterFormat)

version N

Type: int32

The plugin should ignore this field. It is obsolete. Instead, perform version checking with the CHECK_VERSION macro in the D_GET_IDENTITY call, and use that result throughout.

colorType (rasterFormat)

colorType Rw

Type: int32

The type of the raster - halftone, Contone, and so on. The plugin should fill it in using the constants described for the colorType field of the pageHeader structure. See colorType (pageHeader) .

Note: All writers of plugins should use the value colorType_general (value 0) when writing plugins for use with Version 6 and later RIPs. All the other colorType values (1 through 8) are deprecated and can be expressed in terms of colorType_general , together with correct settings of fields in rasterFormat .

When colorType is colorType_general , the call to D_GET_RASTER_FORMAT will usually be followed by a call to the selector D_GET_COLORANTS described in (v13) D_GET_COLORANTS , where the plugin supplies colorant information in the ColorantInfo structure. There is no call to D_GET_COLORANTS when numFixedColorants is zero. See numFixedColorants (rasterFormat) .

When there is no raster format, this field defaults to colorType_mono as before, for backward compatibility.

colorBits (rasterFormat)

colorBits Rw

Type: int32 [4]

Obsolete. If colorType is set to colorType_general , this field is ignored.

colorValues (rasterFormat)

colorValues Rw

Type: int32 [4]

This field specifies the ordering of colorants for simple color spaces. This will be used for older plugins when colorType is not colorType_general . It is set for colorType_general when numFixedColorants is zero and the colorant family is set to DeviceGray , DeviceRGB , or DeviceCMYK .

In either case, values are assigned as follows: 1 for Cyan, Red, or Gray, 2 for Magenta or Green, 3 for Yellow or Blue, and 4 for Black. The array gives the color present in each position, so if element 0 is set to 4, Black appears first. For DeviceGray and DeviceRGB set the 1 or 3 unused elements to zero, and for cases where the array is not used at all (numFixedColorants is non‐zero) set all four elements to zero.

This field is ignored for colorType values of colorType_mono and colorType_gray . For other values of colorType , the plugin should fill in the order of color components in the continuous tone raster that it expects. This should be done as described for the colorValues field of the pageHeader structure.

runLength (rasterFormat)

Note: runLength encoded raster data is no longer supported in Harlequin MultiRIP.

runLength Rw

Type: int32

If the plugin supports run‐length‐encoded output, it should set this field to true (a non‐zero value). If not, it should set it to zero. This is as for the runLength field of the pageHeader structure. See runLength (pageHeader) .

screensRequired (rasterFormat)

screensRequired Rw

Type: int32

Plugins should set this field to:

This field is provided explicitly rather than being deduced from the number of bits of output because sometimes a plugin may want to set or override the screening directly from its own PostScript language fragments. This would mean that anything the user does is irrelevant even though the rasters are halftoned in some way.

Note: For RIPs prior to HMR 10, a plugin that inadvertently set screensRequired_any did not necessarily suffer an error, but in HMR 10 that field directly influences whether the raster will be halftoned. so, setting it in combination with pixel interleaving or 8‐bit raster depth now generates an error.

Note: Plugins can define the availability and naming of screens in the user interface. For more information, see (v13) The plugin directory structure .

interleavingStyle (rasterFormat)

interleavingStyle Rw

Type: int32

The plugin should set this to one of the following values when colorType (pageHeader) is colorType_general :

For more information see (v13) Interleaving of data .

deliveryStyle (rasterFormat)

deliveryStyle Rw

Type: int32

rasterDepth (rasterFormat)

rasterDepth Rw

Type: int32

Replaces colorBits when colorType is colorType_general . This value indicates the number of bits per pixel for each color component. Valid values are 1, 8, 10, 16 .

Table: Supported raster depths for each interleave type

numFixedColorants (rasterFormat)

numFixedColorants Rw

Type: int32

The plugin should set this when colorType is colorType_general . For older color types this was determined by the colorType value.

numFixedColorants is the number of distinct process and fixed spot colorants supported by this raster format (For example. the value may be 6 for a six‐color process system, or 7 for that same system plus a custom varnish).

numFixedColorants may also be zero, but only in the case when pColorantFamily is set to the name DeviceCMYK , DeviceRGB , or DeviceGray . In these cases, the number of colorants is implied. However, the order of the colorants must then be specified in the colorValues array in the conventional way. (colorValues (rasterFormat) describes colorValues .)

numAliases (rasterFormat)

numAliases Rw

Type: int32

The number of names by which each colorant may be known. Each colorant has the same number of aliases: they come in corresponding sets. It is these names that will be matched with the SeparationColorNames key in the page device to determine which raster format to use (though the list may be edited later and shared with other devices).

The plugin should set this when colorType is colorType_general .

pColorantFamily (rasterFormat)

pColorantFamily Wr

Type: uint8*

The plugin should fill in this 64-character string buffer with a null‐terminated family name of the col‐ orants (for example Hex_col , Black-Green Forms Printing , or DeviceCMYK ). This tells the RIP that the device type will accept rasters expressed in this family of colorants.

Warning: This is a pointer to an existing string for the plugin to fill in. Beware of overwriting this pointer with one of your own, especially if you are doing static structure assignment.

Conventional one-, three-, and four-color devices should use DeviceGray , DeviceRGB and DeviceCMYK respectively. The names Cyan , Magenta , Yellow , Black , Red , Green , Blue , and Gray are always assigned for these families, so if these are the preferred names and no other information about the colorants is known or needed, numFixedColorants and numAliases can be set to zero and the D_GET_COLORANTS selector ((v13) D_GET_COLORANTS ) will not then be called. The order of the colorants should also then be supplied in colorValues in the conventional way. There is no harm, however, in supplying fixed colorants explicitly using the D_GET_COLORANTS selector anyway, because this permits other information about the inks to be supplied. Alternative preferred names can also be supplied.

In all cases, if no colorant names are supplied, the colorants will be named according to whatever existing names are selected for the colorant family.

This field is written to by the plugin, and therefore the character encoding method used is determined by the plugin. It is recommended that this field, and others which pass string information from the plugin to the RIP, restrict the characters used to the ASCII 127‐character set.

maxExtraSpotColorants (rasterFormat)

maxExtraSpotColorants Rw

Type: int32

The plugin should set this to indicate that the device type will accept up to this number of additional arbitrarily named colorants (spot colors ). These will be ordered in the raster according to the separationOrdering field in the rasterFormat . If the number of separations the plugin can handle is unlimited, set this field to maxExtraSpotColorants_unlimited . Set this to zero ( 0 ) if spot colors are not allowed at all - as is often the case for a composite color device.

minExtraSpotColorants (rasterFormat)

minExtraSpotColorants Rw

Type: int32

The plugin should set this field to indicate that it requires at least this number of additional arbitrarily named spot colors. This value will often be zero, and must always be less than or equal to maxExtraSpotColorants .

separationOrdering (rasterFormat)

separationOrdering Rw

Type: int32

This field shows whether or not the plugin is prepared to accept separations/colorants in any order or in only the order given.

Plugin should set this when colorType is colorType_general . The field is set by forming the logical OR of the following values:

One of the following is required:

Optionally, you may include in the logical OR one of:

pCustomConversions (rasterFormat)

pCustomConversions Wr

Type: uint8*

A string of up to 64 bytes which, when executed as PostScript code, yields an array of three procedures which will convert colors in DeviceGray , DeviceRGB and DeviceCMYK input color spaces respectively into colors of the colorant family (pColorantFamily ). These procedures operate in the manner of tint transform procedures - operands in the respective device space on the stack are consumed to yield the colors in the right number and order for the result space. The string will often run a file or procset to actually return the procedures, since it will rarely be long enough to do anything else, e.g. (/Devices/epson4800/Misc/DeviceCYMK/conv.ps) cvx run .

This field is written to by the plugin, and therefore the character encoding method used is determined by the plugin. It is recommended that this field, and others which pass string information from the plugin to the RIP, restrict the characters used to the ASCII 127‐character set.

Note: Any reference in the string to an external file cannot use the %fs% device. This is because the code in this string is run outside the context of a plugin device meaning that the %fs% device has no plugin directory to use.

Warning: This is a pointer to an existing string buffer for the plugin to fill in. Beware of overwriting this pointer with one of your own if you are doing static structure assignment.

If the colorant family is DeviceGray , DeviceRGB , or DeviceCMYK , then these procedures are not used. However, there must still be three procedures in an array. Set the contents of the string to {{}{}{}} cvlit in this case.

pCalibrationColorantFamily (rasterFormat)

pCalibrationColorantFamily Wr

Type: uint8*

A string of up to 64 bytes which names the colorant family to use for calibration and color management. For photo‐ink devices, this declared colorant family can be different from the actual colorant family of the output device.

If the device uses a photo‐ink colorant family, choose the value for the related color space. CMYK photo‐ink devices are the best known, for example Photo 2213 . (The numbers 2213 relate to the number of cyan, magenta, yellow and black inks available to the printer)

If the output device is not photo‐ink, set the string to the same as pColorantFamily . Setting the string to null or an empty string is equivalent.

This field is written to by the plugin, and therefore the character encoding method used is determined by the plugin. It is recommended that this field, and others which pass string information from the plugin to the RIP, restrict the characters used to the ASCII 127‐character set.

Warning: This is a pointer to an existing string buffer for the plugin to fill in. Beware of overwriting this pointer with one of your own especially if you are doing static structure assignment.

calibrationAsPress (rasterFormat)

calibrationAsPress Rw

Type: int32

Some devices, for example, the CIP3 file device, define composite raster formats but must emulate a separating output device as closely as possible. As a result, the user should be able to calibrate, and color manage the device as though it were a separating device. Set this field to TRUE (or 1) if this is the case. Set this field to FALSE (zero) if this ability is not required.

This key affects the RIP GUI only, though it would be reasonable for other implementations of calibration to behave similarly. The GUI changes are:

• Intended press and Actual press in the page setup dialog box are available when the flag is TRUE .
• In the Color Setup Manager, if this flag is TRUE for all raster formats supporting a particular colorant family, then that colorant family does not appear in the Colorspace menu.
• In the Calibration Manager and subsidiary dialog boxes, separating and non‐separating styles are treated differently.