The space a page mixes its colours in

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

When two half-transparent colours overlap, something has to decide how they combine. Depending on the way of counting, the result is not quite the same: a half-transparent red laid over a blue can turn out slightly differently from one device to the next. The rule can be fixed once and for all at the page level: here is the space everything mixes in. The result then comes out the same everywhere.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

transparency makes every page a transparency group: its marks composite among themselves in the space named here, rather than in whatever space each of them happened to be painted in. That is what makes a half-opaque red over a blue come to the same colour wherever the page is shown. The space named is one color_spaces declares; two settings complete the group, isolation and knockout.

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

• transparency — object, optional, absent by default.
• transparency.space — string, required. The name of a colour space declared by color_spaces. A name the request did not declare is refused, and the answer names it.
• transparency.isolated — boolean, optional, false by default. The group starts from nothing rather than from what lies behind the page.
• transparency.knockout — boolean, optional, false by default. A mark inside the group replaces what an earlier mark of the same group put down, rather than compositing with it.
• The setting holds for every page of the document. The opacity and blend mode of one particular shape are set through graphics_states.

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

{
  "color_spaces": [
    {
      "name": "blend",
      "space": { "cal_rgb": { "white_point": [0.9505, 1.0, 1.089] } }
    }
  ],
  "transparency": { "space": "blend", "isolated": true },
  "graphics_states": [{ "name": "half", "state": { "fill_alpha": 0.5 } }],
  "items": [
    {
      "type": "rect",
      "rect": { "llx": 60, "lly": 700, "urx": 200, "ury": 790 },
      "fill": [0.85, 0.15, 0.15]
    },
    {
      "type": "rect",
      "rect": { "llx": 140, "lly": 660, "urx": 280, "ury": 750 },
      "fill": [0.15, 0.3, 0.85],
      "graphics_state": "half"
    }
  ]
}

The line that sends it, in three languages

Glossary

transparency

Paint that lets what is underneath it come back through, by a stated amount. It is what makes a mark laid across a page leave the text under it readable, and a highlight a highlight rather than a blot. The file says how much comes through; whatever draws the page works out the colour that results.

request

One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.

colour space

The rule that says what a set of numbers means as a colour. The same three numbers are one red on a screen and another on a press, so a document says which rule it is speaking under. Say nothing and three numbers are read as the lights of a screen.

blend mode

The rule for what happens to the colour where one mark is laid over another: covered up, darkened, lightened, multiplied. The plain rule is that the top one wins.

Every word the site explains