Skip to content

Document transparency, blend state and dual-source blending - #1097

Open
mvaligursky wants to merge 5 commits into
mainfrom
codex/document-dual-source-blending
Open

Document transparency, blend state and dual-source blending#1097
mvaligursky wants to merge 5 commits into
mainfrom
codex/document-dual-source-blending

Conversation

@mvaligursky

@mvaligursky mvaligursky commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Warning

Do not merge this PR until PlayCanvas Engine 2.22 is released.

Overview

Documents transparency in the graphics user manual, and the dual-source blending support
introduced by playcanvas/engine#9096.

Rebased onto main (it was 50 commits behind, and pinned an older engine). Now also carries the
Transparency page previously proposed in #1157, so that the two pages can cross-link - they cover
the same subject from different levels, and neither could link to the other while they were
separate branches.

Changes

Transparency page (user manual)

  • New Transparency page under user-manual/graphics, placed after Physically Based Rendering,
    covering alpha blending, alpha test, opacity dithering and alpha to coverage. Each 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. The manual previously had no conceptual coverage of
    transparency at all.
  • Documents Material#blendState for full control over the blend equation, per-channel factors
    and write mask, the ready-made BlendState constants, and that the getter is a read-only view
    so the setter must be used to keep transparency and sort state in sync.
  • Documents per-attachment blending via BlendState#setAttachment (indices 1 to 7, with
    unassigned attachments following attachment 0), gated on
    GraphicsDevice#supportsIndependentBlending.
  • Documents that alpha to coverage requires a multi-sampled render target and is silently
    ignored
    otherwise, plus the WebGPU-only requirement that the first color attachment use a
    blendable format with an alpha channel - which CameraFrame does not satisfy by default, as
    PIXELFORMAT_111110F has no alpha. Notes that WebGL has no such restriction, so this is a
    deliberate difference between the backends rather than a bug.

Dual-source blending (advanced rendering)

  • Adds a cross-platform Dual-Source Blending page under Advanced Rendering.
  • Documents WebGPU dual-source-blending and WebGL 2 WEBGL_blend_func_extended support.
  • Covers capability detection, secondary-source blend constants, StandardMaterial, ShaderMaterial, and low-level shader definitions.
  • Documents the single-color-attachment restriction and links it from the MRT page.
  • Adds WGSL and GLSL shader-page cross-references.
  • Links to the engine example using the canonical examples-browser URL.

Cross-linking

  • The blend state section links to the Dual-Source Blending page, and the dual-source page links
    back to Transparency for how blend state relates to the other transparency options.

Matching Japanese documentation is included for every changed and added page.

Validation

  • npm run build succeeds for both locales (build and build/ja), which confirms the new
    cross-links resolve.

@mvaligursky
mvaligursky force-pushed the codex/document-dual-source-blending branch from 93ad2bd to 51a2223 Compare August 21, 2026 11:15
@mvaligursky mvaligursky changed the title Document dual-source blending Document transparency, blend state and dual-source blending Aug 21, 2026
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