|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
The definition of an implementation of the modular halftoning interface. More...
#include "swhtm.h"
Data Fields | |
| sw_api_info | info |
| Version number, name, display name, instance size. | |
| HqBool(* | init )(sw_htm_api *implementation, const sw_htm_init_params *params) |
| The init() method is called before any other calls to the implementation. More... | |
| void(* | finish )(sw_htm_api *implementation) |
| The finish() method is called after all calls to the implementation or its instances. More... | |
| sw_htm_result(* | HalftoneSelect )(sw_htm_instance *instance, const sw_htm_select_info *info, sw_htm_instance **matches) |
The RIP calls HalftoneSelect() when the PDL instigates the equivalent of a PostScript sethalftone. More... | |
| void(* | HalftoneRelease )(sw_htm_instance *instance) |
| The RIP calls HalftoneRelease() when it no longer needs a reference to a particular halftone instance. More... | |
| sw_htm_result(* | RenderInitiation )(sw_htm_api *implementation, const sw_htm_render_info *render_info) |
| The RIP calls RenderInitiation() when it prepares to render a page. More... | |
| HqBool(* | DoHalftone )(sw_htm_instance *instance, const sw_htm_dohalftone_request *request) |
| The RIP calls DoHalftone() when it wants the instance to screen a contone buffer (or buffers) into the destination channel(s) within the RIPs band buffers. More... | |
| void(* | RenderCompletion )(sw_htm_api *implementation, const sw_htm_render_info *render_info, HqBool aborted) |
| The RIP calls RenderCompletion() when it successfully finishes rendering a page, or when it cancels or aborts rendering, for example due to an error. More... | |
| void(* | HtmSecurity )(sw_htm_instance *instance, void *buffer, uint32 size) |
| The HtmSecurity() interface is not yet used. More... | |
| sw_htm_band_ordering | band_ordering |
| A class variable describing the band ordering needs of the screening module. Its value should be one of the sw_htm_band_order constants. | |
| HqBool | reentrant |
A class variable describing whether the module is reentrant. Set this to FALSE if the RIP must never call DoHalftone() from more than one thread at any one time. More... | |
| void(* | AbortHalftone )(sw_htm_instance *instance, const sw_htm_dohalftone_request *request) |
| The RIP calls AbortHalftone() when it wants the module to stop rendering an outstanding request issued by DoHalftone() with the same arguments. More... | |
| sw_htm_result(* | RenderInitiationInstance )(sw_htm_instance *instance, const sw_htm_render_info *render_info, sw_htm_render_overrides *overrides) |
| The RIP calls this method when it prepares to render a page. More... | |
The definition of an implementation of the modular halftoning interface.
Multiple halftone implementations may be registered with the RIP. Each implementation may have multiple instances active at the same time.
| void( * sw_htm_api::AbortHalftone) (sw_htm_instance *instance, const sw_htm_dohalftone_request *request) |
The RIP calls AbortHalftone() when it wants the module to stop rendering an outstanding request issued by DoHalftone() with the same arguments.
The module must stop writing to its output buffers and then invoke sw_htm_dohalftone_request::DoneHalftone() before returning (it is permissible to invoke it from another thread). Because the calls can't be synchronized, it may happen that the module has already called sw_htm_dohalftone_request::DoneHalftone() between the RIP deciding to abort and actually invoking AbortHalftone(). This is acceptable, but the module must be so constructed that any such sw_htm_dohalftone_request::DoneHalftone() has, in fact, returned before AbortHalftone() returns. The RIP will check if the request has, in fact, terminated, and it is an error if it hasn't.
| [in] | instance | Pointer to a halftone instance selected by HalftoneSelect(). |
| [in] | request | Pointer to a structure holding details of the RIP's halftone request. |
| HqBool( * sw_htm_api::DoHalftone) (sw_htm_instance *instance, const sw_htm_dohalftone_request *request) |
The RIP calls DoHalftone() when it wants the instance to screen a contone buffer (or buffers) into the destination channel(s) within the RIPs band buffers.
| [in] | instance | Pointer to a halftone instance selected by HalftoneSelect(). |
| [in] | request | Pointer to a structure holding details of the RIP's halftone request. |
| FALSE | The module is unable to accept the request. In this case, the module must not touch any arguments passed to it, and the RIP will deem this an unrecoverable failure. |
| TRUE | The module accepts the request and will call sw_htm_dohalftone_request::DoneHalftone() when done. The success or failure of the overall request is indicated by the result parameter of sw_htm_dohalftone_request::DoneHalftone(). |
The module must not block on something that depends on another DoHalftone() invocation being made. Even if sw_htm_render_info::max_render_threads > 1, there's no guarantee that another invocation can be made concurrently.
The module must call sw_htm_dohalftone_request::DoneHalftone() using exactly the same request pointer passed in to it.
| void( * sw_htm_api::finish) ( sw_htm_api *implementation) |
The finish() method is called after all calls to the implementation or its instances.
The implementation instances should not access any data owned by the RIP after this call, nor should they call any implementation or RIP callback API methods after this call. This method is optional.
| implementation | A registered modular halftone implementation to finalise. |
| void( * sw_htm_api::HalftoneRelease) (sw_htm_instance *instance) |
The RIP calls HalftoneRelease() when it no longer needs a reference to a particular halftone instance.
HalftoneRelease() will be called once for each previously successful HalftoneSelect(), with the instance pointer that is not required. The implementation should clean up any resources associated with the instance.
| [in] | instance | The halftone instance value originally constructed by HalftoneSelect(). |
| sw_htm_result( * sw_htm_api::HalftoneSelect) (sw_htm_instance *instance, const sw_htm_select_info *info, sw_htm_instance **matches) |
The RIP calls HalftoneSelect() when the PDL instigates the equivalent of a PostScript sethalftone.
| [in,out] | instance | An incomplete instance of the sw_htm_instance structure to complete. The RIP will allocate a structure of the size presented in the implementation's sw_htm_api::info.instance_size field, fill in the implementation and callback API instance pointers, and then pass it to this routine. The HalftoneSelect() method is expected to fill in the remaining fields. The implementation may sub-class the instance to allocate private workspace by initialising the sw_htm_api::info.instance_size larger than the size of the sw_htm_instance structure, then downcasting the instance pointer in method calls. |
| [in] | info | Halftone selection information from the RIP. This contains things like the halftone phase and a pointer to an information structure describing the destination raster and colorants etc. It also contains a data access API, a datum representing the colorant name for which this halftone is being selected and a datum representing the halftone dictionary. Any data accessed through this pointer MUST be copied if the halftone instance wished to refer to it after the HalftoneSelect() method has returned. |
| [out] | matches | If the halftone module currently has an instance selected that maps onto the same screen, it should store the existing instance in this pointer and return SW_HTM_SUCCESS. In this case, the instance under construction will be destroyed immediately, and there will be no call to HalftoneRelease(). This will ensure that equivalent screen definitions share the same DoHalftone() calls, and will improve rendering efficiency. It is an error to store the instance under construction through this pointer. |
| void( * sw_htm_api::HtmSecurity) (sw_htm_instance *instance, void *buffer, uint32 size) |
The HtmSecurity() interface is not yet used.
Its pointer should be set to NULL by early screening modules.
| HqBool( * sw_htm_api::init) ( sw_htm_api *implementation, const sw_htm_init_params *params) |
The init() method is called before any other calls to the implementation.
This method may be used to initialise any implementation-specific data. This method is optional.
| implementation | The registered modular halftone implementation to be initialised. | |
| [in] | params | A structure containing callback APIs and parameters valid for the lifetime of the module. Any parameters that the implementation needs access to should be copied out of this structure into private storage for the registered implementation. |
| TRUE | Success, indicating that the implementation is fully initialised. |
| FALSE | Failure to initialise the implementation. If this is returned, the implementation will not be finalised. |
| HqBool sw_htm_api::reentrant |
A class variable describing whether the module is reentrant. Set this to FALSE if the RIP must never call DoHalftone() from more than one thread at any one time.
FALSE, the RIP does not warrant that consecutive calls of DoHalftone() will be from the same thread. | void( * sw_htm_api::RenderCompletion) (sw_htm_api *implementation, const sw_htm_render_info *render_info, HqBool aborted) |
The RIP calls RenderCompletion() when it successfully finishes rendering a page, or when it cancels or aborts rendering, for example due to an error.
RenderCompletion() is a class function, it will be called once for each registered modular halftone implementation that may have halftones used on a page.
This method is optional.
| [in] | implementation | Pointer to the implementation registered with the RIP. |
| [in] | render_info | A pointer to the general render information structure. See RenderInitiation() for more information. |
| [in] | aborted | A Boolean indicating whether rendering has been ended prematurely due to cancellation of the job or a rendering error. The renderer does not distinguish cancellation from error conditions. It merely lets the screening module know that the page or job did not complete its rendering phase sucessfully. |
| sw_htm_result( * sw_htm_api::RenderInitiation) (sw_htm_api *implementation, const sw_htm_render_info *render_info) |
The RIP calls RenderInitiation() when it prepares to render a page.
RenderInitiation() is a class function. It will be called once for each halftone module that may have halftones used on a page.
In the case of color-separated output, RenderInitiation() takes place once, before the RIP renders all the separations of a page.
Note that when the RenderInitiation() is for a partial paint, very little memory will be available, so any mandatory buffers should be preallocated during HalftoneSelect().
This method is optional.
| [in] | implementation | A pointer to the implementation registered with the RIP. |
| [in] | render_info | Pointer to a structure containing general information about the upcoming render as a whole. |
| sw_htm_result( * sw_htm_api::RenderInitiationInstance) (sw_htm_instance *instance, const sw_htm_render_info *render_info, sw_htm_render_overrides *overrides) |
The RIP calls this method when it prepares to render a page.
RenderInitiationInstance() is rather like RenderInitiation(), except it's an instance function. It will be called once for each halftone instance that may have halftones used on a page.
In the case of color-separated output, RenderInitiationInstance() takes place only once, before the RIP renders all the separations of a page.
Note that when the RenderInitiationInstance() is for a partial paint, very little memory will be available, so any mandatory buffers should be preallocated during HalftoneSelect().
This method is optional.
| [in] | instance | A pointer to a halftone instance used on the page. |
| [in] | render_info | A pointer to a structure containing general information about the upcoming render as a whole. |
| [in] | overrides | A pointer to a structure for overriding certain parameters for the duration of this rendering pass. On entry, the fields are set to the values of the parameters given in instance and its implementation. The method may modify them, and this rendering pass will use the new values (but the default values in the instance and implementation structures are not changed). |