(v13) The pageHeader structure

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

The pageHeader structure describes the page that the plugin must output. It is defined in the header file gpagesrc.h .

The structure can be accessed with the d_page (deviceDefinition) pointer in the deviceDefinition structure. The contents of the structure do not change after the D_OPEN request is sent. The plugin should consider it a read‐only structure.

Plugins written for use with more than one version of the RIP should check the plugin interface version before accessing newer fields.

    typedef struct pageHeader {
      int32 pageHeaderVersion;
      int32 deviceSpecifier[8];
      int32 xResolution;
      int32 yResolution;
      int32 printQuality int32 imageNegate;
      int32 marginNegate;
      int32 exposure;
      int32 xNegEnhance;
      int32 yNegEnhance;
      int32 mediaSelect;
      int32 mediaOffset;
      int32 mediaWidth;
      int32 ffff;
      int32 leftMargin;
      int32 rightMargin;
      int32 topMargin;
      int32 bottomMargin;
      int32 imageWidth;
      int32 imageHeight;
      int32 cutAfterPage;
      int32 dataWidth;
      int32 prePageFeed;
      int32 postPageFeed;
      int32 noCopies;
      int32 ctCopies;
      int32 queueType;
      int32 jobNumber;
      int32 pageNumber;
      uint8 jobName[256];
      int32 locked;
      int32 centrePageOnMedia;
      int32 colorType;
      int32 colorBits[4];
      int32 colorValues[4];
      uint8 colorName[32];
      int32 trimThePage;
      float xResFrac;
      float yResFrac;
      int32 runLength;
      int32 runOverlap;
      int32 mediaHeight;
      int32 outputAttributes;
      int32 numSeparations;
      int32 realJobNumber;
      uint8 *pbPluginParams;
      int32 screenDataCount;
      screenData *pScreenData;
      int32 pluginDecompression;
      int32 insertSheet;
      int32 paintNo;
      int32 centrePageOnMediaLength;
      int32 numChannels;
      int32 interleavingStyle;
      int32 rasterDepth;
      PageHeaderColorant * pColorants;
      int32 nRasterFormat;
      uint8 colorantFamily [64];
      PaperType *pPaperTypes ;
      uint8 outputQuality [64];
      uint8 jobNameUTF8 [256];
      uint8 mediaSize [32];
      PageHeaderColorant * pGroupColorants;
      int32 numGroupColorants;
      int32 packingUnit;
    } pageHeader;

pageHeaderVersion (pageHeader)

pageHeaderVersion 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.

deviceSpecifier (pageHeader)

deviceSpecifier N

Type: int32

The plugin should ignore this field. It is obsolete.

xResolution, yResolution (pageHeader)

xResolution, yResolution Wr

Type: int32

These fields hold the integral parts of the x (fast scan direction) and y (slow scan direction) resolutions, in dots per inch, of the page. See also xResFrac, yResFrac (pageHeader) .

This information is normally derived from the HWResolution array in the PostScript language page device, which in turn is set in the page setup dialog from the list supplied by the plugin device capabilities.

printQuality (pageHeader)

printQuality N

Type: int32

The plugin should ignore this field. It is obsolete.

imageNegate, marginNegate (pageHeader)

imageNegate, marginNegate Wr

Type: int32

If imageNegate is set to a non‐zero value, the plugin should negate the image. If marginNegate is set to a non‐zero value, the plugin should negate any margin area which it adds to the raster. In the current version of the RIP, imageNegate is always the same as marginNegate .

The margins are considered white, and should be printed as black if marginNegate is set.

exposure (pageHeader)

exposure Wr

Type: int32

If the exposure on the output unit can be controlled by software, this field will contain a device‐specific exposure value. The value is derived from the Exposure field of the page setup dialog, if the plugin has indicated that exposure is supported in the hasExposure field of the HqnDeviceCapabilities structure, during the D_CAPABILITIES call. If exposure is not supported, the field's value is ignored.

For more information see hasExposure (HqnDeviceCapabilities) .

xNegEnhance, yNegEnhance (pageHeader)

xNegEnhance, yNegEnhance N

Type: int32

The plugin can ignore these fields. They are obsolete.

mediaSelect (pageHeader)

mediaSelect Wr

Type: int32

The number of the cassette or paper tray to be used. It is the entry selected from the PostScript language page device InputAttributes dictionary. See Section 6.2 of [RB3].

This in turn is manipulated by the Cassette entry in the page setup dialog.

mediaOffset (pageHeader)

mediaOffset Wr

Type: int32

The offset, in pixels, of the media from the point at which the setter could start to output. Setting this value appropriately allows the plugin to compensate for any device that has a “logical” origin at a fixed distance from the mediaʹs origin: this is the only case that requires a mediaOffset . This can be a positive or negative value; it is positive if the physical media is smaller than the imageable area. The offset is in the same direction as media width. (For diagrams, see Figure: A typical capstan-type printer .)

mediaWidth (pageHeader)

mediaWidth Wr

Type: int32

The width of the media, in pixels. Not the width of the raster to be printed.

mediaheight and mediawidth are both scaled by the scaling page device parameter. If anti‐aliased, the output size will not be reflected in them.

ffff (pageHeader)

ffff N

Type: int32

This field is obsolete.

leftMargin, rightMargin, topMargin, bottomMargin (pageHeader)

leftMargin, rightMargin, topMargin, bottomMargin Wr

Type: int32

These fields define, in pixels, the size of the margin the plugin should apply to the image.

Raster data is rendered at LeftMargin + mediaOffset pixels from the leftmost imageable pixel on the device.

All fields can take positive or negative values. Negative margins imply an image clip position which the plugin must handle.

Figure: A typical capstan-type printer

Figure: A typical drum-type recorder

imageWidth, imageHeight (pageHeader)

imageWidth, imageHeight Wr

Type: int32

The dimensions of the image, measured in pixels.

Padding is applied to each line of raster data when required to align the start of each line on a 32 or 64‐bit boundary; see dataWidth (pageHeader) . imageWidth represents the width of data that has been rendered. Margins are not included in this value.

Caution: When dealing with continuous tone output, bits, bytes and pixels are not the same since, for example, 16 bits may be required to represent one pixel of one colorant.

dataWidth (pageHeader)

dataWidth Wr

Type: int32

The number of bits in a single line of data. This will currently be, depending on platform, a multiple of 32 or 64; ‘0' bits (or ‘1' bits for negative pages) are always appended to pad the image to make it a multiple of 32 or 64‐bits, depending on the value of imageWidth .

You should use dataWidth for the number of bits in a single line, even if you are using several bits per pixel.

cutAfterPage (pageHeader)

cutAfterPage Wr

Type: int32

If this is non‐zero, the media must be cut after the current page is imaged. This value is normally derived from the Media Manager dialogs via a PostScript language pagedevice parameter.

If the user selects Cut from a menu item, a job is sent with most fields initialized to zero, but with the following fields set:

    xResolution
    yResolution
    imageNegate
    marginNegate
    exposure
    mediaOffset
    leftMargin
    rightMargin
    topMargin
    bottomMargin
    imageWidth
    imageHeight
    dataWidth
    cutAfterPage
    prePageFeed
    postPageFeed
    noCopies
    ctCopies
    jobName

The following fields are not valid:

    mediaSelect
    mediaWidth
    jobNumber
    pageNumber
    colorType
    colorBits
    colorValues
    colorName
    trimThePage
    xResFrac
    yResFrac
    runLength
    mediaHeight
    outputAttributes
    numSeparations
    realJobNumber
    pbPluginParams
    screenDataCount
    screenData
    pluginDecompression
    insertSheet
    centrePageOnMedia

prePageFeed, postPageFeed (pageHeader)

prePageFeed, postPageFeed Wr

Type: int32

The amount of media, in pixels, that should be fed before and after this page, if appropriate for the output device.

This does not include any margins or trim. See trimThePage (pageHeader) , and leftMargin, rightMargin, topMargin, bottomMargin (pageHeader) . These values are normally derived from the Media Manager dialogs via PostScript language pagedevice parameters.

noCopies (pageHeader)

noCopies Wr

Type: int32

The number of copies of this page that should be printed. Whether the RIP sends the page to the plugin this number of times, or whether the plugin produces the right number of copies itself, depends on the device capabilities of the plugin.

The number is normally set in the page setup dialog. This setting can be overridden by a PostScript language job, and subsequently changed in the Output Controller's Info dialog.

ctCopies (pageHeader)

ctCopies Wr

Type: int32

The number of copies of this page that have been printed so far, not necessarily one after the other.

queueType (pageHeader)

queueType N

Type: int32

The plugin should ignore this field. The RIP uses it for internal purposes.

jobNumber (pageHeader)

jobNumber Wr

Type: int32

The job ID. The Output Controller uses this number to determine whether a set of pages originated in the same PostScript language job. The plugin can use it in the same way.

See also realJobNumber (pageHeader) .

pageNumber (pageHeader)

pageNumber Wr

Type: int32

Identifies the position of the page in the sequence of pages produced from the PostScript language job. (The first such page is numbered 1.)

Note: Pages may not be delivered to the plugin in this sequence, because they may have been manually re‐ordered in the Output Controller.

jobName (pageHeader)

jobName Wr

Type: uint8

A null‐terminated character string containing the name of the job. This name is prefixed by the page number, as it appears in the Output Controller.

This field is set by one of the following:

• The PostScript language job, from the string jobname in statusdict .
• The PostScript language user parameter JobName .
• The PostScript language page device parameter JobName .
• The name of the file from which the job is taken. This might be an input plugin name as given in the Input Manager dialog.

If none of the others is available, the last of these is the default.

This field uses the character encoding method supplied by the job, if the job name is supplied by the job itself, or the Harlequin encoding scheme (HES) if the job name is derived from the file name.

locked (pageHeader)

locked N

Type: int32

This plugin should ignore this field. The RIP uses it for internal purposes.

centrePageOnMedia (pageHeader)

centrePageOnMedia Wr

Type: int32

If this is non‐zero, the RIP has adjusted the margins so that the page is centered on the media in the x (fast‐scan) direction. This field corresponds with the Center page on media box in the Output Controller's Page Layout dialog.

Note: Although this field is not normally relevant to a plugin, if your plugin ignores margin information, you can use it to still keep control of the centering facilities. See also centrePageOnMediaLength (pageHeader) .

colorType (pageHeader)

colorType Wr

Type: int32

This field describes the format of the raster data for the page. It is one of the following manifest constants, defined in the header file gdevdefs.h :

colorType_general A constant indicating that the format is defined in the rasterFormat using interleavingStyle, numChannels and rasterDepth. . This value is only used if the rasterFormat that was selected for output had this as the colorType , as is strongly recommended for modern plugins. This means that older plugins will be supported correctly, and all the newer fields will be set properly, even if this is the case. (It is possible to express all the older values for colorType in terms of colorType_general .)

All other values are deprecated and should not be used.

See (v13) Interleaving of data for examples of all interleaved formats.

colorBits (pageHeader)

colorBits Wr

Type: int32 [4]

Obsolete: When colorType is set to colorType_general (see colorType (pageHeader) ) this field is ignored

colorValues (pageHeader)

colorValues Wr

Type: int32 [4]

This field is redundant, replaced by srgbEquivalent (PageHeaderColorant) , pColorants (pageHeader) , and numChannels (pageHeader) .

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.

For colorType_general this field will be set to [ 0 0 0 0 ] except where the family is DeviceCMYK , DeviceRGB , or DeviceGray in which case it will reflect the ordering used in versions of the RIP before version 5.0, described in Raster data representing a single-color separation and Raster data representing several colors . For other values of colorType this field will be set as before. Note that element 0 (zero) gives the position of the Cyan colorant, not the color of the first colorant.

For versions of the RIP before version 5, and for version 5.0 where the family is DeviceCMYK , DeviceRGB , or DeviceGray , the way this field is used depends on whether the raster represents a single-color separation or several colors.

Raster data representing a single-color separation

If the raster represents a single-color separation, that is, if the colorType is either colorType_mono or colorType_gray , this field gives the color represented by that separation in CMYK terms - whatever the color space of the original separation.

Each element of the array corresponds to a process color:

The values therein are 16‐bit integers, ranging as follows:

Typically, all elements of colorValues but one will be zero. Spot colors are an exception to this; if a page is in a spot color, it will be represented in colorValues as a mixture of process color values.

Note: If more than one separation is imposed on a single page, the values in the array are meaning‐ less.

The Roam and Preview functions use the values in colorValues to work out the color in which a separation should be displayed. The plugin may use them for its own purposes.

Raster data representing several colors

If the raster represents several colors, that is, if the colorType is any of the colorType_RGB and colorType_CMYK constants, the values indicate the order in which the raster presents the colored pixels. The order starts at 1, with 0 (zero) meaning that a color is not present.

For example, if a raster contained 32‐bit‐deep pixels with the first byte of each 4‐byte sequence representing yellow, the second representing magenta, the third cyan, and the fourth black (an ordering of YMCK), then this array would read [3 2 1 4]. For an RGB order of green, red, blue, the array would be [2 1 3 0].

colorName (pageHeader)

colorName Wr

Type: uint8 [32]

If the page is a color separation produced by the RIP, this field holds its color name in a null‐terminated string.

If the page is in a process color, it will be one of the preferred process color names specified in the raster format, for example: Cyan , Photo Black, Light Magenta . For plugins still using the deprecated colorType_CYMK values, the names Cyan , Magenta , Yellow , and Black are used.

If the page is in a spot color, it will be the spot color name given in the PostScript language job, for example PANTONE 386 .

If more than one color separation appears on the page, it will be Composite . If the page is mono‐ chrome, the colorName will be Gray .

This field uses the character encoding method supplied by the job or the plugin, as appropriate.

trimThePage (pageHeader)

trimThePage Wr

Type: int32

Gives the state of the Trim Page check box in the page setup and Output Controller Info dialogs. The option helps save media and improve throughput.

When it is set, whole bands of completely white space at the top and bottom of the image are omitted from the raster data delivered to the plugin, and the imageHeight parameter in the pageHeader structure is reduced accordingly.

Note: Empty bands in the middle of the page are still included.

xResFrac, yResFrac (pageHeader)

xResFrac, yResFrac Wr

Type: float

If the resolution of the image, in dots per inch, has a fractional part, it will be stored in these floats. The values in these fields are added to the integral parts in xResolution and yResolution respectively to produce the real image resolution.

The values in these fields are always between 0.0 and 1.0.

This fractional representation capability was introduced to support devices requiring metric measures, which may not convert to a whole number of dots per inch and for which this accuracy was vital. For compatibility with earlier versions of the plugin interface, fields were added to the structure rather than changing the type of the xResolution and yResolution fields.

Resolutions may be configured in Page Setup in lpi, lpcm, or lpmm, to one decimal place. If greater accuracy is required, it is necessary to use a PostScript language program to override /HWResolution in currentpagedevice .

runLength (pageHeader)

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

runLength Wr

Type: int32

This is non‐zero if the page buffer is run length encoded. It is usually zero.

Unless a plugin has been written to handle run‐length‐encoded data, it should reject any page for which this field is set. Further details about run‐length encoding can be obtained from Global Graphics.

runOverlap (pageHeader)

runOverlap N

Type: int32

The plugin can ignore this field. It is reserved for use in future versions of the plugin interface.

mediaHeight (pageHeader)

mediaHeight Wr

Type: int32

The height, in pixels, of the medium being used. On capstan recorders, where the feed is in the direction of the y ‐axis, this will normally be zero, indicating that there are no limits placed on the height of the bitmap that the RIP generated.

mediaheight and mediawidth are both scaled by the scaling page device parameter. If anti‐aliased, the output size will not be reflected in them.

outputAttributes (pageHeader)

outputAttributes Wr

Type: int32

The index number of the output destination (the bin, sorter, or whatever) selected from the PostScript language OutputAttributes field of the pagedevice dictionary. See [RB3] , Section 6.2.

To allow the user to select this from the page setup dialog, the plugin could use a plugin dialog. See (v13) Input and output plugin parameters and plugin dialogs .

numSeparations (pageHeader)

numSeparations Wr

Type: int32

The number of pages or films the RIP produced when automatically separating a single, color input page. The current page buffer will be one of these separations.

realJobNumber (pageHeader)

realJobNumber Wr

Type: int32

Note: This field is only valid in single device mode.

A predictable number identifying the job. It can be set from the PostScript language job as the JobNumber key to the setpagedevice operator.

If it is not set in that way, the number is incremented each time the interpreter starts a new job. These job numbers might be duplicated from session to session, or explicitly from the PostScript language.

By contrast, the jobNumber field identifies which job pages stored on disk belong to. (These are the pages listed in the Output Controller.) The jobNumber cannot be predicted in the way that realJobNumber can, because it depends on the jobs stored on disk in any one session.

Note: Two jobs cannot share the same jobNumber , but they can share a realJobNumber .

pbPluginParams (pageHeader)

pbPluginParams Wr

Type: uint8*

Using the selectors described in (v13) Input and output plugin parameters and plugin dialogs , the plugin can request arbitrary additional arguments. This field points to data, organized according to the DICTSTRUCTION template, giving any values specified for this page.

screenDataCount (pageHeader)

screenDataCount Wr

Type: int32

A count of the number of screen items in the pScreenData (pageHeader) list.

Note: This is only relevant if runLength is non‐zero.

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

pScreenData (pageHeader)

pScreenData Wr

Type: screenData*

A pointer to the head of the chain of screenData structures. The screenData structure is defined in the header file gpagesrc.h .

This field is only relevant if runLength is non‐zero. The pointer will be null otherwise.

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

pluginDecompression (pageHeader)

pluginDecompression Wr

Type: int32

This integer indicates whether the raster data for this page is in compressed form. If it is, the plugin must decompress it. Normally it is -1 , indicating that the raster is not compressed.

When the raster data is compressed, pluginDecompression will be the identifier of the algorithm needed to decompress it.

Details of the decompression algorithms required can only be obtained by special arrangement with Global Graphics.

insertSheet (pageHeader)

insertSheet Wr

Type: int32

Non‐zero when the pagedevice parameter InsertSheet is set to true .

It indicates that, for any appropriate devices, a sheet is to be fed to the output bin, bypassing the nor‐ mal imaging route. For example, this is a good choice for a plastic sheet such as a cover or separator which a user might otherwise damage. See the PostScript Language Reference Supplement, for Version 2011 - Jan. 24 1992, and later editions.

paintNo (pageHeader)

paintNo N

Type: int32

The plugin can ignore this field. It is used by the Output Controller in conjunction with the runLength field.

centrePageOnMediaLength (pageHeader)

centrePageOnMediaLength Wr

Type: int32

If this is non‐zero, the RIP has adjusted the margins so that the page is centered on the media in the y (slow‐scan) direction. This field corresponds with the Center page on media length box in the Output Controller's Info dialog. It is not relevant to capstan recorders, where media length is arbitrary.

Note: Although this field is not normally relevant to the plugin, if your plugin ignores margin information, you can use it to retain control over the centering of the media. See also centrePageOnMedia (pageHeader) .

numChannels (pageHeader)

numChannels Wr

Type: int32

The number of colorant channels in this raster. Note that some of these channels may be blank when producing separations, for example when separating to a band interleaved device. Also, where the plugin has permitted extra spot colorants in its raster format, there may be more channels than the fixed colorants originally specified.

For a monochrome device, numChannels is always 1 - it is not the total number of separations.

More generally, for composite output devices, numChannels is not necessarily, or even usually, the same as numFixedColorants in the rasterFormat because:

• When separating, each raster contains only a subset of the original colorants, usually 1 colorant.
• When separating, multiple separations can be imposed on one raster. (numChannels indicates the number imposed on this raster.)
• Arbitrary extra separations may have been added in response to spot color requests, even in composite rasters if the rasterFormat allows it.
• Colorants may be replicated: for example, in step and repeat work.

interleavingStyle (pageHeader)

interleavingStyle Wr

Type: int32

Note: The same values are valid here as are valid for interleavingStyle in the rasterFormat . For more information see (v13) Interleaving of data .

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