Skip to content

Add a Transparency page to the graphics user manual - #1157

Closed
mvaligursky wants to merge 2 commits into
mainfrom
mv-transparency-docs
Closed

Add a Transparency page to the graphics user manual#1157
mvaligursky wants to merge 2 commits into
mainfrom
mv-transparency-docs

Conversation

@mvaligursky

@mvaligursky mvaligursky commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

The graphics user manual has no conceptual coverage of transparency. Alpha to coverage in
particular appeared only as a single row in the editor inspector and web components reference
tables, and blending, alpha test and opacity dithering were not explained anywhere. This adds a
page that covers all four and, more importantly, when to choose each.

Changes:

  • New Transparency page under user-manual/graphics, placed after Physically Based Rendering
    in the sidebar, covering alpha blending, alpha test, opacity dithering and alpha to coverage.
  • Each technique notes whether it is order dependent, which pass it renders in, and its main
    drawback, with a summary table and a short "which one should I use" guide.
  • Documents that alpha to coverage requires a multi-sampled render target and is silently
    ignored
    otherwise, which is the most likely thing to be reported as a bug.
  • Documents the WebGPU-only requirement that the first color attachment use a blendable format
    with an alpha channel, and that CameraFrame defaults to PIXELFORMAT_111110F, which has
    none - so alpha to coverage does nothing through CameraFrame unless a format with alpha is
    requested. Also notes that WebGL has no such restriction, so this is a deliberate difference
    between the backends rather than a bug.
  • Japanese translation added alongside, keeping the graphics section at full ja parity.

Note on timing: the alpha to coverage section describes behaviour that requires engine
2.22 (playcanvas/engine#9208, which wires the flag into the WebGPU pipeline). The rest of the
page documents existing behaviour. Please hold until 2.22 ships.

Follow-up needed: two cross-links with #1097 (dual-source blending)
are deliberately omitted, because the dual-source page does not exist on main yet and
onBrokenLinks defaults to throw, so linking it now would fail this PR's build. Once #1097
merges, the blend state section should link to the dual-source page, and the dual-source page
should link back here. Whichever of the two merges second is the natural place to add them.

@mvaligursky

Copy link
Copy Markdown
Contributor Author

Superseded by #1097. Rebased that branch onto main and moved the Transparency page into it, so the two pages can cross-link - while they were separate branches neither could link to the other's page without failing the build (onBrokenLinks defaults to throw). Branch mv-transparency-docs left in place; nothing lost.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant