Opacity and how colours mix

Declare a painting setting — half-transparency, a blend mode — then apply it to shapes by its name.

Written at the top level of a request, under "graphics_states"

In plain words

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

A highlighter lets the text below show through: the colour does not hide, it mixes. The same is possible here. You set once "paint at half transparency", or "mix by darkening", give that setting a name, and apply it to the shapes you want. Sixteen ways of mixing exist, the ones drawing software uses: multiply, lighten, difference.

For a developer

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

graphics_states declares the graphics states the document defines for itself, each under the name a drawn shape applies it by. A state is written once however many shapes apply it, and it lasts as long as the shape that named it and no longer. Only what it names is written: a state naming an opacity and nothing else leaves everything else as it stands.

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.

  • graphics_states — array, optional, empty by default.
  • graphics_states[].name — string, required. The name items apply this state by.
  • graphics_states[].state — object, required.
  • state.fill_alpha — number from 0 to 1, optional. The opacity every fill is painted at: 0 lets everything through, 1 covers.
  • state.stroke_alpha — number from 0 to 1, optional. The opacity every stroke is painted at. Fill and stroke are said apart: a shape half transparent outside and whole inside names both.
  • state.blend_mode — string, optional. Sixteen values: normal, multiply, screen, overlay, darken, lighten, color_dodge, color_burn, hard_light, soft_light, difference, exclusion, hue, saturation, color, luminosity. The first twelve mix each channel on its own, the last four take a whole colour at a time.
  • A path or rect item applies a state through its graphics_state key.

A whole request that draws it

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

{
  "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

Colour and how it is shown

The device the colours are stated for Declaring colour beyond red, green and blue A colour sliding into another The space a page mixes its colours in

Where to go next

Every key of a request, in one page The other thirty-two settings of a request

See the prices See the examples

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.
graphics state
The set of settings in force while something is being drawn: how see-through it is, how two colours mix where they overlap, the shape of the ends of a line. A shape names one and it holds for that shape alone.

Every word the site explains