Skip to main content
Skip table of contents

(v13) DoHalftone

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

The RIP invokes DoHalftone to instruct the Screening module to use a given halftone instance to screen parts of the band being rendered.

The main inputs to DoHalftone are:

  • The halftone instance value for the screening to be employed.
  • A mask bitmap indicating the pixel positions to be halftoned.
  • The pointer(s) to the destination Raster pixel buffer(s) for the Channel(s).
  • A destination band buffer containing halftoned raster pixels.
  • The offset(s) within the destination band of the channel(s) to be halftoned.
  • Optionally, a map of the object properties of each pixel position to be halftoned.

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 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 14739254 for details of when multiple channels are screened in a single call and therefore multiple offsets are supplied.

DoHalftone does not necessarily imply that the screening process is synchronous. Instead, the screening module is required to call a RIP-supplied API, known as DoneHalftone , to notify the RIP when it has done what was requested. (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 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 14739254 for more information.


Figure: Typical DoHalftone one channel (band interleaved)

Interrelated channels

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 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 DoHalftone, for that halftone instance, it will pass source band and destination band offsets for all of the interrelated channels. In effect, 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. See 14739254 for more information.

Figure: Interrelated channels DoHalftone four channels (band interleaved)

Mask bitmap format

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.

Source and destination band formats

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.

Source bands

The source band passed to the Screening module is either 8-bits or 16bits per pixel per channel.

The number of bits per pixel is constant and the same for all channels.

Destination bands

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.

Note however that 2-bit and 4-bit destination raster depths are not yet supported by the Harlequin RIP.

In the interim, 2-bit and 4-bit halftones may need to store their bits within an 8-bit container value, relying upon the output device driver or plugin to disregard the unused bits. (For best results with the Harlequin GUI RIP's “Roam” feature, it is best to use the most-significant 2 or 4bits of the 8-bit container.)

The 16-bit destination raster depth is not currently supported by the Harlequin GUI RIP's pagebuffer device, and so is restricted to OEM-supplied pagebuffer devices.

Use of the object properties map

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:


Anything detected as an image; this may exclude some images such as those taken as being vignettes (1xN and Nx1 images) or linework (1-bit deep images of other sizes). Includes anything labelled as /Picture, for example, with the setcolorrenderingintent operator.


Text objects; (see note below).


If supported, and enabled in the RIP any page object likely to be a vignette, including shfills . May also include 1xN or Nx1 images that are more than 1-bit deep.


Linework objects are those that are not Pictures, Vignettes or Text; (see note below).


Composited transparent objects.

NOTE: The Text and Linework object keys do not include text or linework used as a clipping mask, or filled with a pattern color. The contents of the pattern cell or shading determine how such objects are classified. (Parts of the pattern cell may be treated in different ways. For example, a pattern cell containing an image and a fill would have the image treated as Picture and the fill as Linework.)

For more information about the object map see section 10 of the [HQNEXTN].

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.