(v13) The HqnDeviceCapabilities structure

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

The HqnDeviceCapabilities structure defines some of the more standard features of the output device implemented by the plugin. It is defined in the header file gdevcpcf.h , and is sent as an argument by the selectors D_CAPABILITIES and D_FIND_DEVICE .

          typedef struct deviceCapabilities { int32 devCapStructVer;
          uint8 name[32]; int32 deviceType; int32 horizResCount;
          int32 horizResArray[32]; int32 vertResCount; int32 vertResArray[32]; int32 resDepends; USERVALUE setterWidth; USERVALUE setterLength; int32 clipType;
          int32 renderMaxFirst; int32 deviceIOMode; int32 ffff;
          int32 deviceFlags[8]; int32 xNegEnhance; int32 yNegEnhance; int32 hasExposure;
    } HqnDeviceCapabilities;

devCapStructVer (HqnDeviceCapabilities)

devCapStructVer Rw

Type: int32

Obsolete. Instead, perform version checking with the CHECK_VERSION macro in the D_GET_IDENTITY

call, and use that result throughout.

name (HqnDeviceCapabilities)

name Rw

Type: int8 [32]

The name to be used by the Device Manager to identify the device. This is a null‐terminated string, and is therefore limited to 31 significant bytes.

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.

deviceType (HqnDeviceCapabilities)

deviceType Rw

Type: int32

This field describes the device's media‐handling characteristics. The plugin sets this value to the com‐ bination of a number of flags, using the logical OR operation. These flags are defined in the header file gdevcnst.h .

Each of the flags represents a media‐handling characteristic of a typical output device. In addition to these flags, there are some compound flags that describe the characteristics of common devices. You can use one of these compound flags in place of the flags they combine.

Basic media handling flags

deviceType_x_unlimited deviceType_x_upto deviceType_x_exact

Set one of these three flags to indicate how the media restricts the image in the x (fast‐scan) direction.

Unlimited here means a raster of any size may be generated. Upto means that a raster may be generated up to the size of the media in that direction. Exact means that the size of the raster must match the size of the media exactly.

deviceType_y_unlimited deviceType_y_upto deviceType_y_exact

These flags are the same as those above for x , but for the y (slow scan) direction.

deviceType_x_feed

Set this flag to specify that media is fed from the x direction. This describes a device like a drum where the media feeds along the axis of the drum rather than from a direction perpendicular to the drum. Setting the flag has the following effect:

• The diagram in the Page Layout dialog of page setup is oriented appropriately for media fed from the side.
• The Center Page on Media Length check box is available in Page Layout. See centrePageOnMediaLength (pageHeader) .
• The RIP assumes that media is consumed in one go when fed, rather than incrementally changing as the page is exposed. This is a consequence of the feed being in the fast‐scan direction.
• Optimization in page setup offers Time Saving in addition to None and Media Saving . Time Saving changes the orientation of the job to keep the shortest side of a page parallel to the slow scan direction, provided that the media is wide enough.
• All four margin settings are available in Page Layout.

If deviceType_x_feed is not set, Y_Feed is taken as the default.

Media with a fixed dimension

Two flags show that a dimension of the media is fixed.

deviceType_fixed_length_media

Set this flag to specify that each page printed on the device consumes a fixed amount of media.

If set, it is assumed that an amount of media equal to the setterWidth (if deviceType_x_feed is set) or setterLength (if deviceType_x_feed is not set) will be consumed for each page printed. If not set, the RIP assumes that the printed image will consume an amount computed by adding image size and margins.

In addition, Center Page on Media Length or Center Page on Media Width (depending on the direction of feed) is adjusted, according to the amount of media fed.

deviceType_fixed_width_media

If set, the media width is derived from setterLength (if deviceType_x_feed is set) or setterWidth (if it is not set), rather than being editable in the Page Layout dialog or the Cassette Manager.

deviceType_no_cassettes

Set this to indicate that the device does not use interchangeable media cassettes and so cassette management is disabled.

deviceType_warn

Set this to enable warnings when media size constraints are exceeded by the rasters generated from the job. For example, the page size in the page setup for the job might be too large.

If set, rasters of any size can be generated, but if the media sizes are exceeded, a warning is given. If media size parameters are not set, then a warning will be issued if the setter sizes are exceeded by the rasters.

deviceType_ripToDisk

Set this flag to force the RIP to write the entire image to disk before attempting to start outputting it. Generally outputting from memory is faster than from disk and in multiple mode, the job is always fully written to disk (the pagebuffer) before output is started. However, if you are not using multiple mode, the entire job will not fit into memory and the output device is stop/starting, the job can be written to disk.

This provides faster output to the plugin, because there are fewer chances of catch‐up. It also means that output time will be more predictable overall.

Note: This flag's setting does not affect any of the other flags' settings.

Flags provided for backwards compatibility

Some flags are provided for backwards compatibility only, and new plugins should not use them. When the RIP sees these flags set, it sets the newer flags that have superseded them.

deviceType_continuous has been superseded by deviceType_capstan . deviceType_fixed has been superseded by deviceType_sheet . deviceType_both has been superseded by deviceType_part_drum . deviceType_file has been superseded by deviceType_unlimited . deviceType_mediaMask is obsolete.

Composite media-handling flags

The media‐management characteristics of five common device types are combined in some pre‐ defined device‐type flags, and also in the header file gdevcnst.h . They are:

RLE Device Flags

Note: RLE encoding is not supported in Harlequin MultiRIP

deviceType_partialPaintToPlugin

Set this flag to allow the RIP to output partial pages directly to the plugin instead of painting partial page buffers to disk when operating in Single If Required mode with RLE plugins.

The plugin must be capable of producing partial output and it is the responsibility of the plugin to buffer and combine any data from partial paints as necessary.

In this mode of operation pdevdef->d_page->paintNo will be set to a negative number when a partial paint is in progress, when the last set of data relating to the page is passed to the plugin this value will be positive so the output can be closed.

Plugins using the deviceType_partialPaintToPlugin flag must be coded to close the output under the correct conditions.

An example of this operation is included in the rle2ps example plugin.

Note : If a job is aborted during a partial paint, the plugin can detect and delete any buffered page by intercepting the D_CLOSE with the c_abort flag set and if a job is aborted between partial paints, the plugin can detect this by noting that it has a partial page buffered when the D_OPEN_ENDJOB call occurs. An illustration of this is in the rle2ps example plugin.

Cassette mismatch

deviceType_pluginHandleCassetteChange is a static flag defined in gdevcnst.h . If the plugin has this flag in its deviceType field of the deviceCapabilities structure, the RIP would not generate a warning if there is a cassette mismatch, assuming that the plugin would handle the mismatch itself.

This flag is not to be dynamically changed during the execution. Plugins do not have to have deviceType_pluginHandleCassetteChange defined (no Harlequin MultiRIP plugin from GGS does). The default behavior (that is, without the flag) is that the RIP posts a warning message when it finds that the cassette selected for a pagebuffer is different from that selected by the device.

horizResCount, horizResArray[32] (HqnDeviceCapabilities)

horizResCount, horizResArray[32] Rw

Type: int32 , and int32 [32]

These fields are concerned with the horizontal resolutions supported by the output device.

horizResArray should contain all possible horizontal (x , or fast‐scan direction) output resolutions, in dots per inch, that the output device supports, up to the array limit of 32 values.

horizResCount should be set to the total number of elements you set in horizResArray - that is, the total number of possible horizontal output resolutions available on the device.

If the device can support any resolution in a particular range of dots per inch, you can encode this range directly in horizResArray instead of listing each resolution. To do this:

• Before putting the first number in the range in the array, negate it. (300 => ‐300)

When the RIP reads the negative number, it interprets its absolute value as the start of a resolution range.

• Follow this element with the last number in the range.

A negative number must always be followed by another number, that is, a range must always be completed.

The absolute values of the two numbers specify the range allowed. (It does not matter whether the second number is positive or negative.)

More than one range can be specified, and ranges can be mixed with fixed resolutions as appropriate to the device.

If horizResCount is 1 and horizResArray[0] is zero, the resolution is entered explicitly by the user, and there is no list from which to choose. The only limit upon resolution in this case is the overall maximum imposed by the RIP.

When there is an array of resolutions to choose from, there is also an array of screen frequencies, with a direct mapping made between the two. Not providing an array of resolutions also means that the user cannot choose screen frequencies. Such a situation is usually only appropriate for continuous‐ tone devices. See also lpiArray (DeviceConfig) .

Note: If the user changes the output resolution in the page setup dialog, the screen frequency changes automatically. This is because the index of the horizResArray element representing the selected resolution is used to index the array of screen frequencies. (lpiArray , in the DeviceConfig structure.) The vertical resolution is used to set screen frequency.

Note: Interdependence between vertical and horizontal resolutions is controlled by the resDepends (HqnDeviceCapabilities) flag.

vertResCount, vertResArray[32] (HqnDeviceCapabilities)

vertResCount, vertResArray[32] Rw

Type: int32 , and int32 [32]

These fields are concerned with the vertical resolutions, in dots per inch, supported by the output device. They should be set as for horizResCount, horizResArray[32] (HqnDeviceCapabilities) , above.

Note: If the user changes the output resolution in the page setup dialog, the screen frequency changes automatically. This is because the index of the vertResArray element representing the selected resolution is used to index the array of screen frequencies.

resDepends (HqnDeviceCapabilities)

resDepends Rw

Type: int32

Set this to one of the following constants, defined in the header file gdevcnst.h :

deviceResolutionsVeqH

If resDepends is set to this, the RIP assumes that the output device resolutions are always square: vertical and horizontal are always equal.

In this case, whenever the user selects a resolution in the page setup dialog, the other resolution changes to the same value, providing it can be located in the other array of available resolutions. If this is not possible, the other resolution is set to zero.

deviceResolutionsIndependent

If resDepends is set to this, the RIP assumes that the output device resolutions are not necessarily square. (For example, some devices can operate with a horizontal resolution which is twice the vertical resolution.)

There is a constant deviceResolutionsIndependentScaled and deviceResolutionsVeqHScaled

The scaled versions behave as the unscaled ones, except that the values are scaled (multiplied) by the constant deviceResolutionsScaleFactor before use 1.              Using the formula (int)( (res) * deviceResolutionsScaleFactor + 0.5 ). The ʺ+ 0.5ʺ ensures rounding nearest, rather than round down. [1]. The value of deviceResolutionsScaleFactor is 1000.

There is a macro hasScaledResolutions() which checks whether the resDepends value in pCap is one of the scaled versions.

pCap in the previous para must be a pointer to a deviceCapabilities structure (typedef HqnDeviceCapabilities ).

When the user selects a vertical resolution in the page setup dialog, the horizontal resolution will change to the same value if it exists in horizResArray - but not vice versa.

deviceResolutionsInPairs, deviceResolutionsInPairsScaled

Resolution arrays are interpreted as pairs of values, so there must be an equal number of h and v values. The values do not need to be the same number for the h and v values; although, using unequal values will distort the view in ROAM.

Ranges are not supported. When the selected device uses deviceResolutionsInPairs[Scaled] the page setup and calibration edit dialogs show all possible resolutions from which you can make your choice.

This feature is introduced at plugin interface v18.6. The macro hasResolutionInPairs(pCap) returns True if the device pointed to by pCap has either of the above set. For more information see pluginInterfaceMajorVersion and pluginInterfaceMinorVersion in (v13) D_GET_IDENTITY and gdevcpcf.h line 91 et seq .

setterWidth, setterLength (HqnDeviceCapabilities)

setterWidth, setterLength Rw

Type: USERVALUE

The size, in inches, of the setter, expressed as floating-point values.

These should be the maximum width/length of media that can be inserted into the device. The actual media width in use is determined by the current cassette, and its location across the width can be set separately. The values are used in the Page Layout section of the page setup menu, and similarly in the Output Controller's Info dialog.

If a dimension is given as zero, then the RIP will take this to mean that the setter can cope with any size in that direction. For example, a continuous media device would specify setterLength as zero if it could cope with arbitrarily long images.

See Figure: A typical capstan-type printer , and Figure: A typical drum-type recorder .

clipType (HqnDeviceCapabilities)

clipType N

Type: int32

The plugin should ignore this field. It is obsolete.

renderMaxFirst (HqnDeviceCapabilities)

renderMaxFirst N

Type: int32

The plugin should ignore this field. The feature it was introduced to support is not implemented.

deviceIOMode (HqnDeviceCapabilities)

deviceIOMode N

Type: int32

The plugin should ignore this field. It is obsolete.

ffff (HqnDeviceCapabilities)

ffff N

Type: int32

The plugin should ignore this field. It is obsolete.

deviceFlags[8] (HqnDeviceCapabilities)

deviceFlags[8] Rw

Type: int32

Device‐specific flags. Only those in deviceFlags[0] are used in communications with the RIP. The remainder are available to the plugin for storing internally useful information, (deviceFlags[1] in the example output plugins).

For example, one element could be set to distinguish between different device types in a multiple‐ device plugin.

The plugin sets element 0 (zero) to the combination of a number of flags, chosen as required, and using the logical OR operation. These flags are defined in the header file gdevcnst.h .

DEV_FLAG_DISABLEMM

If this is set, media management is disabled. Setting this is equivalent to checking the Disable Media Management box in the Media Manager.

DEV_FLAG_SUPPORTS_DIR

Set this if the plugin supports the SELECT_DEV_DIRECTORY parameter of the selector (v13) D_SELECT_DEVICE .

DEV_FLAG_MIRROR_MODIFIER

If this flag is set, it toggles the direction of printing (right to left or left to right) that the RIP currently considers to be ‘mirrorprinting', and hence the orientation of the bitmap presented to the user at the page setup dialog's Mirrorprint option.

This means that a device which scans right to left instead of left to right across the output can recon‐ figure the user interface to make the RIP generate a bitmap more appropriate to its scan direction than the standard one.

DEV_FLAG_ROTATE_MODIFIER

If this flag is set, it adjusts by 90 degrees the Rotate option presented to the user in the page setup dialog, so that a device which scans in the y direction rather than the x direction can make the RIP generate a bitmap more appropriate to its scan direction.

DEV_FLAG_INSTANTIATE_ONE_DEVICE

If this flag is set, it causes automatic instantiation of a single device of a multiple‐device plugin. The name of the device will be the same as the name of the device type and the address field will be an empty string.

Note: The device does not immediately become available if a “protected” dongle is used. A suitable password must be entered at the Configure RIP > Extras dialog.

DEV_FLAG_LASERBUS

This flag is obsolete.

DEV_FLAG_MEGABUFFER

This flag is obsolete.

DEV_FLAG_DOUBLEFACET

This flag is obsolete.

DEV_FLAG_SUPPORTS_STOPSTART

This flag is obsolete.

xNegEnhance, yNegEnhance (HqnDeviceCapabilities)

xNegEnhance, yNegEnhance N

Type: int32

The plugin should ignore these fields. They are obsolete.

hasExposure (HqnDeviceCapabilities)

hasExposure Rw

Type: int32

This should be set to a non‐zero value if the output device has software‐controlled exposure. Doing so allows the user to enter a value in the Exposure field in the page setup and Output Controller Info dialogs. That value is then passed to the plugin in the pageHeader structure sent with each page.