Skip to main content
Skip table of contents

(v13) The deviceDefinition structure

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

All output plugin selector calls pass a pointer to a deviceDefinition structure. It is the central data structure in output plugin operations. The RIP instantiates it as soon as it starts up the plugin.

The structure is defined in the header file gdevdefs.h . Its current version number is given by the manifest constant DEV_DEF_VERSION in the same file.

The plugin should only modify values that it is allowed to change in the deviceDefinition structure during a plugin selector call. This is especially pertinent for plugins that create a separate thread to perform work on. Updates to the deviceDefinition fields, especially d_linescopied , d_linesprinted , d_error , and d_feeding should be deferred until a plugin selector is called. How‐ ever, the TL_PLUGAPI_LINES_COPIED timeline may have its progress updated outside of a selector call, by a separate thread.

Note: d_frames , d_longfilenames are omitted as they are deprecated.

    struct deviceDefinition {
      void *d_storage;
      driverFn *d_driver;
      int32 d_error;
      int32 d_lastpagebuffered;
      int32 d_linesripped;
      int32 d_linesfreed;
      int32 d_linescopied;
      int32 d_linesprinted;
      int32 d_stopstarts;
      int32 d_ripband;
      int32 d_freebands;
      int32 d_maxbands;
      uint32 **d_bands;
      int32 *d_compression;
      int32 d_linesperband;
      struct pageHeader *d_page;
      struct bufDef *d_buf;
      void *d_private ;
      int32 d_needsidle;
      int32 d_lasterror;
      int32 d_open;
      int32 d_devicetype;
      int32 d_feeding;
      int32 d_linesfed;
      int32 d_lastmedia;
      void *d_driverstore;
      int32 d_version;
      void *d_libglobals;
      int32 d_outmonitor;
      char *d_SWDir;
      int32 d_answer;
      int32 d_frames;
      int32 d_longfilenames;
      char d_PlgDir[OP_MAX_SUBDIR]; struct deviceCapabilities *d_capabilities ;
      struct deviceConfig *d_config ;
      char *d_address;

d_storage (deviceDefinition)

d_storage Wrw

Type: void*

The plugin can use this field to store a pointer to any data it needs to associate with the device. The RIP clears this field prior to calling D_INITIALISE . It never accesses it again after doing so.

d_driver (deviceDefinition)

d_driver N

Type: driverFn*

The plugin should ignore this field. The RIP uses it to note the plugin entry point. The type driverFn is defined in gdevdefs.h .

d_error (deviceDefinition)

d_error WRw

Type: int32

The plugin should use this field to pass error codes back to the RIP.

The field can be thought of as two subfields: the high‐end four bits contain a 4‐bit error type , and the low‐end twelve a 12‐bit error code .

The error type determines how the RIP responds to the error condition. The error code is a description of the cause of the error condition.

All the error types and codes are defined as manifest constants in the header file gdeverrs.h . Error type names have the prefix DETYPE_ ... while error codes have the prefix DERR_ The error code list

may be extended by OEMs, and supporting icons and error text added for any such extensions. In addition, gdeverrs.h defines some macros that can be used to combine error types and codes into a single value for storage in d_error , and to extract them in turn from such a value.

Error types, error codes, and error macros are described in (v13) Error Handling in Output Plugins .

d_lastpagebuffered (deviceDefinition)

d_lastpagebuffered N

Type: int32

The plugin should ignore this field. It is obsolete.

d_linesripped (deviceDefinition)

d_linesripped Wr

Type: int32

The number of lines of data D_OUTPUT has made available to the plugin since the start of the current page.

You must also always ensure that:

d_linesripped >= d_linescopied >= d_linesprinted

d_linesfreed (deviceDefinition)

d_linesfreed N

Type: int32

The number of lines of buffer space available to the RIP after having been used and released by the plugin. This value must not be updated by the plugin.

d_linescopied (deviceDefinition)

d_linescopied WRw

Type: int32

The number of lines of data that the plugin has read from the buffer. The plugin should update this field after it has copied the data and no longer needs it. Thus, releasing the space for reuse by the RIP.

A plugin often cannot process all data supplied with D_OUTPUT immediately. If this is the case, d_linescopied can be updated during a D_IDLE call.

The RIP sets d_linescopied to zero before calling D_OPEN . See Note in d_linesprinted (deviceDefinition) below.

d_linesprinted (deviceDefinition)

d_linesprinted WRw

Type: int32

The RIP sets d_linesprinted to zero at the beginning of each page, before the D_OPEN request is sent.

The number of lines of data that have actually been printed. The plugin should keep this field up to date. It should always be less than or equal to d_linescopied , and never exceed
d_page->imageHeight * d_frames .

When the RIP has finished ripping a page and has sent all the band data for it to the plugin, it repeatedly calls D_IDLE , until d_linesprinted reaches the number of lines in the page,
d_page->imageHeight * d_frames .

Sometimes, at the end of the page, it is reasonable to report that lines have been printed before the printing is actually complete, so that the RIP can continue with other pages. You should only do this if you can be sure that no errors will be detected, and that the printing will complete without the need for further action from the plugin.

Note: When setting d_linescopied and d_linesprinted , you must ensure that their values are between 0 and d_page->imageHeight * d_frames .

You must also always ensure that
d_linesripped >= d_linescopied >= d_linesprinted

d_stopstarts (deviceDefinition)

d_stopstarts Rw

Type: int32

The plugin should increment d_stopstarts each time the device goes through a stop–start cycle (a data “underrun”). The value in this field is used to determine whether to re‐rip the entire page to disk, thereby ensuring a high data rate for complicated jobs.

The RIP sets d_stopstarts to zero at the beginning of each page, before the D_OPEN request is sent.

Note: If stop–start cycles do not affect print quality on the output device, there is no need to increment this field.

The RIP only checks whether this field is greater than zero: if it is, and stop–starts are not enabled in the Configure RIP dialog, the RIP signals an error. When the RIP is in single output modes, the entire page is ripped to disk and then output again. In multiple output modes, the error results in the stored page being output again.

d_ripband (deviceDefinition)

d_ripband N

Type: int32

The plugin should ignore this field. The RIP uses it for internal housekeeping related to the d_bands array.

d_freebands (deviceDefinition)

d_freebands N

Type: int32

The plugin should ignore this field. The RIP uses it for internal housekeeping related to the d_bands array.

d_maxbands (deviceDefinition)

d_maxbands Wr

Type: int32

The RIP may change the address stored in the d_bands array before D_OPEN . So, you cannot assume that the band address remains in the order that they original happen.

The order of the d_band addresses may change between D_OPEN and D_CLOSE . When you get a D_OUTPUT you either have to reload the address, given the band number you are given, or you have to use the band address provided with the D_OUTPUT call.

The RIP waits until the plugin has finished with each band (as indicated by d_linescopied ) before refilling it

The order is unpredictable, so use the band address in D_OUTPUT .

This value will not change between the D_OPEN and D_CLOSE calls for a particular page, but may be different for successive pages.

d_bands (deviceDefinition)

d_bands Wr

Type: uint32** /uint64**

A circular buffer of d_maxbands elements which give the base address of each band within the page. Though declared as uint32** , the type of d_bands can be regarded as:
uint32 *d_bands[devdef->d_maxbands];

Note: Even though declared as a uint32 it will be 64‐bit aligned on a 64‐bit platform.

The plugin need not be aware of this data structure, since it is given the address of the data to be out‐ put with each D_OUTPUT request. However, in an asynchronous plugin the actual act of output may well be deferred, perhaps making it easiest to log the number of lines supplied by D_OUTPUT , and use d_bands to locate the data when it is needed by calculating from d_lineprinted .

For asynchronous output using D_IDLE , which is typical of non‐file devices, it is common to use a private currentBand counter, which, modulo d_maxbands , indexes into d_bands .

d_compression (deviceDefinition)

d_compression N

Type: int32

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

d_linesperband (deviceDefinition)

d_linesperband Wr

Type: int32

The number of lines of raster data held in each band.

Note: The last band of the page is usually an exception, having fewer lines than this when d_linesperband is not an even multiple of the raster height (imageHeight * d_frames) .

d_page (deviceDefinition)

d_page Wr

Type: pageHeader*

A pointer to the pageHeader structure, which describes the current page. See (v13) The pageHeader structure for details of the pageHeader structure.

The d_page sub‐structure should not be accessed in the D_OPEN_ENDJOB ...D_CLOSE_ENDJOB sequence. It is only valid between D_OPEN and D_WAIT_ON_CLOSE . In particular, the plugin private data sub‐pointer is not valid after the final D_WAIT_ON_CLOSE .

Note: This pointer cannot be assumed to point to valid and current page information until the D_OPEN selector call is made.

d_buf (deviceDefinition)

d_buf N

Type: struct bufDef*

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

b_form (deviceDefinition)

b_form N

Type: IMGFORM b_form

The basic image form.

b_trimstart (deviceDefinition)

b_trimstart N

Type: int32

The band number of the first non‐white band.

b_trimend (deviceDefinition)

b_trimend N

Type: int32

The band number of the last non‐white band +1.

b_maxband (deviceDefinition)

b_maxband N

Type: int32

The total number of bands in the buffer when not trimmed.

d_private (deviceDefinition)

d_private Wr

Type: void*

A pointer to a platform‐specific data area. For more details, refer to the platform specific appendices of this document. d_private can be used to store a pointer to a private area of allocated memory and can be used in case where global memory cannot be used.

d_needsidle (deviceDefinition)

d_needsidle N

Type: int32

Set by the plug‐in when d_idle() is required.

d_lasterror (deviceDefinition)

d_lasterror N

Type: int32

The plugin should ignore this field, and use its own error status system. The RIP uses it for internal purposes.

d_open (deviceDefinition)

d_open N

Type: int32

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

d_devicetype (deviceDefinition)

d_devicetype Wr

Type: int32

This is derived from the deviceType field of the HqnDeviceCapabilities structure and is a combination of flag bits denoting roll or sheet media handling properties. See (v13) The HqnDeviceCapabilities structure for details of HqnDeviceCapabilities .

d_feeding (deviceDefinition)

d_feeding Rw

Type: int32

The plugin should set this to a non‐zero value to indicate that it is outputting or feeding film.

In practice, this is set by the plugin when the RIP calls D_OPEN , and cleared when the output is complete, or possibly when it can be completed without any further action on the plugin's part. If it is not set when the RIP calls D_OPEN , it can be set if required when the RIP calls D_OPEN_ENDJOB .

D_CLOSE is called when page output is complete, or after the user requests that the plugin abort output of the page. However, when d_feeding is set the plugin needs more processing time and D_CLOSE and D_CLOSE_ENDJOB cannot be called. When d_feeding is not set D_CLOSE and D_CLOSE_ENDJOB can be called.

Setting d_feeding means that D_IDLE can be sent repeatedly after D_OPEN_ENDJOB . Subsequently reset‐ ting d_feeding to zero means that D_CLOSE_ENDJOB can be sent, to signal the end of the page.

If d_feeding is never set, a D_CLOSE_ENDJOB immediately follows the D_OPEN_ENDJOB .

d_linesfed (deviceDefinition)

d_linesfed Rw

Type: int32

The plugin should set this to the number of lines of media that were fed, in addition to the number of lines output while recording the image on roll media. It is not used with sheet media.

This value, along with d_linesprinted , is used by the Media Manager to log the amount of film used. It is only relevant to capstan‐feeding devices where the media is consumed as the job is imaged, rather than all at once at the start of the page.

d_driverstore (deviceDefinition)

d_driverstore N

Type: void*

The plugin should ignore this field. The RIP uses it to locate the plugin.

d_libglobals (deviceDefinition)

d_libglobals N

Type: void*

The plugin should ignore this field. It is used by plugin library functions to pass information between the plugin and the RIP.

d_outmonitor (deviceDefinition)

d_outmonitor N

Type: int32

The plugin should ignore this field. It is used by plugin library functions to pass information between the plugin and the RIP.

d_SWDir (deviceDefinition)

d_SWDir Wr

Type: char*

A pointer to a string containing the pathname of the SW directory. On a PC this string might be:


The plugin could use this string as the default location for any files it deals with See also, d_PlgDir (deviceDefinition) .

This field is encoded using the Harlequin character encoding scheme (HES).

d_answer (deviceDefinition)

d_answer Wr

Type: int32

When the plugin asks the user, a question using the plugin library mechanism (see (v13) Messaging functions ), the user's answer is passed back to the plugin in this field. It can be one of the following values, defined in the enumeration plugAnswer in gplugin.h :


The answer was “yes”.


The answer was “no”.


No answer received yet.

This field does the same thing for output plugins as the answer field of ipPluginContext does for input plugins.

d_frames (deviceDefinition)

d_frames WRr

Type: int32

This is the number of colorants that are being iterated through for a single output page. Given that each page is imageHeight * d_frames scan lines high, and that the d_linesXXXX do not reset at the end of a colorant, then the lines increment from 0.              d_frames*imageHeight .

For more information see: d_linesripped (deviceDefinition) , d_linesfreed (deviceDefinition) and d_linescopied (deviceDefinition) .

d_longfilenames (deviceDefinition)

d_longfilenames Wr

Type: int32

If necessary, a plugin can determine whether the system is running with long or short filenames by looking at this flag. Generally, d_longfilenames is set to TRUE .

d_PlgDir (deviceDefinition)

d_PlgDir Wr

Type: char[OP_MAX_SUBDIR].

The subdirectory of the SW folder from which the plugin executable was loaded, including a terminating directory separator, so the plugin can access data files by concatenating their names to the value of d_SWDir . See also (v13) Plugin directory .

This field is encoded using the Harlequin character encoding scheme (HES).

d_capabilities (deviceDefinition)

d_capabilities Wr

Type: struct deviceCapabilities*

Pointer to the HqnDeviceCapabilities structure for the device to which the deviceDefinition refers, as originally provided by the plugin. This effectively makes the D_SELECT_DEVICE selector redundant, since the capabilities structure normally contains the information to identify the device type.

d_config (deviceDefinition)

d_config Wr

Type: struct deviceConfig*

Pointer to the config structure originally provided by the plugin during the D_CAPABILITIES call. See (v13) D_CAPABILITIES .

d_address (deviceDefinition)

d_address Wr

Type: char*

Pointer to the character string forming the address provided by the user when instantiating a device type in the Device Manager. The string capacity is 256 bytes, making it useful for password entry, as well as setting an I/O address range.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.