Skip to content

refactor(engine)!: GPU pass fusion stack 5/5 — shader migration - #2171

Closed
yuto-trd wants to merge 1 commit into
speckit/004-s4-evidencefrom
speckit/004-s5-shader-migration
Closed

refactor(engine)!: GPU pass fusion stack 5/5 — shader migration#2171
yuto-trd wants to merge 1 commit into
speckit/004-s4-evidencefrom
speckit/004-s5-shader-migration

Conversation

@yuto-trd

@yuto-trd yuto-trd commented Aug 1, 2026

Copy link
Copy Markdown
Member

Description

Stacked-PR slice 5/5 of speckit/004-gpu-pass-fusion.

This final slice moves the non-Gaussian Shader migration into its own review boundary:

  • nine per-pixel color effects record deferred CurrentPixel descriptions using cached parsed SkslSource instances;
  • ColorShift, Mosaic, and the displacement-map transforms record WholeSource descriptions;
  • existing CustomEffect shader consumers use explicit same-footprint allocation, replacement, and mapped-input helpers;
  • SKSLShaderBuilder owns per-build state and exposes caller-owned Build() results without leaking the disposable runtime effect;
  • LUT recording and resource-lifetime coverage move with the Shader consumer;
  • empty DrawableBrush displacement maps render transparently in both transform and ShowDisplacementMap paths, while Delivery allocation failures remain fatal.

Blur.cs and DropShadow.cs remain outside this migration slice. The final S1-S4 review changes and immutable evidence archive are propagated through ordinary signed merge commits.

Stack

  1. speckit/004-s1-spec — specification and contracts
  2. speckit/004-s2-engine — record-then-plan engine and consumer migration
  3. speckit/004-s3-tests — pipeline and rendering test suites
  4. speckit/004-s4-evidence — benchmarks, paired evidence, and acceptance
  5. This PR — built-in Shader migration, excluding Blur and DropShadow

Affected areas

  • Beutl.Engine (rendering / scene / track)
  • Beutl.ProjectSystem (project / document persistence)
  • UI (Beutl.Editor, Beutl.Editor.Components, Beutl.Controls)
  • Beutl.Extensibility (plugin abstractions)
  • Beutl.NodeGraph (node editor)
  • Beutl.FFmpegIpc / Beutl.FFmpegWorker (media IPC boundary)
  • Beutl.Api (server API client)
  • Build / CI / docs only

Breaking changes

SKSLShader.ApplyToNewTarget and SKSLShader.Effect are removed. Allocate with CustomFilterEffectContext.CreateTargetLike or CreateTarget, map inputs with UseMappedInputShader, configure metadata through SKSLShaderBuilder.Uniforms and Children, and render with SKSLShader.RenderToTarget. The caller owns each SKShader returned by SKSLShaderBuilder.Build().

The lower stack also contains the documented Beutl.Engine render-authoring migration. Downstream plugins must use named resource bindings, immutable callback state, PaintedRenderCanvas, IRenderTargetFactory.MaximumDimension, and an explicit RenderAllocationBudget as described in the S1/S2 breaking-change contract.

Review follow-up (2026-08-09)

  • Corrected replacement-target allocation diagnostics to name the actual target density.
  • Removed the inaccurate claim that every empty SKSL replacement has a preceding allocation warning.
  • Cached parsed SkslSource objects for all migrated current-pixel built-ins, including separate LUT 1D and 3D sources.
  • Routed empty DrawableBrush displacement maps through one owned transparent-shader fallback for both transform and ShowDisplacementMap paths.
  • Preserved Delivery allocation failures instead of converting them to transparent output.
  • Made ShowDisplacementMap replacement transactional: draw failure disposes the uncommitted target and preserves the original slot; success commits the replacement before disposing the original.
  • Added direct failure/success ownership tests and preserved the primary exception if cleanup itself fails.
  • Propagated final S4 evidence with an ordinary signed no-ff merge, then migrated the one S5-only render-target factory fixture in a separate signed commit.

All five unresolved inline review threads were answered and resolved.

Test plan

  • Fresh solution build: passed with 0 warnings and 0 errors.
  • Shader migration focused suite: 103/103 passed.
  • Displacement focused suite: 76/76 passed.
  • Final ownership fixture: 24/24 passed.
  • Evidence and instrumentation suite: 171/171 passed.
  • PR fix: draw SourceBackdrop from the current pass, not the previous render #2189 frame-order/backdrop regression suite: 5/5 passed on the new renderer.
  • Beutl.PublicApiContractTests: 195/195 passed.
  • SourceGeneratorTest: 30/30 passed.
  • Beutl.HeadlessUITests: 250/250 passed.
  • GPU Beutl.Graphics3DTests: 14/14 passed with no skips.
  • Solution-wide format verification: 3,473 files checked, 0 changed.
  • GPL/MIT boundary scan, three evidence-script syntax checks, conflict-marker scan, ancestry, signatures, and clean-status checks: passed.

Full UnitTests was green before the final ownership-test addition: 6,486 passed, 3 skipped, 0 failed. On the final tree, two full runs each produced 6,487 passed, 3 skipped, and one failure in the unrelated ProxyJobQueueTests.Cancel_ParkedUnavailableJob_WakesDrainLoopWithoutWaitingBackoff test. The isolated case passed, while repeated fixture execution reproduced the pre-existing lost-cancel race on run 25. Proxy queue production and tests are byte-identical to main and S4 and were intentionally not changed in this GPU pass-fusion PR.

Evidence status

  • Paired visual: PASS, 44/44 scenes.
  • Paired benchmark: overallAcceptancePassed=false; T123 remains pending.
  • Focused tests and GPU gates do not override formal paired acceptance.

Fixed issues / References

  • Feature 004: renderer-wide GPU pass fusion

Review follow-up (2026-08-10)

  • Propagated the final S1-S4 review fixes and historical evidence through an ordinary signed no-ff merge.
  • Migrated the remaining S5-only LUT target factory to descriptor-specific maximum-dimension queries.
  • Preserved the finite InnerShadow parity fixture and expression-bodied getter census fix that close the prior x64 SwiftShader CI failures.
  • Replied to and resolved the newly raised breaking-footer thread with the actual signed owning commit and literal migration footer.
  • Preserved every S5 shader, displacement fallback, Delivery failure, and transactional replacement implementation byte-for-byte.

Validation at final HEAD:

  • Fresh solution build: 0 warnings / 0 errors.
  • S5 shader, displacement, ownership, InnerShadow, and getter suite: 152/152.
  • Final S4 evidence: 120/120; GPU live evidence: 56/56.
  • PR fix: draw SourceBackdrop from the current pass, not the previous render #2189 exact frame-order tests: 5/5; adjacent backdrop suite: 16/16.
  • PublicApiContractTests: 213/213; SourceGeneratorTest: 30/30.
  • Headless: 254/254; GPU Graphics3D: 14/14.
  • Solution format: 3,475 checked / 0 changed; GPL boundary, script syntax, diff, conflict, ancestry, and signature checks passed.

Two final full UnitTests runs each produced 6,498 passed, 3 skipped, and one failure in the unchanged main-identical ProxyJobQueueTests.Cancel_ParkedUnavailableJob_WakesDrainLoopWithoutWaitingBackoff race; the isolated test passed 1/1. No Proxy code or tests were changed. The final historical evidence manifest is f10ab3ba6f03f36621c9e4254d7cb9467481fce301245b75434855e75b2c9303; formal performance gates remain false and T123 remains pending.

@coderabbitai

coderabbitai Bot commented Aug 1, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5af3bae2-481f-485f-bdc5-afcfcacb63db

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@greptile-apps

greptile-apps Bot commented Aug 1, 2026

Copy link
Copy Markdown

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename Overview
src/Beutl.Engine/Graphics/FilterEffects/SKSLShader.cs Defines per-builder state and explicit ownership of built shaders while keeping the runtime effect owned by the parent shader.
src/Beutl.Engine/Graphics/FilterEffects/ColorShift.cs Replaces immediate rendering with a deferred WholeSource shader and explicit forward and backward bounds mappings.
src/Beutl.Engine/Graphics/FilterEffects/DisplacementMapEffect.cs Implements transparent empty-map rendering and transactional replacement that preserves the original target on draw failure.
src/Beutl.Engine/Graphics/FilterEffects/DisplacementMapTransform.cs Migrates displacement transforms to deferred shaders while retaining the mapped legacy DrawableBrush path.
src/Beutl.Engine/Graphics/FilterEffects/CustomFilterEffectContext.cs Adds explicit target allocation, replacement, and mapped-input operations used by migrated shader consumers.
tests/Beutl.UnitTests/Engine/Graphics/FilterEffects/WholeSourceFilterEffectTests.cs Covers WholeSource recording, displacement fallback behavior, and ColorShift bounds metadata.

Reviews (29): Last reviewed commit: "refactor(engine)!: stack 5/5 — migrate b..." | Re-trigger Greptile

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a2302ae19e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/Beutl.Engine/Graphics/FilterEffects/SKSLShader.cs
@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from a2302ae to 9163623 Compare August 1, 2026 19:08
@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from 9163623 to 2200c61 Compare August 1, 2026 19:23

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2200c61c34

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/Beutl.Engine/Graphics/FilterEffects/CustomFilterEffectContext.cs Outdated
@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from 2200c61 to cf41190 Compare August 1, 2026 19:34
@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from cf41190 to 8738e28 Compare August 1, 2026 21:02
@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from 8738e28 to 9c9f4af Compare August 1, 2026 21:17
@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from 9c9f4af to 2228754 Compare August 1, 2026 21:40

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2228754db5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/Beutl.Engine/Graphics/FilterEffects/SKSLScriptEffect.cs Outdated
@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from 2228754 to f08d99e Compare August 1, 2026 22:51
@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from f08d99e to 13fad9d Compare August 2, 2026 02:44
@drift-check

drift-check Bot commented Aug 2, 2026

Copy link
Copy Markdown

Code Review Bot

No comment/code divergences or documentation drift detected. Reviewed 38 file(s); skipped 6.

@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from 13fad9d to 5260b9e Compare August 2, 2026 11:55
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

Copilot AI lite review requested due to automatic review settings August 5, 2026 04:50
@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from 5260b9e to 1d84d47 Compare August 5, 2026 04:50
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from cf164a4 to a25fe7a Compare August 7, 2026 23:40
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from a25fe7a to ea1d94a Compare August 8, 2026 00:49
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9885d95796

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/Beutl.Engine/Graphics/FilterEffects/DisplacementMapTransform.cs Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: db38a972c0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/Beutl.Engine/Graphics/FilterEffects/ColorGrading.cs Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 970dbcf4d1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/Beutl.Engine/Graphics/FilterEffects/SKSLShader.cs

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1116b63574

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/Beutl.Engine/Graphics/FilterEffects/GLSLScriptEffect.cs
Comment thread src/Beutl.Engine/Graphics/FilterEffects/LutEffect.cs
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

1 similar comment
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from 7dd5c0c to 36f8e97 Compare August 10, 2026 15:00
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

1 similar comment
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@github-actions

Copy link
Copy Markdown
Contributor

No TODO comments were found.

@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from 36f8e97 to a795101 Compare August 10, 2026 18:38
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@github-actions

Copy link
Copy Markdown
Contributor

No TODO comments were found.

Nine pixel-wise color effects, ColorShift, Mosaic, and the
displacement-map transforms migrate to the SKSL/GLSL shader pipeline
with explicit target ownership; the SKSLShaderBuilder ownership change
and LUT snapshot/reuse (ConditionalWeakTable under the ownership gate)
are included. Blur and DropShadow stay on the legacy path.

The ColorShift snapshot-intent tests are dropped with the removed
readback-failure surface; the FrameProviderImpl retention-heuristic test
stays excluded with its separately shipped change.
@github-actions

Copy link
Copy Markdown
Contributor

Code Coverage

Package Line Rate Branch Rate Complexity Health
Beutl 27% 18% 11330
Beutl.AgentToolkit 90% 74% 7517
Beutl.Api 31% 18% 1422
Beutl.Benchmarks 57% 40% 2448
Beutl.Configuration 63% 40% 425
Beutl.Controls 35% 15% 5555
Beutl.Core 70% 61% 3108
Beutl.Editor 82% 79% 2865
Beutl.Editor.Components 23% 15% 9788
Beutl.Embedding.MediaFoundation 6% 8% 1374
Beutl.Engine 78% 68% 30644
Beutl.Engine.SourceGenerators 61% 45% 548
Beutl.ExceptionHandler 0% 0% 45
Beutl.Extensibility 71% 74% 167
Beutl.Extensions.AVFoundation 5% 2% 202
Beutl.Extensions.FFmpeg 28% 26% 738
Beutl.Extensions.FFmpeg.Core 50% 30% 323
Beutl.FFmpegIpc 27% 35% 858
Beutl.FFmpegWorker 4% 4% 898
Beutl.Language 52% 50% 1515
Beutl.NodeGraph 33% 22% 2567
Beutl.PackageTools.UI 0% 0% 676
Beutl.ProjectSystem 79% 64% 1296
Beutl.Testing.Headless 88% 92% 15
Beutl.Threading 99% 88% 137
Beutl.Utilities 94% 87% 358
Beutl.WaitingDialog 0% 0% 36
Iciclecreek.Avalonia.Terminal 35% 22% 1164
XTerm.NET 15% 7% 2009
Summary 54% (124831 / 232989) 44% (31443 / 70707) 90028

Minimum allowed line rate is 0%

@yuto-trd
yuto-trd force-pushed the speckit/004-s5-shader-migration branch from a795101 to 72417e0 Compare August 10, 2026 23:47
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@github-actions

Copy link
Copy Markdown
Contributor

No TODO comments were found.

@yuto-trd

Copy link
Copy Markdown
Member Author

Superseded by #2221, which merges every layer of this stack into one branch, propagates the s2 reduction through layers 3–5 (this stack no longer built above s2), and drops the 61.5 MB evidence archive.

@yuto-trd yuto-trd closed this Aug 12, 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.

2 participants