The screenforall operator

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

The screenforall operator is located in statusdict. Its purpose is to report on screen use. It can be used with PDF jobs as well as PostScript-language jobs.

A procedure operand is called repeatedly, once for each screen reported, in the manner of the filenameforall operator. A dictionary operand controls which screens are reported using its Report and Duplicate keys. The Output key of the dictionary operand controls which properties of the reported screens are provided on the operand stack to the procedure operand.

This form of screenforall replaces a more restricted operator in version 3 which took Boolean and numeric operands. That form of the operator still works, but is obsolete and will be withdrawn in a future version of the RIP.

The screenforall operator provides information about the screens actually used to render a page, rather than those requested by a job. These are different because of the various overrides provided by the RIP and because a screen is sometimes set but never used.

A typical use of screenforall is to enumerate screens used by a page. The following example prints the names and angles of screens used in a page from the EndPage procedure. If used as a page feature, this example would report screens used in the PostScript language, PDF, or TIFF/IT-P1 pages.

TEXT

  <<
    /EndPage {
      exch pop 2 ne % determines whether to print the page
      dup {
        % procedure to print each name and angle:
        { exch = ( ) print = (\n) print }
        % dictionary to control operator:
        <<
          /Report /All
          /Duplicate false
          /Output [ /HalftoneName /Angle ]
        >>
        statusdict /screenforall get exec
      } if
    } bind
  >> setpagedevice

A specialized use of screenforall is to interpret the screen index embedded in run-length encoded (RLE) raster data, described in [SWRLE], for substitution in a RLE consumer.

RLE is only available with the Harlequin Core.

The screen index allocated by the RIP to each unique screen can be determined using the ScreenIndex name in the Output array of the screenforall operand dictionary. The characteristics of that screen can also be extracted and passed to the RLE consumer so that it can substitute the correct screen when that index is encountered in the run-length raster data.

Regarding partial paint, each paint is a separate page for the purposes of /Report /All.

Also note that if a screen is not used by any object, it is discarded once another screen has come into play, and so not reported by screenforall. For example, consider:

TEXT

  ...
  f a { exch pop } setscreen % (1)
  gsave
  ...
  f a { pop } setscreen % (2)
  { = } % procedure for screenforall at comment 3
  <<
    /Report /Current
    /Duplicate false
    /Output [ /ScreenIndex ]
  >>
  screenforall % (3)
  grestore % (4)
  { = } % procedure for screenforall at comment 5
  << /Report /All /Duplicate false /Output [ /ScreenIndex ] >> screenforall % (5)
  ...

In this example, the screenforall at comment (3) will report (only) the screen set at (2), but the screenforall at (5) will report the screen set at (1) (and any others up to that point), but not that set at (2) because it was discarded on the grestore at (4).

The operator

proc dict screenforall -

Procedure proc is called once for each screen selected according to the criteria given in dict.
Before calling proc , a number of objects are pushed onto the operand stack which should all be consumed by proc. The number is determined by the criteria given in dict.
dict must supply all three entries listed in the table below.

screenforall is located in statusdict.

Screenforall dict operand

Duplicate

Boolean

(required) If false, a screen is reported only once (assuming the other criteria cause it to be reported at all) to the proc operand. If true, screen is reported for each occasion and each color it is used.

Report

name

(required) Report must be one of the literal names All, Current, or New.

All causes every screen known to the RIP to be reported with a call to the operator’s proc operand. If Duplicate is false, this excludes screens where the screen is not used. (Solid and clear colors do not typically use a screen.)

Current supplies only the screen currently in force. Typically, this would be used with Duplicate set true to discover all variations of the screen for all colors.

New reports only those screens not previously reported with screenforall, again subject to the setting of Duplicate.

Output

array of names

(required) Output lists the features of a screen which should be provided to the proc operand of screenforall. Each entry in the array represents one operand pushed on the operand stack, in the order given in the array. Therefore, proc must consume exactly the same number of operands as there are entries in the Output array. Duplicates are allowed: the same operand may be pushed several times if required. The permitted keys are described in the following section.

Output array contents

Frequency (screenforall array)

real

For spot function screens, the nominal frequency of the screen, either as requested by the job or as overridden by the RIP, as appropriate. For other types of screens, this number is meaningless and is returned as a constant, 60.0.

Angle (screenforall array)

real

For spot function screens, the nominal angle of the screen in degrees, either as requested by the job or as overridden by the RIP as appropriate. For other types of screens, this number is meaningless and is returned as a constant, 0.0.

SpotFunction (screenforall array)

array or null

The spot function procedure of the screen. In some circumstances (for example after a restore, or for threshold screens), a spot function may not be available, in which case a null object is returned.

AccurateScreens (screenforall array)

Boolean

true if the screen was generated using Harlequin Precision Screening, and false otherwise.

PatternScreen (screenforall array)

Boolean

true if the RIP has determined that the screen is a pattern screen. See Pattern and degenerate screens.

ActualFrequency (screenforall array)

real

For spot function screens, the actual frequency of the screen (in lines per inch) as achieved on the raster, after any adjustment by HPS. This is the same value that would be returned for the standard ActualFrequency key of a type 1 halftone dictionary. For other types of screens, this is set to a constant, 60.0.

ActualAngle (screenforall array)

real

For spot function screens, the actual angle (in degrees) as achieved on the raster, after any adjustment by HPS. This is the same value that would be returned for the ActualAngle key of a type 1 halftone dictionary. For other types of screens, this is set to a constant, 0.0.

FrequencyDeviation (screenforall array)

real

The aim frequency which was chosen by HPS for the screen (and all the others in the same set of screens). The nominal frequency for the screen is adjusted to this deviated frequency according to the limits permitted by HPS parameters. Choosing a slightly different frequency allows more accurate angles to be produced in a reasonable amount of memory, thereby reducing moiré. Each color’s frequency may then differ slightly from this aim frequency, by a tolerance given by the ScreenFrequencyAccuracy system parameter.

For non-HPS spot function screens, this is the same as the Frequency. For other types of screens, this is set to a constant, 60.0.

FrequencyAccuracy (screenforall array)

real

For spot function screens, the amount by which the frequency achieved for the screen (ActualFrequency) differs from the deviated frequency, or for non-HPS screens, the requested frequency. For other types of screens, this is 0.0.

AngleAccuracy (screenforall array)

real

For spot function screens, the amount by which the angle achieved for the screen (ActualAngle) differs from the angle requested. For other types of screens, this is 0.0. For HPS, it should be a very small magnitude number.

HalftoneType (screenforall array)

integer

If the screen is a threshold screen this is returned as 3, if a spot function screen as 1, if a modular screen as 100, if a tile screen as 116. A screen mix (type 1009) returns 3 or 1, depending on the base screen of the mix.

This is not the same as how the screen was originally expressed in PostScript language or PDF, so it would never be 4 or 6, for example, if the original screen were specified in a HalftoneType 4 or 6 dictionary.

HalftoneModule (screenforall array)

string

For a modular screen, this is the name of the screening module, otherwise null.

HalftoneName (screenforall array)

name

A name by which the screen is known. Anonymous screens return the name Unknown. The name of a screen is determined by (a) whether it matches a built-in named spot function (such as Euclidean), or (b) whether the halftone dictionary defining the screen (if any) supplied a name for the screen in the HalftoneName key.

HalftoneColor (screenforall array)

name

The colorant for which the screen was being applied. When Duplicate is false, only one of the colorant for which the screen is being used is listed; which one is arbitrary.

ScreenIndex (screenforall array)

integer

This number is used to identify different screens within RLE output, enabling an RLE backend to do its screening according to the job or the RIP configuration, where that has been set to override. See RLE documentation for details.

RLE is only available with the Harlequin Core.

ColorIndex (screenforall array)

integer

A number corresponding to the HalftoneColor name. 0, 1, 2, and 3 are for Cyan and Red and Gray, Magenta and Green, Yellow and Blue, and Black respectively (according to whether the device color space is DeviceCMYK, DeviceRGB or DeviceGray). Spot colors are represented by higher numbers; and -1 represents the Default screen (as supplied in a type 5 halftone dictionary).