(v13) 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.

  <<
    /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.

Note that if a partial paint occurs - that is, the page is rendered to a raster before it is complete, and a new display list started - then any screens unused in the remainder of the page are discarded, and will not, therefore, be reported in a subsequent screenforall. This behavior can be changed by setting the system parameter PreserveScreens to true, at the cost of retaining the memory required to hold the screen. Regarding partial paint, each paint is a separate page for the purposes of /Report /All.

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

  ...
  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).

Screenforall

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 colors do not use a screen). (Solid and clear colors do not always 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 name

(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

The nominal frequency of the screen, either as requested from PostScript language or as overridden by the RIP, as appropriate. For threshold and modular screens, this number is meaningless and is returned as a constant, 60.0.

Angle (screenforall array)

real

The nominal angle of the screen in degrees, either as requested from PostScript language or as overridden by the RIP as appropriate. For threshold, modular and HDS 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. Pattern screens are typically only usable with a single particular frequency, angle, resolution, and gray level combination and without the special action the RIP takes for them would not be rendered correctly on continuous tone devices or where overrides for frequencies, angles and spot functions are used, or where calibrated. See (v13) Pattern and degenerate screens.

ActualFrequency (screenforall array)

real

The actual frequency of the screen in lines per inch, after adjustment by HPS. This is the same value that would be returned for the standard ActualFrequency key of a type 1 halftone dictionary. For threshold and modular screens this is set to a constant, 60.0.

ActualAngle (screenforall array)

real

The actual angle (in degrees) used for the screen after adjustment by HPS. This is the same value that would be returned for the ActualAngle key of a type 1 halftone dictionary. For threshold and modular 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 screens, this is the same as the Frequency. For threshold and modular screens this is set to a constant, 60.0.

FrequencyAccuracy (screenforall array)

real

The amount in lines per inch by which the frequency computed for the screen differs from the deviated frequency. For non-HPS screens, including threshold and modular screens, this is 0.0.

AngleAccuracy (screenforall array)

real

The amount in degrees by which the angle computed for the screen differs from the angle requested (that is, ActualAngle Angle). For non-HPS screens, including threshold and modular 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, otherwise 1. For modular screens 100 is returned.

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

This is the name of the screening module. Screening modules are the clients of the screening interfaces and are principally required to perform Raster halftoning, but they can also choose to receive object-type information for the raster to enable them to vary their screening techniques accordingly. For more information about modular screening see Chapter 2 of the API Reference Manual “Screening interface”.

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, an Adobe extension described in [EXTN2017].

HalftoneColor (screenforall array)

name

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

ScreenIndex (screenforall array)

integer

Every time the screen is changed, the RIP assigns a number unique within any one run of the RIP to the new screen (whether or not it is a duplicate of an already encountered screen). This number is also embedded within RLE rasters. This number could be used to key a table of screens if one is being maintained in a PostScript language dictionary, for example.

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).