(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:
C:\RIP\SW\
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.