|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
The halftone screening API enables customer-supplied code to generate halftoned raster output from the Harlequin RIP during the RIPping process. More...
Files | |
| file | swhtm.h |
| Header file defining the Halftone module interface. | |
Data Structures | |
| struct | sw_htm_colorant_info |
| Information about a colorant in a raster. More... | |
| struct | sw_htm_raster_info |
| Information about the destination raster. More... | |
| struct | sw_htm_select_info |
| Information passed to the screening module for sw_htm_api::HalftoneSelect(). More... | |
| struct | sw_htm_render_info |
| Render information passed to sw_htm_api::RenderInitiation() and sw_htm_api::DoHalftone(). More... | |
| struct | sw_htm_dohalftone_request |
| Structure describing what the RIP wants sw_htm_api::DoHalftone() to do. More... | |
| struct | sw_htm_instance |
| An instance structure for the modular halftone API implementation. More... | |
| struct | sw_htm_init_params |
| Collection structure for initialisation parameters. More... | |
| struct | sw_htm_render_overrides |
| Structure for parameters that may be overridden at sw_htm_api::RenderInitiationInstance. More... | |
| struct | sw_htm_api |
| The definition of an implementation of the modular halftoning interface. More... | |
Macros | |
| #define | SW_HTM_DEFAULT_INDEX UINT_MAX |
Denotes the halftone is being selected for /Default. | |
| #define | SW_HTM_RASTER_UNIT_BITS (64) |
| The number of bits in each sw_htm_raster_unit. | |
Typedefs | |
| typedef HqnResult | sw_htm_result |
| Type of results returned by screening modules. More... | |
| typedef struct sw_htm_api | sw_htm_api |
| A type definition for an implementation of the modular halftone interface. | |
| typedef int32 | sw_htm_coord |
| Raster coordinates, widths, heights etc. | |
| typedef double | sw_htm_resolution |
| Raster resolution, usually dots per inch, expressed as a floating-point value. | |
| typedef void | sw_message_fn(const char *message) |
| Type of the callback to output a message to the RIP's monitor device. More... | |
| typedef int32 | sw_htm_coloranttype |
| Storage unit for colorant types. | |
| typedef int32 | sw_htm_colorant_handling |
| Storage unit for colorant handling. | |
| typedef struct sw_htm_colorant_info | sw_htm_colorant_info |
| Information about a colorant in a raster. | |
| typedef int32 | sw_htm_raster_interleaving |
| Storage unit for raster interleaving. | |
| typedef int32 | sw_htm_colorspace |
| Storage unit for raster colorspace. | |
| typedef struct sw_htm_raster_info | sw_htm_raster_info |
| Information about the destination raster. | |
| typedef struct sw_htm_select_info | sw_htm_select_info |
| Information passed to the screening module for sw_htm_api::HalftoneSelect(). | |
| typedef int32 | sw_htm_band_ordering |
| Storage unit for band ordering. | |
| typedef struct sw_htm_render_info | sw_htm_render_info |
| Render information passed to sw_htm_api::RenderInitiation() and sw_htm_api::DoHalftone(). | |
| typedef uint64 | sw_htm_raster_unit |
| The unit of size used to access and point to rasters. More... | |
| typedef sw_htm_raster_unit * | sw_htm_raster_ptr |
| Type definition for a raster pointer. | |
| typedef int32 | sw_htm_mask_hint |
| Storage unit for mask hints. | |
| typedef struct sw_htm_dohalftone_request | sw_htm_dohalftone_request |
| Structure describing what the RIP wants sw_htm_api::DoHalftone() to do. | |
| typedef struct sw_htm_instance | sw_htm_instance |
| An instance structure for the modular halftone API implementation. More... | |
| typedef struct sw_htm_init_params | sw_htm_init_params |
| Collection structure for initialisation parameters. | |
| typedef struct sw_htm_render_overrides | sw_htm_render_overrides |
| Structure for parameters that may be overridden at sw_htm_api::RenderInitiationInstance. | |
Functions | |
| HqnResult | swhtm_result_translate (sw_htm_result result) |
| Translate an HTM API-specific error code to a generic HqnResult error code. More... | |
| sw_api_result | SwRegisterHTM (sw_htm_api *implementation) |
| This routine makes a modular halftone implementation known to the RIP. More... | |
The halftone screening API enables customer-supplied code to generate halftoned raster output from the Harlequin RIP during the RIPping process.
The Harlequin Core supports multiple methods of halftone screening built-in, including AM screens defined by spot functions; screens defined by threshold arrays; tile-based screening for non-monotonic screens; FM screens, and other methods. In addition, it includes extensions to those screening mechanisms, including controls to increase the number of gray levels achievable; controls to manage and override the selection of screens; automatic selection of screens by object type; and support for multi-level screening. For more information see the Extensions Manual. Harlequin Core can also be integrated with Global Graphics Software's dedicated post-RIP screening engine, ScreenPro™ to apply screening at very high speed post-RIP, with PrintFlat™ to correct for non-uniformity in the print.
The RIP also supports a modular screening API that allows you to supply code (screening modules) to apply your own halftoning algorithms. Screening modules convert continuous tone raster data into screened data. Because the screening algorithm programmed in a screening module is specified by code, screening modules can support any type of screening algorithm, including error diffusion, stochastic, non-monotonic, and object type and color dependent algorithms.
Halftone modules perform screening on raster bands, converting pixel values in a band of continuous tone raster data into a reduced set of values arranged according to the screening algorithm. The halftone module interface is designed to allow multiple halftone modules to be used for different types of objects in a page, for a halftone module to be able to vary its behavior depending on the type of object that a pixel represents, and for halftone modules to be able to co-exist with in-RIP screening.
The Harlequin RIP divides the raster into a sequence of bands using a fixed number of scanlines per band (the last band will contain fewer lines when the raster height is not an exact multiple of the band height). Band boundaries are fixed early on during pagedevice setup and persist throughout the rendering phase and delivery to the halftone module or final output device.
Source data for halftone modules are band buffers containing one or more channels of 8 or 16-bit contone raster data. The halftone module is expected to modify a destination band of 1, 2, 4, 8 or 16-bit raster data, depending on the configuration of the output. The halftone module interface can be used for some other raster to raster transformations as well as screening.
In the Harlequin RIP, the properties of the final output raster, such as the number of output channels, the order of the channels in that list, the way the channels are interleaved, and the number of bits per channel per pixel, are also fixed early during page-device instantiation and interpretation. These are usually tailored towards the needs of the final output device driver or plugin. The raster layout structure describes how color channels are stored in rasters for a page. The three basic variants of the raster layout using by the halftone module interface are:
This method is where all the pixels of the first color channel (for as many consecutive scanlines as are present in the band) are followed by all the pixels of the second channel (for the same number of consecutive scanlines), followed by the third channel and so on.
The number of color channels present is the same for all bands in a page. There is no theoretical limit on the number of color channels. The order of the color channels within the band is also the same for all bands in a page. That order depends on the raster format, as determined by the preferences of the output device or plugin, the presence of spot colors, whether channels are omitted, suppressed and so on.
Some raster formats may require mandatory channels in fixed positions with relation to the other channels. Other raster formats may permit any number of channels to appear in any order, including unknown spot colors in between known process colors. The RIP's Screening mechanisms supports, wherever possible, any channel order required by the output device or plugin.
This method is where each band contains only a single color channel. All the bands of the first channel is processed and output first, followed by all the bands of the second channel, followed by all the bands of the third and so on. This method is also used when rendering single color channel separations.
This method is limited to one, three or four channels in Harlequin RIP Rasters, and is available solely for output of 8-bits per pixel per channel (contone). Pixel interleaving is not available for screening interfaces.
The three or four-color channels making up a pixel are stored in consecutive bytes followed by the three or four channels of the next pixel and so on. When there is only one channel, of course, the bytes are simply consecutive.
In a single-processor Harlequin RIP, the RIP renders each band in turn, rasterizing the appropriate elements of the display list into the final output band ready for compression and/or delivery to the raster output. Any compositing necessary for transparent areas is performed before rasterization. In a multi-processor Harlequin RIP, several bands can be rendered simultaneously by separate threads. The Harlequin RIP usually writes bands in order, from the top of the raster to the bottom, but if requested may write bands in arbitrary order. Halftone modules may specify the order in which they expect bands. If there is no required order, use SW_HTM_BAND_ORDER_ANY, this may make certain multi-threaded setups run faster. The RIP currently does not support bands in descending order, so halftone modules should not specify SW_HTM_BAND_ORDER_DESCENDING.
If the RIP runs out of memory to store its display list, it may perform a partial paint. This involves invoking the renderer to rasterize all the bands of the display list so far, storing the rasterized bands in final output format on disk. The display list is then truncated so that new elements can once again be added as page interpretation continues. After a partial-paint subsequent rendering of any further elements of the display list involves reading back the partly rasterized band from the page-buffer device before merging in the newly rendered raster. In this case, the destination band buffer presented to the halftone module interface may already contain screened data.
Some halftone algorithms require a broader view of the input data than a single band of data can provide: for example, they may need to look ahead at the scanlines immediately after the end of a in input band to determine how to distribute error terms or apply a filter kernel.
Setting the latency of a halftone module instance allows the number of previous bands that are needed by the screening algorithm to be specified. The destination rasters for a number of bands are guaranteed to be available at the addresses that they were initially presented for a number of succeeding band calls. For example, if latency is specified as 3, the screening module can use and modify the last 3 bands of data as well as the current band (as passed in the arguments to sw_htm_api::DoHalftone()). With latency set to 0 the normal mode of working, one band at a time, is used.
Halftone module band latency only makes sense with a defined order of band delivery. If you specify a non-zero latency, you should also specify a band order of SW_HTM_BAND_ORDER_ASCENDING. The RIP currently does not support bands in descending order, so halftone modules should not specify SW_HTM_BAND_ORDER_DESCENDING.
To use a screen defined by a module, you need to create a type 100 halftone dictionary. You will also want to create entire screen sets with screens for all the colorants, using a standard type 5 halftone dictionary, and possibly sets with different screens for different types of objects, using the Harlequin extension, type 195. For more information see the "GGS extension, HalftoneType 195" in the Extensions Manual.
You may also want to register these screens by name, so they can be used as override screens. For more information see "Adding extra dot shapes" in the Extensions Manual.
See the screen setup and configuration examples in the RIP's data directory, in SW/Sys/ExtraStart/HtmEg and SW/TestConfig/HTM/.
Calls to the halftone module interface follow these stages:
sethalftone operator. Separate halftone select calls may be made for each potential colorant. Halftone select and release occur as necessary.Each screening module is identified by an internal name, for use in configuring the RIP, and an additional UTF-8 name for display purposes. Each screening module also indicates at registration time the source (contone) and destination (halftone) raster depths and interleaving formats it supports.
Halftoning modules are represented by instances of the the sw_htm_api structure. Halftone modules may be registered after the RIP is started by calling SwRegisterHTM(). This function performs some validation checks on the API structure, and then registers it in RDR as a named RDR, in the RDR_NAMES_HTMAPI namespace, using the internal name provided in the structure. This internal name is also used to select the halftone module. You may register halftone modules in RDR directly before the RIP is started, but doing so will not perform the validation checks that SwRegisterHTM() performs. If you miss out a required callback function pointer, selecting your halftone may crash the RIP. You may also de-register halftone modules from RDR by calling SwDeregisterNamedRDR(), if you have access to the pointer and length that the module was registered with.
The source raster depth is used to deliver the contone pixels to the screening module for halftoning. It will be either 8-bits or 16-bits. Note that for screening modules requesting object-type information to accompany the raster, the bit depth of the object-type information is always the same as that of the source (contone) raster. All screening modules should support both 8-bit and 16-bit source rasters. The RIP will report an error and stop processing if it is unable to adopt a source raster depth satisfying all screening modules used within a page.
The destination raster depth is that required by the output device driver or plugin. Destination raster depths are expected to be 1, 2, 4, 8 or 16-bits.
The interface between the RIP and screening modules only permits the use of band-interleaved or frame-interleaved raster formats. The RIP does not support screening of a pixel-interleaved raster. If required, it is the responsibility of the output device driver/plugin to convert the raster to pixel interleaving.
If you configure use of a screening module that does not support the destination bit depth or interleaving format required by the output device, the RIP will report an error and abort processing of the job.
Before any other calls are made to the halftone module, sw_htm_api::init() is called to allow it to initialize data. This call is provided with a parameters structure that contains a pointer to a memory callback API instance. The halftone module should save the memory callback API instance pointer and use it to allocate any data it needs.
The sw_htm_api::HalftoneSelect() call makes the screening module aware of a request from the PDL for the potential use of a single halftone, enabling the screening module to verify the request and accept or reject it.
The request might originate from a PostScript language sethalftone operator, or from appropriate changes to the graphics state, such as save/restore, or from a PDF halftone setting. All such requests appear to the screening module as though they were defined using a halftone dictionary, even though the request may have originated in some other form within the PDL.
The /HalftoneType value for these halftone dictionaries is 100. The association of the request with an individual screening module is provided by a mandatory /HalftoneModule key within the halftone dictionary. The contents of this halftone dictionary are made available to the screening module as part of the details associated with the halftone select together with some information describing the target destination raster.
The screening module's response to a halftone select is an opaque value, representing an instance of that halftone, and is used by the RIP to refer to uses of that halftone. The screening module must maintain the validity of that instance value until notified by the RIP via a halftone release call. Where possible, the screening module should return the same instance value for a subsequent halftone select sharing the same properties, so several separate requests from the PDL for what is essentially the same halftone should all return the same instance value.
If the screening module deems the halftone select invalid it should, wherever possible, identify a key within the halftone dictionary as probable cause of complaint.
The RIP does not attempt to cache or bypass halftone selects, nor the resulting instance values, but it may do so in the future.
Note that it is possible for the RIP to invoke a halftone select and subsequently release the instance without having used the halftone for any objects. A halftone select does not imply that the halftone will necessarily be used for rendering.
Note also that many changes to the graphics state may take place when preparing a job, and that the RIP itself may therefore invoke HalftoneSelect many times, seemingly repeating itself. What the RIP is actually doing is calling the screening module to ascertain whether different halftone instances are needed under the new circumstances. If they are different, the RIP will usually then release the earlier ones. If the module returns the same halftone instance, on the other hand, the RIP will release the duplicates and continue.
The halftone select operation establishes an instance value for a single colorant. The RIP performs a separate and distinct halftone select operation for each potential colorant.
Even without a module making different choices for colorants, a type 5 dictionary (in the job or the configuration) can specify wholly different screening mechanisms or modules for different channels of the same pixel. Situations wherein some channels within a pixel utilize different halftoning from others may also arise as a result of overprints.
When all the screening mechanisms involved are capable of processing each channel individually, pixels made up of several different screening mechanisms should pose no particular problem.
Some screening mechanisms, however, exploit the interrelationships between color components and therefore need to have all color values (for channels relevant to them) available as and when they process each pixel. Nevertheless, the use of spot colors might mean there exist, within a pixel, color channels not relevant to such interrelationships; such channels can reasonably be expected to demand the use of a different screening mechanism or halftone.
The dilemma is that there may be pixels, within the raster, some of whose channels are interrelated and should be considered as a whole by one screening module, whilst other channels should be processed individually by another screening module or modules.
To resolve this, the RIP requires screening modules needing interrelated channels to do two things:
These together ensure that, from the RIP's point of view, all the interrelated channels can be halftoned using a single call of sw_htm_api::DoHalftone().
The halftone select operation gets a description of the output raster as an argument. This includes an array describing the device colorants and the output channels in the raster. While the elements are called sw_htm_colorant_info, the array is really organized by channel.
If the module inspects the raster description and it is intended to work with configurations unknown to the module writer, careful attention is required to correctly interpret this description. In some configurations, some colorants may appear on multiple channels, or unused channels may not have a valid colorant, and the set of channels may change during the page.
For details of separation configuration see "Configuring the page device" in the Extensions Manual.
The sw_htm_api::HalftoneRelease() call will be made when the RIP relinquishes one use of a halftone instance. If this is the last release for the relevant instance value, the screening module can clean up resources associated with that halftone as desired. The RIP assumes that instance values are reference-counted by the screening module. Halftone selects and releases are paired, such that the RIP will always issue a matching release for each successful select.
Halftone instance values have scope beyond page boundaries, so a single instance of a halftone may be used across several disconnected pages.
The RIP also reserves the right to extend the scope of halftone instances beyond job boundaries, if desired in the future.
When the RIP determines that it is about to start rendering a page, or a part thereof such as might be the case during a partial paint, it calls sw_htm_api::RenderInitiationInstance() to ask the screening modules to prepare to perform halftoning. For each separation it is going to output, the RIP then calls sw_htm_api::RenderInitiation().
Memory allocations/deallocations are not permitted during rendering, so the screening modules must allocate any further memory they require now. Shortly after this the RIP will claim its own memory needs prior to rendering. The RIP reserves the right to allocate all remaining memory for its own purposes.
The screening modules must also furnish the RIP with information regarding their needs during rendering. One such need is whether the module must be presented with bands in a particular order; say from the top to the bottom of the page, or vice-versa.
Screening modules should avoid imposing band ordering needs on the RIP wherever possible, so as to maximize the RIP's opportunity to exploit multiple processors. The other important property a screening module needs to communicate to the RIP is its band latency.
Any screening module not capable of supporting sw_htm_api::DoHalftone() calls from multiple separate renderer threads must inform the RIP during render initiation. For such modules, multi-threaded RIPs will arrange to only ever call sw_htm_api::DoHalftone() from one thread at any one time. Note however that the RIP does not warrant that each call will originate in any particular thread: sequential calls may be made from the same or different RIP threads at the RIP's discretion.
The RIP invokes sw_htm_api::DoHalftone() to instruct the screening module to use a given halftone instance to screen parts of the band being rendered.
The main inputs to sw_htm_api::DoHalftone() are:
The mask bitmap indicates those pixel positions within the band to be halftoned using the given halftone instance. Be aware that other instances, modules or mechanisms may screen other pixels in the band. It is the responsibility of each screening module to avoid pixels screened elsewhere. Only pixels identified by the mask bitmap are replaced in the destination band.
In the majority of cases, the RIP will invoke sw_htm_api::DoHalftone() separately for each channel, so there is only a single channel pointer into the source band, and a single channel pointer within the destination band. See Interrelated channels for details of when multiple channels are screened in a single call and therefore multiple offsets are supplied.
sw_htm_api::DoHalftone() does not necessarily imply that the screening process is synchronous. Instead, the screening module is required to call a RIP-supplied callback, sw_htm_dohalftone_request::DoneHalftone(), to notify the RIP when it has done what was requested: Calling sw_htm_dohalftone_request::DoneHalftone() will set a condition variable in multi-renderer RIPs. This allows screening modules to exploit hardware or multi-threading, even if the RIP itself is built as single-threaded.
From the instant the screening module invokes sw_htm_dohalftone_request::DoneHalftone() for a given band, it must no longer access any of the memory areas or structures it was originally passed.
The optional object properties map is only supplied if the screening module requested it. See Use of the object properties map for more information.
Some screening modules exploit the interrelationships between color channel, or for other reasons need to have a set of color values available to them when they process each pixel. In these cases, the module needs sw_htm_api::DoHalftone() to be called once to process several channels at the same time. To trigger this, the screening module will have informed the RIP, as part of the halftone select process, the interrelated channels, and the order of those channels from the module's perspective. The module must also have returned the same halftone instance for all those channels.
During rendering when the RIP invokes sw_htm_api::DoHalftone(), for that halftone instance, it will pass source band and destination band offsets for all of the interrelated channels. In effect, sw_htm_api::DoHalftone() is requested to screen multiple channels instead of one.
The order of the channel pointers is the order the screening module gave for its interrelated channels. This need not reflect the physical order of the channels within the raster.
There is still only one mask bitmap, because the mask identifies pixel positions, and is independent of the number of channels. The screening module must still take care that only pixels identified by the mask bitmap are replaced in the destination band. Furthermore, the module must also ensure that it only changes the channels identified by the list of source and destination band offsets.
Other instances, modules or mechanisms may screen other channels in the same pixel positions.
There is one bit in the mask bitmap for each pixel position within the band. This means the mask bitmap is made up of a number of scanlines, with one bit representing each horizontal pixel position in the scanline. The number of scanlines is the same as the number of lines in each channel of the source and destination band buffers. The number of channels does not affect the number of bits in the mask bitmap.
The number of lines in each band is constant for any one page, except that the last band in a page may contain fewer lines than the rest. The given number of lines is present in each of the channels. The number of channels is constant from band to band, and is always one in the case of frame-interleave.
The source band passed to the screening module is either 8 bits or 16 bits per pixel per channel. The number of bits per pixel is constant and the same for all channels.
The destination band passed to the screening module is at the raster bit depth required by the output device.
The number of bits per pixel is constant and the same for all channels. This will currently be 1, 2, 4, 8 or 16 bits per pixel per channel.
The optional object properties map is only supplied if the screening module requested it. The object properties are used for screening modules that act like screening managers and vary the halftones employed on a pixel-by-pixel basis according to their own algorithms.
The object properties map, like the band bitmap, has one entry for each pixel position within the band, but each entry is 8-bits or 16-bits per pixel instead of one. (The bit depth is always the same as the source contone raster.)
The value of each entry in the map indicates the types of object that contributed to that pixel position for the appropriate channel (or set of interrelated channels).
It is important to note that a single pixel position can have contributions from more than one object type, due to overprinting or transparency.
The screening module is expected to use the object-type information to determine the halftoning method it wishes to apply to the different pixels.
The types of object that can be differentiated are:
/Picture, for example, with the setcolorrenderingintent operator.For more information about the object map see the object map section in the Extensions Manual.
sw_htm_api::RenderCompletion() is called when the RIP finishes or aborts the render process. A boolean parameter lets the screening module know whether rendering was successful or abortive.
Screening modules should at this point release any memory they allocated at render initiation time.
There are times when the renderer needs to abort rendering, such as when a failure occurs, or a job is interrupted.
If requests have been passed to a screening module via sw_htm_api::DoHalftone(), and any such request has not been notified as having been completed when the renderer needs to abort, the screening module will be informed using an sw_htm_api::AbortHalftone() call for each such request.
The screening module must take any action necessary and confirm the abort as quickly as possible. The outstanding request should also be marked as complete, by invoking sw_htm_dohalftone_request::DoneHalftone(), with a failure indication if possible.
Only if a serious impediment exists, such as an outstanding DMA transfer, may the screening module refuse the abort. In such a case the RIP will repeat the sw_htm_api::AbortHalftone() attempt periodically until it succeeds.
The screening module will subsequently receive a render completion, with a boolean indicating that rendering was aborted, so as to allow further tidying up as necessary. The subsequent render completion will not take place until the render abort has succeeded.
Note that the screening module must be prepared to receive an sw_htm_api::AbortHalftone() even when it is in the process of notifying the RIP that it has completed all the calls made to sw_htm_api::DoHalftone() (because they cannot be synchronized). The screening module should deny the abort in such a case; otherwise, the RIP could try to do render completion before the sw_htm_dohalftone_request::DoneHalftone() calls have finished.
After all other calls are made to the halftone module, sw_htm_api::finish() is called to allow it to finalize data. The module should free any data it allocated.
| typedef struct sw_htm_instance sw_htm_instance |
An instance structure for the modular halftone API implementation.
This is the definition of a modular halftone instance. The RIP allocates memory for the instances, calling the sw_htm_api::HalftoneSelect() method to complete the details. The RIP uses this value in calls to sw_htm_api::DoHalftone() and sw_htm_api::HalftoneRelease(), to tell the module which halftone is being referred to.
The instance structure may be subclassed to hold private data by defining a subclass structure containing this structure as its first member, and using the size of that structure as the implementation's instance size. Individual methods may then downcast their instance pointer parameters to subclass pointers, and use the private data. e.g.,
The RIP will not touch memory beyond the size of the instance structure for the implementation version registered.
The unit of size used to access and point to rasters.
All raster buffers and pointers are also aligned to units of at least this size, though the RIP reserves the right to arrange raster alignment in multiples of this size.
All 1, 2 and 4 bit rasters should also be accessed in units of this size. These rasters are physically stored in memory as a row of unsigned values of the relevant number of bits in size. Accessing the raster as though it were a row of bytes, instead, will cause groups of bytes to appear in the reverse order on little-endian architectures such as Intel processors.
On the other hand, 8 and 16 bit rasters are only ever accessed in units of uint8 or uint16 as appropriate.
| typedef HqnResult sw_htm_result |
Type of results returned by screening modules.
This is a subclass of HqnResult that also supports some specific extra error codes generated by sw_htm_api functions (declared as the sw_htm_error enumeration). Before assigning to values of HqnResult type or any of its other subclasses, sw_htm_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 swhtm_result_translate().
| typedef void sw_message_fn(const char *message) |
Type of the callback to output a message to the RIP's monitor device.
| [in] | message | An ASCII string to output, or a UTF-8 string starting with the Unicode byte order mark: 0xEF,0xBB,0xBF. |
| enum sw_htm_api_version |
Version numbers defined for the HTM API.
| enum sw_htm_band_order |
Band ordering constraints imposed by a screening module.
Band ordering constraints apply to individual channels, or sets of interrelated channels. The RIP does not guarantee the order in which the individual channels, or sets of interrelated channels, are halftoned with respect to any other channel, or set. It only arranges to ensure that for a particular channel, or set, the bands are halftoned in the appropriate order.
For example, ascending order will ensure that channel 0 of the first band is halftoned before channel 0 of the second band, which in turn is before channel 0 of the third band etc. Whilst the same order will apply within the bands being halftoned for channel 1, there is no fixed relationship between the channels. The RIP might halftone the first three bands of channel 0 before commencing channel 1.
| enum sw_htm_coloranttypes |
| enum sw_htm_colorspaces |
Values for the fundamental color space of a raster.
| enum sw_htm_error |
Return values for screening modules.
| Enumerator | |
|---|---|
| SW_HTM_SUCCESS | Success return value for sw_htm_api methods. |
| SW_HTM_ERROR | Non-specific error, also minimum error value. Please avoid using this if possible. |
| SW_HTM_ERROR_IOERROR | Problem accessing file resource |
| SW_HTM_ERROR_LIMITCHECK | A hard limit has been exceeded. |
| SW_HTM_ERROR_RANGECHECK | Parameter values are out of range. |
| SW_HTM_ERROR_TYPECHECK | Parameter values are the wrong type. |
| SW_HTM_ERROR_MEMORY | Memory allocation failed. |
| SW_HTM_ERROR_CONFIGURATIONERROR | Incorrect configuration. |
| SW_HTM_ERROR_VERSION | The version of a callback API is insufficient for this module. |
| SW_HTM_ERROR_BAD_HINSTANCE | The module does not recognise the supplied halftone instance value. |
| SW_HTM_ERROR_UNSUPPORTED_SRC_BIT_DEPTH | The module does not support the source raster bit depth. |
| SW_HTM_ERROR_UNSUPPORTED_DST_BIT_DEPTH | The module does not support the destination raster bit depth. |
| enum sw_htm_maskhint |
Hints of the state of the mask bitmap, so as to permit optimisations when all bits are known to be set or no bits are set.
| Enumerator | |
|---|---|
| SW_HTM_MASKHINT_ALL_OFF | No bits are set in the bitmap. |
| SW_HTM_MASKHINT_NORMAL | Some bits are set, some are not. |
| SW_HTM_MASKHINT_ALL_ON | All bits are set in the bitmap. |
Values for special handling to apply to a colorant.
A screening module which doesn't understand special handling should just assume colorants are normal ones. Similarly, an unexpected value should be treated the same as SW_HTM_SPECIALHANDLING_NONE.
| HqnResult swhtm_result_translate | ( | sw_htm_result | result | ) |
Translate an HTM API-specific error code to a generic HqnResult error code.
| [in] | result | One of the sw_htm_error values, or an error value greater than MON_CLASS_ERROR. |
| sw_api_result SwRegisterHTM | ( | sw_htm_api * | implementation | ) |
This routine makes a modular halftone implementation known to the RIP.
It can be called any number of times with different implementations of the modular halftone API. Every implementation registered may multiple instances constructed.
This function may be called at any time after the RIP is initialized, and before the RIP is shut down.
| [in] | implementation | The API implementation to register. This pointer will be returned through the sw_htm_api::init() and sw_htm_api::finish() calls, and also will be in the implementation member field of every instance created, so the pointer can be in dynamically allocated memory. |
Implementations may be subclassed to hold class-specific private data by defining a subclass structure containing the sw_htm_api structure as its first member. Individual methods may then downcast their implementation pointers to subclass pointers, and use those to get at the class data. e.g.,