Design Proposal: {line,fill,circle,..}-layer-blend for layer compositing modes

Motivation

MapLibre currently composites layers using a fixed blending model normal.

While existing paint properties control color and opacity, there is currently no way to control how a layer blends with previously rendered content.

Modern graphics systems commonly expose compositing or blending controls such as normal, multiply, screen, overlay, darken, lighten, plus, erase, ...

These are useful for:

• cartographic emphasis
• hillshade and terrain rendering
• heatmap and glow effects
• annotation overlays
• artistic/stylized maps
• improved visual integration between raster/vector layers

Currently, these effects require:

• preprocessing assets externally
• custom rendering pipelines
• additional render passes
• engine-specific extensions

A standardized layer-level blending mechanism would allow these effects to be expressed directly in the style specification.

layer-blend	without blending	with blending
multiply
colour burn
(multiple layers, see post)

All images from https://www.helenmakesmaps.com/post/how-to-use-blending-modes-in-mapping

Requirements

The style specification should support controlling how a fully composited layer blends with existing framebuffer contents.

*-layer-blend is evaluated after all features in the layer have been composited, and therefore applies to the layer output as a whole rather than to individual features.

Therefore, the compositing model is:

• features are rendered normally into the layer output
  existing *-opacity properties continue to apply during feature compositing
• *-layer-opacity, if present, is applied to the composited layer output before blending
• *-layer-blend defines how the final layer output is composited into the destination framebuffer

Proposed Change

Add new paint properties {line,fill,circle}-layer-blend

These properties control how the composited output of the layer blends with existing framebuffer contents.

Initial supported values could include normal, multiply, screen, overlay, darken, lighten, plus, erase, ...

The properties would:

• be data-constant
• support transitions
• support zoom expressions

Unlike existing paint properties, these properties affect framebuffer compositing behaviour rather than feature styling.

Migration Plan and Compatibility

This proposal is fully backwards compatible.

Rejected Alternatives

Alternative approaches discussed include:

• render-pass systems
• custom shader hooks
• engine-specific extensions

These approaches are intentionally out of scope for this proposal.