sw_raster_api_20230105 Struct Reference

A structure collecting the raster backend API functions. More...

#include "rasthand.h"

Data Fields
SwLeRASTERBANDSIZE *	band_size_fn
SwLeRASTERREQUIREMENTS *	raster_requirements_fn
SwLeRASTERDESTINATION *	raster_destination_fn
SwLeBLANKPAGECALLBACK *	blank_page_fn
RASTER_START_EX *	raster_start_fn
RASTER_WRITE_DATA_EX *	raster_write_data_fn
RASTER_FINISH_EX *	raster_finish_fn
RASTER_JOB_END_EX *	job_end_fn

Detailed Description

A structure collecting the raster backend API functions.

Field Documentation

band_size_fn

SwLeRASTERBANDSIZE* sw_raster_api_20230105::band_size_fn

Routine via which the RIP allows the skin to affect band size computations.

If an error is returned by this function, the SDK will set the value of the RASTER_BANDSIZE::handled field to TRUE.

Parameters

	pJobContext	An opaque pointer to caller-managed data, as originally provided by inputq_print_job() or SwLeJobStart().
[in,out]	pBandSize	Structure providing details of the raster stride (byte offset between the start address of successive raster lines), and some parameters for the skin to indicate to the RIP whether to limit band size and whether to allocate dynamic bands for asynchronous processing.

Returns

This function should return RASTER_noErr (0) for success; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error; or RASTER_notReady indicate that the RIP should call the skin again.

blank_page_fn

SwLeBLANKPAGECALLBACK* sw_raster_api_20230105::blank_page_fn

A function that the RIP will call when a page is omitted entirely.

If an error is returned by this function, the SDK will set the value of the RASTER_BLANK::handled field to TRUE.

The pRasterDescription pointer has as much information about the omitted page as is known, including the page width and height, but the colorant and channel information is not available.

RASTER_BLANK::handled is a flag which the callee sets when it has decisively dealt with the call. Not setting the flag before returning indicates to the RIP that the callee would like to be called again with the same parameters. This is used when the skin needs to delay to allow some output or other work to progress before the RIP continues, or to split the production of a blank page into multiple passes in order to better suit the rest of the workflow.

Parameters

pJobContext	An opaque pointer to caller-managed data, as originally provided by inputq_print_job() or SwLeJobStart().
handlep	A pointer to a raster handle. This will normally point to a NULL handle, but for raster backends that maintain data across pages, this may point to an existing handle created by a previous blank page, or by RASTER_START_EX. The blank page function may create, destroy, or update the raster handle.
pBlank	The RASTER_BLANK structure shared by RIP and skin.
pRasterDescription	A pointer to a RasterDescription structure describing the size, job, and number of the omitted page.

Returns

This function should return RASTER_noErr (0) for success; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error; or RASTER_notReady to indicate that the RIP should call the skin again.

job_end_fn

RASTER_JOB_END_EX* sw_raster_api_20230105::job_end_fn

A function called at the end of the core job lifetime. This function is only called if sw_raster_api_20230105::raster_start_fn was called.

Implementations can use this call to perform tasks at job scope, such as closing disk files and releasing other platform resources.

Parameters

pJobContext	An opaque pointer to caller-managed data, as originally provided by inputq_print_job() or SwLeJobStart().
handlep	A pointer to the raster handle obtained from RASTER_START_EX

Returns

This function should return RASTER_noErr (0) for success; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error.

Note

This function is called in the Farm RIPs, at the end of some sets of chunks for a job. These calls will not necessarily be at the end of all chunks for a job. You should not rely on this call being at the end of a job when using the Scalable RIP, but it can still be used to clean up any state allocated by raster start and finish functions.

raster_destination_fn

SwLeRASTERDESTINATION* sw_raster_api_20230105::raster_destination_fn

A function which returns a memory range into which the RIP should render a given band. This will only be called if sw_raster_api_20230105::raster_requirements_fn was used to indicate that the skin is in control of band memory allocation.

If an error is returned by this function, the SDK will set the value of the RASTER_DESTINATION::handled field to TRUE.

The use of this callback is optional. Together with SwLeRASTERREQUIREMENTS, it gives a mechanism for the skin to provide all of the memory into which the RIP should render, which in turn eliminates memory copying operations and so improves performance.

For the given frame and band number, the skin should calculate the correct destination range and return it in RASTER_DESTINATION::memory_base and RASTER_DESTINATION::memory_ceiling. This range is exclusive, i.e., RASTER_DESTINATION::memory_ceiling is the address of the first byte that the RIP is not allowed to write into.

RASTER_DESTINATION::handled is a flag which the callee sets when it has decisively dealt with the call. Not setting the flag before returning indicates to the RIP that the callee would like to be called again with the same parameters. This is used when the skin needs to delay to allow some output or other work to progress before the RIP continues, or to split the rendering of a single RIP band into multiple passes in order to better suit the rest of the workflow.

Parameters

pJobContext	An opaque pointer to caller-managed data, as originally provided by inputq_print_job() or SwLeJobStart().
pRasterDestination	The RASTER_DESTINATION structure shared by RIP and skin.
separationIndex	The index of the current separation.

Returns

This function should return RASTER_noErr (0) for success; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error; or RASTER_notReady to indicate that the RIP should call the skin again.

Note

This function does not have a failure return code. This function is used to set the raster destination address associated with a pre-allocated framebuffer, discovered through the raster requirements callback (see the SwLeRASTERREQUIREMENTS callback type). If the framebuffer allocation can fail, the raster requirements call should return the failure code.

raster_finish_fn

RASTER_FINISH_EX* sw_raster_api_20230105::raster_finish_fn

A function called at the end of outputting the data for each separation.

Parameters

pJobContext	An opaque pointer to caller-managed data, as originally provided by inputq_print_job() or SwLeJobStart().
handlep	A pointer to the raster handle obtained from RASTER_START_EX. This function may destroy the handle and reset the value to NULL if operating separation-by-separation, or it may leave the handle intact and rely on the RASTER_JOB_END_EX function to destroy the handle if maintaining data across separations or pages.
pRasterDescription	The raster description for the page
result	RASTER_noErr if the page was output succesfully, otherwise an error value

Returns

This function should return RASTER_noErr (0) for success; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error.

raster_requirements_fn

SwLeRASTERREQUIREMENTS* sw_raster_api_20230105::raster_requirements_fn

Routine via which the RIP informs the skin of its memory requirements, and the skin can allocate the buffers it requires.

If an error is returned by this function, the SDK will set the value of the RASTER_REQUIREMENTS::handled field to TRUE.

The use of this callback is optional. Together with SwLeRASTERDESTINATION, it gives a mechanism for the skin to provide all of the memory into which the RIP should render, which in turn can eliminate memory copying operations and so improve performance.

Parameters

pJobContext	An opaque pointer to caller-managed data, as originally provided by inputq_print_job() or SwLeJobStart().
pRasterRequirements	A pointer to the RASTER_REQUIREMENTS structure shared by RIP and skin.
pRasterDescription	A pointer to a description of the raster data. There are several points in the sequence of processing a job at which the RIP will call this type of function. There will be a set of calls while a page is being interpreted: the first is when the page device has just changed, there are also calls if dynamic separations are added which may affect the raster layout, and also just before the page is handed over for rendering. There will also be a set of calls while the page is being rendered; the first when about to render a pass of a page (i.e., a partial paint, composite, or final render), and secondly before each sheet is rendered. For the calls from interpretation and the render pass call, pRasterDescription will be NULL, and the RASTER_REQUIREMENTS::raster_sheet_index field will be -1. The calls before each sheet will have the pRasterDescription pointer non-NULL and it will contain the finalised description of the raster data, and the RASTER_REQUIREMENTS::raster_sheet_index field will be non-negative.

Returns

This function should return RASTER_noErr (0) for success; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error; or RASTER_notReady to indicate that the RIP should call the skin again.

Note

It may be that the best approach is for the skin to allocate raster memory during the earlier calls to this type of function, i.e., with pRasterDescription is NULL, to ensure that the raster memory is always available. Depending on configuration, it's possible that if raster memory allocation happens later that the RIP uses all available memory and there's not enough left for raster memory when needed. However, if the skin is in a position to guarantee that a later allocation when pRasterDescription is non-NULL will succeed, that approach is preferable - not least because the page device changes quite often - perhaps a dozen or more times per job. When Harlequin Parallel Pages is enabled, calls to this function may be made from both interpreter (pRasterDescription NULL) and renderer threads (pRasterDescription non-NULL) simultaneously. The skin must not assume that a renderer call is related to the most recent interpreter call. The RASTER_REQUIREMENTS::eraseno field can be used to correlate calls from the interpreter with subsequent renderer calls. Not every interpreter call will have an associated call from a renderer. The RASTER_REQUIREMENTS::eraseno field increases monotonically for each raster description, so when a renderer call is received, all buffers allocated for raster descriptions with lower values of RASTER_REQUIREMENTS::eraseno can be discarded.

The RIP will set all fields in the RASTER_REQUIREMENTS argument.

The following fields are used to communicate information back from the raster backend to the RIP:

• RASTER_REQUIREMENTS::have_framebuffer is a flag which the callee can set to indicate that it has will allocate the memory for all of the band buffers (a framebuffer). This can lead to extra efficiencies, by avoiding data copying. For any particular value of the RASTER_REQUIREMENTS::eraseno field, the skin must not change its mind about the setting of RASTER_REQUIREMENTS::have_framebuffer between the interpreter and renderer calls to this function.
• RASTER_REQUIREMENTS::scratch_size may be set in the interpretation calls to request a scratch buffer from the core. The buffer will be provided to the renderer calls in the RASTER_REQUIREMENTS::scratch_band field.
• RASTER_REQUIREMENTS::band_order may be modified by the raster backend to indicate the order in which it can handle bands. This may be changed in the first render call, but not in the per-sheet calls.
• RASTER_REQUIREMENTS::bands_handled_by_caller may be modified by the raster backend to indicate that it takes responsibility for issuing SWEVT_BANDS_HANDLED events. This allows the raster backend to process data in bands asynchronously, returning to the RIP immediately. If DynamicBands are configured, this allows the RIP to render the next band while the backend is processing data.
• RASTER_REQUIREMENTS::store_partial may be modified by the raster backend to indicate how partial paints and transparency compositing passes should be stored.
• RASTER_REQUIREMENTS::copies_handled_by_output may be modified by the raster backend to indicate that it can handle transmitting multiple copies of the same page to the output, rather than have the RIP re-output the page multiple times.
• RASTER_REQUIREMENTS::write_empty_bands may be modified by the raster backend to indicate if it can handle empty bands being skipped either at the start and end of a page, anywhere in a page, or not at all.
• RASTER_REQUIREMENTS::handled is a flag which the callee sets when it has decisively dealt with the call. Not setting the flag before returning indicates to the RIP that the callee would like to be called again with the same parameters. This is used when the skin needs to delay to allow some output or other work to progress before the RIP continues. Note that the maximum such delay should be around 100 milliseconds.

raster_start_fn

RASTER_START_EX* sw_raster_api_20230105::raster_start_fn

A function called at the start of outputting the data for each separation.

Parameters

pJobContext	An opaque pointer to caller-managed data, as originally provided by inputq_print_job() or SwLeJobStart().
pRasterDescription	The raster description for the page
handlep	If successful, set by the callback to the raster handle for this page

Returns

This function should return RASTER_noErr (0) for success; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error.

raster_write_data_fn

RASTER_WRITE_DATA_EX* sw_raster_api_20230105::raster_write_data_fn

A function called to deliver data to the raster backend. This will be called only if sw_raster_api_20230105::raster_start_fn succeeded, and then it will be called once for each band of each frame successively.

This function will be called with successive bands of data until all frames of the separation have been delivered.

Parameters

pJobContext	An opaque pointer to caller-managed data, as originally provided by inputq_print_job() or SwLeJobStart().
handle	The raster handle obtained from RASTER_START_EX
pRasterDescription	The raster description for the page
data	The raster data. This may be NULL if the entire separation was trimmed out.
topline	The index of the first line of raster data being provided to this call
nlines	The number of lines of raster data being provided
bytesperline	The number of bytes of unpadded data in each line of raster.
plane	The raster plane index, counted across all planes of all frames in the separation, after separation omission. For a normal RIP configuration, this will be zero for monochrome and pixel interleaved output; the band index after separation omission for band interleaved output; or the frame index after separation omission for frame interleaved output. The RasterPlaneFromDescription() function can be used to retrieve the plane structure in callback functions.

Returns

This function should return RASTER_noErr (0) for success; one of the negative RASTER_RESULT codes or a sw_mon_type error code greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error.

---

The documentation for this struct was generated from the following file:

• lib/skinkit/export/rasthand.h