(v13) RasterDescription

To view v13.x documentation, go to the top level of the legacy documentation.

This page applies to Harlequin v14.0r0 and later; and to Harlequin Core but not Harlequin MultiRIP.

The SDK's RasterDescription structure is the main method for passing data from the RIP to your raster output backend code. RasterDescription is defined in the SDK's lib/skinkit/export/skinras.h include file. For information see the Doxygen documentation supplied either as a compiled help file (.chm ) or as an HTML file tree with the SDK release for full details of the fields.

A method of passing structured data through from the RIP to the backend allows you to set page device parameters in the RIP and access them in the raster backend code without having to modify any SDK code. Global Graphics recommends transitioning any existing code that relies on modifying the skinkit pgbdev.c file to use this new method. For details of this method see (v13) Structured data parameters for raster handlers.

The following list shows fields of RasterDescription , the main structure describing the raster produced by the RIP.

• double xResolution This is the output resolution in the X (fast scan) axis measured in dpi (dots-per-inch).
• double yResolution This is the output resolution in the Y (slow scan) axis measured in dpi (dots-per-inch).
• int32 imageNegate This is a Boolean indicating whether the raster handler should negate the image. imageNegate is set to TRUE by the RIP if the raster handler should negate the image, FALSE if it should leave it as is.
• int32 mediaSelect This selects the cassette or paper tray to be used (as determined from inputAttributes in setpagedevice).
• int32 leftMargin This indicates the left margin of the raster (to be added or recorded by the raster handler), measured in pixels.
• int32 rightMargin This indicates the right margin of the raster (to be added or recorded by the raster handler), measured in pixels.
• int32 topMargin This indicates the top margin of the raster (to be added or recorded by the raster handler), measured in pixels.
• int32 bottomMargin This indicates the bottom margin of the raster (to be added or recorded by the raster handler), measured in pixels.
• int32 imageWidth This value defines the width of the image, measured in pixels.
• int32 imageHeight This value defines the height of the image, measured in pixels.
• int32 dataWidth This defines the number of bits in a scan line (including the padding and multiple bits per pixel) and is divisible by 32 for 32-bit RIPs and 64 for 64-bit RIPs.
• int32 bandHeight This defines the number of scan lines in a band. For band interleaved formats this height specifies the height for a single channel.
• int32 noCopies This value defines the number of copies of this page to be printed (in total).
• int32 jobNumber This is a unique number for this job, as determined by the core RIP. A core RIP job is defined by a trip around the core server loop. This number may not match the job number as submitted by the RIP skin, because a single input file may contain more than one core server loop iteration. This is typically the case for PostScript configuration or installation jobs using startjob or exitserver, and for configuration-only jobs submitted through the input queue or SwLeJobStart(). This is not the same as the job number submitted by SwLeJobStart() or the inputq_print_job() functions. To get access to the job number used by these functions, see skinJobNumber.
• int32 pageNumber This is a unique number for this page; reset to 1 at the start of each core RIP job.
• int32 pageNumberOffset A value supplied by the user or configuration that can be added to the page number to identify a page extracted from a range. This is just passed through from the setpagedevice calls; the RIP itself does not ascribe semantics to it or set it itself. Harlequin Core Scalable RIP configuration uses this offset to identify page ranges in jobs split across multiple processes, so you should not set page offsets if using a Scalable RIP.
• int32 ripID The Farm RIP ID in a Scalable RIP environment. This is zero if not running in a Scalable RIP environment, or greater than zero when running as a Scalable RIP's Farm RIP.
• int32 documentNumber No longer used; remains at zero.
• uint8 jobName[512] This is a zero-terminated string containing the name of the job. The job name is typically not the filename or stream name indicating the job's source, but a name set from the job's metadata.
• int32 runLength This is a Boolean indicating if the raster is run length encoded. It is TRUE if the raster uses the Harlequin RLE format, FALSE if the raster is a contone tonemap or screened bitmap.
• int32 outputAttributes This indicates the bin into which the output is placed as derived from outputAttributes in setpagedevice .
• int32 screenDataCount, ScreenData *pScreenData This is the number of screen items in the screenData structure list and the ScreenData list. ScreenData is used only in conjunction with RLE output. For more details on ScreenData see the Harlequin RIP Run-length Output Format document.
• int32 insertSheet This Boolean indicates that the raster is a special sheet that should not normally go through the normal mechanical route on a printer (for example, a transparent cover sheet). The interpretation of this parameter depends on the raster handler. Most implementations will issue a blank page. insertSheet is TRUE if this raster represents a special sheet, FALSE normally. This value is derived from InsertSheet in setpagedevice.
• int32 numChannels This is the number of colorant channels in the raster. Note that some of these channels may be blank (for example, when separating to a band interleaved device). Also, where the setup has permitted extra spot colorants there may be more channels than the fixed colorants originally specified by the PostScript language. Note that for a monochrome device, this is always 1 it is not the total number of separations.
• int32 interleavingStyle The interleaving style of the raster, indicating how colorants are laid out in the raster data. This takes one of the values:

• int32 rasterDepth The number of bits per channel. Individual backends should impose their own restrictions on the image depth and interleaving styles they support, rejecting unsuitable rasters in the RASTER_start() function call. Monochrome, separated, and composite halftones (/Halftone true) can be 1, 2, 4 or 8 bits. Halftones with bit depths of 3, 5, 6 or 7 bits are delivered in either 4 or 8-bit packets, to allow them to be aligned to byte boundaries. That is, a 3-bit (8level) halftone may be supplied as either 1 or 2-pixels-per-byte. For more information see the Extensions Manual, "Continuous tone and color printers".

• int32 packingUnit The size of chunks into which data is packed, high bit first. This is 8 or 16 for contone rasters, 32 or 64 for halftone rasters. This is the machine word width which can be used to extract and manipulate the raster data.
• RasterColorant * pColorants A list of colorants represented in this raster. The RIP maps colorants onto channels (possibly none to some channels, possibly more than one to others); these are identified by RasterColorant structures. There are numChannels channels (which may not correspond to the number originally set up in the PostScript language if it permitted the dynamic addition of extra spot colors). The number of colorants is determined by the length of the linked list. For example, a four-color dye sublimation printer normally would be configured to receive four channels, in the order for the ribbon interleaving. In composite use, typically each of the four colorants corresponding to the ribbon's colors would be mapped to the corresponding channel of raster data. However, separations sent to such a device would still require a four-channel raster, but the only colorant would be mapped to the channel corresponding to the blackcolored ribbon. The contents of the RasterColorant structure are:

• uint8 colorantFamily[64] This is the colorant family to which the colorants of this raster belong.
• int32 separation The current separation number, not taking into account separation omission. This is a one-based index of separations before omission – it can exceed nSeparations in the final render. The separation number is zero when testing blank page handling using the callback function set by SwLeSetBlankPageFunction().
• int32 nSeparations The number of separations produced for this page. This will be for composite output modes; it may be greater for separating modes.
• uint8 pageBufferType[32] An indicator of the overall output methodology, copied from the /PageBufferType pagedevice key.
• uint8 outputTarget[32] The output target for the raster handler. Some raster handlers may be able to deliver the raster to different destinations (e.g., file, network socket, memory, data sink).
• uint8 partialPaint A Boolean indicating if this raster is a partial paint, and should be retained by the raster handler or skin. This Boolean is TRUE if this raster is a partialpaint, FALSE if this is the final paint for this page.
• int32 duplex A Boolean indicating if the output is to be printed duplex. This is derived from the pagedevice's /Duplex setting.
• int32 tumble A Boolean indicating whether duplex output should be printed with long-edge and short-edge binding reversed. The default setting depends on the page layout and orientation. This is derived from the pagedevice's /Tumble setting.
• int32 orientation An integer indicating the number of 90-degree rotations applied to the page layout. This is derived from the pagedevice's /Orientation setting. For information see the Extensions Manual about the interactions between Orientation, ExtraOrientation, and the page layout.
• int32 collate A Boolean indicating whether the raster handler should collate copies of the output. This is derived from the pagedevice's /Collate setting.
• int32 outputFaceUp A Boolean indicating whether output should be delivered face up (if possible). This is derived from the pagedevice's /OutputFaceUp setting.
• uint32 OptimizedPDFUsageCount This integer indicates how many times this page is used as a base layer by other pages, when eHVD is enabled. The raster handler can use this to determine how many times a page uses this layer, and request deletion of the base page once all of the pages using it have been processed. The raster handler needs to note all of the pages and layers associated with a job, and remove them all once the job is complete or fails.
• uint8 OptimizedPDFId[32] If this does not contain an empty string (zero in the first byte), it contains a 32-character hexadecimal string representing a unique ID for this page. If an ID is presented, the page should be stored for later use. It will have another page or pages placed on top of it later. For information see Harlequin VariData.
• int32 OptimizedPDFPositionIndependent This is a Boolean, indicating whether eHVD is position independent. If eHVD is active, it is position independent if this Boolean is TRUE.
• struct { int32 y1, y2, advance ; } band When reading or writing data, this structure indicates the range of scanlines in the band. y1 and y2 are the inclusive start and end scanline for the band, represented as a line within the entire frame set. For frame interleaved mode, the line within a single frame may be computed by taking the scanline modulo imageHeight. A band index within a frame set may be computed by taking the line within frame (as computed above), and dividing by bandHeight. The line advance is the number of scanlines to advance the write position after outputting. This may be zero if multiple output passes are made for the same band. This may happen when doing RLE output, or for some other special raster processing modes.
• int32 separation_id This is an omission-independent separation ID. When performing partial paints, the RIP always renders all separations and channels, regardless of whether there is any data on them. The RIP cannot predict whether objects are painted in appropriate colorants in future. On the final output pass, separations and channels with no objects painted on them may be omitted. This ID is guaranteed to remain the same between partial paints and the final paint for any page, allowing the raster handler to skip omitted channels and separations, and to re-load and paint the correct separation data on the final paint.
• int32 trim_start If trim_page is TRUE , the raster data output may be smaller than imageHeight, because blank bands may be removed from the start and end of the page. This is the zero-based index of the first line of the raster actually output.
• int32 trim_end If trim_page is TRUE , the raster data output may be smaller than imageHeight, because blank bands may be removed from the start and end of the page. This is the zero-based index of the last line of the raster actual output.
• int32 trim_page This is a Boolean indicating whether blank lines may have been trimmed from the top and bottom of the page. It will only be TRUE if the pagedevice parameter TrimPage was enabled.
• uint8 ColorName[1024] A representative name for this raster. If the raster represents a single colorant, then the colorant name will be used. If the raster is composite, or if more than one colorant is mapped onto a channel, then the name includes whether the page was composite, progressive, or separations, and maybe if it is the sole raster for the page or one of a number of rasters. The name is unique within the rasters for this page.
• intptr_t band_owner The band owner for use in the SWMSG_BANDS_HANDLED message. This is only relevant if the raster handler is taking responsibility for returning bands to the RIP asynchronously.
• int32 skinJobNumber The job number created or supplied to the skin when submitting a job through SwLeJobStart() or inputq_print_job(. This job number is attached to the SWTLT_SKIN_JOB timeline as the SW_SKIN_JOB_NUMBER_CTXT context. In a Scalable RIP, this is also the Scalable RIP job ID.
• sw_datum *rasterParams Optional structured data for raster parameters. For full details see (v13) Structured data parameters for raster handlers If the raster backend wishes to access these parameters after the page is finished, it should either unpack them into its own variables, or use the sw_data_api retain() and release() methods to preserve the data tree.
• int32 separationCount The current (1-based) separation index, taking into account separation omission. This count equals nSeparations when outputting the final separation of a non-blank page. It is zero when testing blank page handling using the callback function set by SwLeSetBlankPageFunction().
• int32 PageRelativeBBox[4] From Harlequin v13.0r0, the Harlequin Core SDK's RasterDescription structure has a bounding box array in it, called pageRelativeBBox. This is populated from the PageRelativeBBox parameter on the pagebuffer device.

This bounding box is the device space (x1 , y1 , x2 , y2 ) offsets from the raster provided to the full-page area. If the raster provided takes the entire PageSize , then the offsets are (0 ,0 ,0 ,0 ). Since the tiles are restricted to the page size, the first (x1 , y1) offsets are either zero or negative, and the (x2 , y2 ) offsets are zero or positive.

PageRelativeBBox can be set by using tiling. For information see the Harlequin Extensions Manual , “Tiling operators” or “ImagingBBox, TileDeviceBBox”.

See the %t /%T tags to the -f clrip command-line option in (v13) Using the clrip application for inclusion of the PageRelativeBBox in output file names.

The relationship between the bounding boxes, margins, and output raster size are shown in the following diagram:

Figure: Relationship between the bounding boxes, margins, and output raster size