Skip to content

fix(flame_3d): Fix alpha blend factors for transparent background compositing#3812

Open
agnath18K wants to merge 1 commit intoflame-engine:mainfrom
agnath18K:fix/flame_3d-alpha-blend
Open

fix(flame_3d): Fix alpha blend factors for transparent background compositing#3812
agnath18K wants to merge 1 commit intoflame-engine:mainfrom
agnath18K:fix/flame_3d-alpha-blend

Conversation

@agnath18K
Copy link
Contributor

Description

Fixes #3811

The alphaBlend path in GraphicsDevice.begin() sets sourceAlphaBlendFactor: oneMinusSourceAlpha, which zeroes the alpha channel for opaque fragments:

result_alpha = src_alpha * (1 - src_alpha) = 1.0 * 0.0 = 0

The GPU texture has valid RGB but zero alpha, so it becomes invisible when composited onto the Flutter canvas via srcOver.

This swaps the factors to match the standard premultiplied "over" operator:

  • sourceAlphaBlendFactor: one — preserves source alpha
  • destinationAlphaBlendFactor: oneMinusSourceAlpha — blends with destination

Checklist

  • I have followed the Contributor Guide when preparing my PR.
  • I have updated/added tests for ALL new/updated/fixed functionality.
  • I have updated/added relevant documentation in docs and added dartdoc comments with ///.
  • I have updated/added relevant examples in examples or docs.

The blend equation change is purely in the GPU pipeline — not feasible to unit test without a real GPU context. Verified manually by rendering models with clearColor: 0x00000000 and compositing over Flutter widgets.

Breaking Change?

  • Yes, this PR is a breaking change.
  • No, this PR is not a breaking change.

Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR attempts to fix transparent background compositing in flame_3d by correcting the alpha blend factors used in the GPU pipeline. The issue was that the alpha channel was being zeroed out for opaque fragments due to incorrect blend factor configuration, making rendered 3D scenes invisible when composited over Flutter widgets.

Changes:

  • Modified alpha blend factor configuration in GraphicsDevice.begin() to use premultiplied alpha "over" operator

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@@ -84,9 +84,9 @@ class GraphicsDevice {
..setColorBlendEnable(true)
..setColorBlendEquation(
gpu.ColorBlendEquation(
Copy link

Copilot AI Feb 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fix is incomplete. According to the PR description and issue #3811, the correct premultiplied "over" operator requires setting BOTH source and destination alpha blend factors:

  • sourceAlphaBlendFactor: one (to preserve source alpha)
  • destinationAlphaBlendFactor: oneMinusSourceAlpha (to blend with destination)

The current change only sets destinationAlphaBlendFactor without setting sourceAlphaBlendFactor. This means the source alpha blend factor is not configured at all, which may result in undefined or default behavior that doesn't match the intended fix. The ColorBlendEquation constructor should include both parameters.

Suggested change
gpu.ColorBlendEquation(
gpu.ColorBlendEquation(
sourceAlphaBlendFactor: gpu.BlendFactor.one,

Copilot uses AI. Check for mistakes.
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.

[flame_3d] Transparent backgrounds don't work — alpha zeroed out by blend equation

1 participant