(v13) Using the raster manager output API in Scalable RIP

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

There is one API method that the raster backend should use to inform the Scalable RIP raster manager about rasters. The raster_ready () method adds a raster reference to the set of rasters for a particular page in a Scalable RIP job. It may optionally indicate that all of the rasters for a particular page have been added, or may be called multiple times for additional rasters associated with the page. There may be any number of rasters for a page in a Scalable RIP job, including zero; the number of rasters may vary for each page; the data format of each raster in a page may vary; the storage and location of each raster in a page may vary. The raster backend must call the raster_ready () method with the rasters complete Boolean parameter TRUE when all of the rasters have been sent to the raster manager.

The raster manager API has some utility methods to assist with creation and destruction of objects, and constructing location description strings. These are documented in the HHR SDK Doxygen.

Usually, the raster backend finish function will communicate the raster information for a page:

TEXT

                      /* In your raster backend finish function: */
                      static int32 RIPCALL RASTER_finish(void *pJobContext,
                                          RASTER_handle *phandle, RasterDescription *rd, int32 result)
                      {
                        int32 result = RASTER_noErr ;
                        ...
                          if ( rm_output_api != NULL ) { RF_RASTER *raster = NULL ; RF_ERROR *rferror = NULL ;
                          char *location = rm_output_api->get_location("%B") ;
                          /* Use Blade location for this raster */
                                  if ( (raster = rm_output_api->raster_create(my_raster_name, location, "TIFF" /*data format*/,
                                  NULL /*optional metadata*/)) == NULL ||
                                  !rm_output_api->raster_ready(rd->skinJobNumber /*job ID*/, rd->pageNumber + rd->pageOffset /*page ID*/,
                                  &raster /*raster object is always consumed*/, NULL /*optional callback function*/,
                                  NULL /*optional callback data*/,
                                  rd->separationCount == rd->nSeparations /*page complete?*/,
                                  &rferror) ) {
                            /* Handle output failure... */ result = RASTER_fileOutputErr;
                          }
                          rm_output_api->free_object(location) ; rm_output_api->free_object(rferror) ;
                        }
                        ...
                        return result ;
                      }

If you plan to use separation omission, the raster backend should also have a blank page handling function registered. To register the blank page handling function, use SwLeSetBlankPageFunction() after SwLeSetRasterCallbacks() wherever you select the raster backend. The blank page function should override the default action for blank pages due to separation omission, so that the page number is counted in the normal job sequence. It may also override handling of blank pages for other reasons. For example, the following blank page function notifies the raster manager that blank pages detected for any reason should insert a placeholder page with no rasters:

TEXT

                      static int32 RIPCALL RASTER_BlankPage(void *pJobContext,
                          RASTER_BLANK *pBlank, RasterDescription *rd)
                      {
                      int32 result = RASTER_noErr ; if ( rm_output_api != NULL ) {
                        RF_RASTER *raster = NULL ; RF_ERROR *rferror = NULL ;
                        /* Tell the RIP to count this page in the job sequence */ pBlank->action = BLANK_PAGE_COUNT ;
                                    if ( !rm_output_api->raster_ready(rd->skinJobNumber /*job ID*/, rd->pageNumber + rd->pageOffset /*page ID*/, &raster /*NULL raster object*/,
                                    NULL /*optional callback function*/, NULL /*optional callback data*/, TRUE /*page is complete*/, &rferror)) ) {
                          /* Handle output failure... */ result = RASTER_fileOutputErr;
                        }
                        rm_output_api->free_object(rferror) ;
                      }
                      return result ;
                      }

Raster manager output callbacks

The raster output API can optionally call the raster backend for each raster after the Scalable RIP raster manager acknowledges the client DBE has handled a page. If you use this capability, you must be aware that callbacks can happen long after the Farm RIP job has completed, even after the raster backend has been deselected. It is preferable to design the raster backend so that calls to the raster manager do not require callbacks; this especially applies to ownership of rasters created in shared memory. If a raster-ready method succeeds, the raster backend and DBE should preferably be designed so that ownership of shared memory is passed from the raster backend to the DBE. The Scalable RIP raster manager acts as a queue in between these components.