|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
The tiling method API is used to sub-divide a page or HVD element, represented by a device space bounding box, into a series of tiles. More...
Files | |
| file | tileapi.h |
| Header file defining the Tiling method API. | |
Data Structures | |
| struct | sw_tile_bbox |
| Definition of a device space tile bounding box. More... | |
| struct | sw_tiling_api_20190924 |
| The tiling method API. More... | |
Typedefs | |
| typedef HqnResult | sw_tile_result |
| Return status of the tiling API functions. More... | |
| typedef struct sw_tile_iteration_opaque * | sw_tile_iteration |
| Opaque definition of a tiling iteration. | |
| typedef struct sw_tiling_api_20190924 | sw_tiling_api_20190924 |
| The tiling method API. | |
Enumerations | |
| enum | SW_TILE_RESULT { SW_TILE_SUCCESS = HQN_RESULT_SUCCESS , SW_TILE_ERROR , SW_TILE_ERROR_PARAMS , SW_TILE_ERROR_MEMORY } |
| Return codes for API calls. More... | |
Functions | |
| HqnResult | tileapi_result_translate (sw_tile_result result) |
| Translate a tiling API-specific error code to a generic HqnResult error code. More... | |
The tiling method API is used to sub-divide a page or HVD element, represented by a device space bounding box, into a series of tiles.
When rendering PDF or any of the image formats supported by the HqnImage procset (such as TIFF or JPEG input), the Harlequin RIP can tile pages. Tiling is not supported for PostScript, EPS, or GIF input. Tiling allows very large pages to be split over multiple RIPs and processed in parallel, and it may lower peak memory usage to process large pages. The PostScript language configuration for Tiling is described in the Extensions Manual.
Each implementation of the tiling method API defines an algorithm to produce a series of device-space tile bounding boxes, given: a page or element number, a device-space bounding box, and configuration parameters for the algorithm. Tiling methods may be implemented in either the RIP core or RIP skin.
Implementations of the tiling method API are represented using sw_tiling_api_20190924 structures. These are registered in RDR as Named RDRs, using the RDR_NAMES_TILEAPI namespace, the name under which the tiling method is selected by settilingparams as the name, and the tiling API version number (20190824) as the ID. The data registered in RDR is a pointer to the API structure, and the length of the API structure:
You can register the tiling method instance at any time before making the settilingparams call to configure it. Registration does require RDR to be active, so can be performed at any time after the Harlequin RIP SDK is started, until the Harlequin RIP SDK is shutdown.
The RIP core looks up the configured method for a particular context (/Page, /HVDPage, or /HVDElement) by getting the /Method key from the current tiling parameters dictionary, and looking up the named instance in RDR.
The Harlequin RIP SDK defines three implementations of the tiling API, which you can use for tiling as-is, or use as a model for your own tiling methods. These are:
The Harlequin SDK registers these implementations when the SDK is started.
The RIP makes a call on the tiling method API when configured for tiling using the settilingparams operator. An initial call validates parameters during settilingparams. When a page or element configured for tiling is about to be rendered, additional calls start a tiling iteration, count the number of remaining tiles in a tiling iteration, get a number of the remaining tiles in the tiling iteration, and end the tiling iteration. More than one tiling iteration may be in progress simultaneously, so tiling method implementations should use the iteration handles to contextualize their operation.
The initial call made during settilingparams is sw_tiling_api_20190924::validate(). This is given a data API datum parameter that can be used to extract the configuration parameters provided in the settilingparams method sub-dictionary. An error can be returned if the parameters are not valid or appropriate.
When the RIP is ready to render a tiled page or element, it will call sw_tiling_api_20190924::start_tiling(). This is also given a data API datum parameter that can be used to extract the configuration parameters provided in the settilingparams method sub-dictionary. It should check that the parameters are valid, and not assume that the validate() method was sufficient. If successful, this method returns a tiling iterator, which will be used by the remaining method calls.
The sw_tiling_api_20190924::count_tiles() method may be called to return the number of tiles remaining in an iterator. The return value may be zero, if there are no tiles left. The sw_tiling_api_20190924::get_tiles() method will be called request a number of tiles. The number of tiles requested may be larger than the number of remaining tiles in the iterator, so this method will update the number of tiles and store device space bounding boxes for all tiles returned in the locations provided for them.
When all tiling iteration has been performed, the sw_tiling_api_20190924::end_tiling() method will be called to free any resources used by the tiling iterator. This method is always called if the start_tiling() method was successful, even if an error occurred in extracting or processing tiles.
When outputting a tiled page, the raster output backend receive bands of data as normal. The only difference it may notice is the the RasterDescription::pageRelativeBBox array will have non-zero values in it. This indicates that this raster is part of a larger overall page, and indicates where in the page the raster is located. For information and a diagram of the page relative bounding box relation ship to the page, see Raster bounding boxes, margins and size.
When tiling parameters are specified for a job (see settilingparams operator in the Extensions Manual), the Scalable RIP schedules tiles to Farm RIPs. There are two different ways this is done, depending on the setting of ScheduleIndividualTiles in the RIP Farm JSON configuration ripfarm_global.json file:
ScheduleIndividualTiles is false, all the tiles in a page range are scheduled to a single Farm RIP. For example, if the chunk size is 2 and we have two Farm RIPs processing a 10-page job, all tiles for pages 1-2 are scheduled to one of the Farm RIPs; all tiles for pages 3-4 are scheduled to the other Farm RIP and so on for pages 5-6, 7-8, and 9-10 as RIPs become free.ScheduleIndividualTiles is true, each tile on a page is scheduled to any Farm RIP that happens to be free. Tiles within a page range are scheduled first. For example, if the chunk size is 2 and we have two Farm RIPs processing a 10-page job, all tiles are from the first page are scheduled to both the first Farm RIP and second Farm RIP. When all tiles from the first page are scheduled, tiles from the next page are scheduled and so on. As another example, a 1-page job with 100 tiles on the page shares the tiles between the two Farm RIPs; if ScheduleIndividualTiles was false, a single Farm RIP processes all the tiles, while the second Farm RIP remains idle.If /HVDElement tiling has been specified, ScheduleIndividualTiles is assumed to be false. This means chunks of pages are always sent to individual Farm RIPs that do their own HVD scanning in isolation, taking into account any tiling parameters specified. This is because we cannot pre-scan /HVDElement tiles in the controlling RIP to determine the elements that will be produced.
If there is no /HVDElement specified but /HVDPage is specified, the HVD page tiles are scheduled based on the ScheduleIndividualTiles value, but with slightly different semantics to those described above:
ScheduleIndividualTiles is true and the set of tiles for all pages are identical across the entire job, a chunk of pages is sent to a Farm RIP but with one tile selected for all pages in that HVD page range. This means the first page range is processed in parallel, improving first page output time.ScheduleIndividualTiles is false, chunks of pages are sent to Farm RIPs to process every tile on every page in that page range. This is the same behavior as described above. | typedef HqnResult sw_tile_result |
Return status of the tiling API functions.
This is a subclass of HqnResult that also supports some specific extra error codes generated by tiling API functions (declared as the SW_TILE_RESULT enumeration). Before assigning to values of HqnResult type or any of its other subclasses, sw_tile_result values must be converted to change the API specific values to HQN_RESULT_SUCCESS or a monitor UID error code greater than MON_CLASS_ERROR. This can be done by calling the function tileapi_result_translate().
| enum SW_TILE_RESULT |
| HqnResult tileapi_result_translate | ( | sw_tile_result | result | ) |
Translate a tiling API-specific error code to a generic HqnResult error code.
| [in] | result | One of the SW_TILE_RESULT values, or an error value greater than MON_CLASS_ERROR. |