gum-monogame-rendering
Skill659 starsChanged 2 months agoMITView on GitHub
Gum's MonoGame rendering pipeline — Renderer/SpriteBatchStack/GumBatch, BatchKey transitions, SpriteBatch ↔ Apos.Shapes ShapeBatch interleaving. Triggers: Renderer.cs, SpriteBatchStack.cs, GumBatch, RenderableShapeBase, SpriteBatchRenderableBase, BatchKey, draw-order bugs, GumRenderBatch in FRB2/MonoGameGumImmediateMode, shaders, post-process effects, RenderTargetEffect, SourceShaderFile, outline/glow/shadow effects.
In this repository69 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- debuggingSkill
- frb-build-verificationSkill
- frb-pixel-harnessSkill
- gum-architecture-layersSkill
- gum-bundleSkill
- gum-cliSkill
- gum-cross-platform-unificationSkill
- gum-docs-writingSkill
- gum-file-pathsSkill
- gum-forms-behaviorsSkill
- gum-forms-controlsSkill
- gum-forms-default-visualsSkill
- gum-forms-itemscontrolSkill
- gum-forms-theme-importSkill
- gum-iconsSkill
- gum-issue-creationSkill
- gum-kernsmith-integrationsSkill
- gum-layout-engineSkill
- gum-layoutSkill
- gum-localizationSkill
- gum-monthly-releaseSkill
- gum-project-versioningSkill
- gum-property-assignmentSkill
- gum-raylib-renderingSkill
- gum-releaseSkill
- gum-runtime-animation-chainsSkill
- gum-runtime-bindingSkill
- gum-runtime-fontsSkill
- gum-runtime-hot-reloadSkill
- gum-runtime-syntax-versionSkill
- gum-runtime-systemmanagers-initSkill
- gum-runtime-topologySkill
- gum-runtime-variable-referencesSkill
- gum-samplesSkill
- gum-serviceSkill
- gum-source-linked-projectSkill
- gum-themingSkill
- gum-tool-animationsSkill
- gum-tool-codegenSkill
- gum-tool-copy-pasteSkill
- gum-tool-delete-logicSkill
- gum-tool-dialogsSkill
- gum-tool-errorsSkill
- gum-tool-file-watchSkill
- gum-tool-font-generationSkill
- gum-tool-import-from-gumxSkill
- gum-tool-loggingSkill
- gum-tool-outputSkill
- gum-tool-pluginsSkill
- gum-tool-save-classesSkill
- gum-tool-screenshotsSkill
- gum-tool-selectionSkill
- gum-tool-tree-viewSkill
- gum-tool-undoSkill
- gum-tool-variable-gridSkill
- gum-tool-variable-referencesSkill
- gum-tool-viewmodelsSkill
- gum-unit-testsSkill
- gum-variable-deep-diveSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 139
RenderableShapeBase.StartBatch/EndBatch: call ShapeBatch.Begin/End — separate GPU state stream, but the runtime now plumbs the active … - Very specific: line 208
When a clip is active, RenderableShapeBase.StartBatch assigns ShapeBatch.GraphicsDevice.ScissorRectangle = scissor.ToXNA() …
- Very specific: line 296
When changing matrix routing, verify alignment with a two-rectangle test (one ColoredRectangleRuntime, one RoundedRectangleRuntime, …
- Distinctive: line 302
When reading a trace:
- Distinctive: line 318
When changing batch logic:
- Very specific: line 325
If you touch basicEffect.World/View or ShapeBatch.Begin(view:), does ForcedMatrix end up applied exactly once to sprite vertices and once …
- Very specific: line 326
If you touch SpriteBatchStack.Begin(bool), does Begin(false) still call SpriteBatch.Begin with all seven currentParameters fields …
- Very specific: line 327
If you touch RenderableShapeBase.StartBatch or ShapeBatch.Begin plumbing, does the active scissor state still flow to the shape batch?
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Gum's MonoGame Rendering Pipeline
This skill covers the XNA-family backends only (MonoGame / KNI / FNA). Skia, Raylib, and Sokol have their own renderers and don't go through this code — for raylib's blend-mode/render-target pipeline see gum-raylib-rendering.
Two Entry Paths into Renderer
Layered path — Renderer.RenderLayer
Used by the Gum tool and any consumer with sorted Layer.Renderables. Walks every renderable in the layer in order. Renderer.Draw(SystemManagers, List<Layer>) and Renderer.Draw(SystemManagers, Layer) share a once-per-host-frame render-target sweep: the first draw after SystemManagers.Activity advances time (or an explicit Renderer.BeginFrame()) calls ClearUnusedRenderTargetsLastFrame(); subsequent Draw(layer) calls in the same host frame accumulate _usedThisFrame marks without re-sweeping (#3416). FRB's GumIdb.Update already calls Activity(TimeManager.CurrentTime) before draw. Draw(SystemManagers) (the GumService path) calls EndFrame() after each full draw so hosts that skip Activity still get a fresh sweep token on the next full draw.
spriteRenderer.BeginSpriteBatch(..., BeginType.Push, ...); // outer SpriteBatch begin
Render(layer.Renderables, ...); // recursive walk
lastBatchOwner?.EndBatch(managers); // flush pending custom batch
EndSpriteBatch(); // (NET<8 only) outer endGumBatch path — Renderer.Begin/Draw/End
Used by FRB2's GumRenderBatch, the immediate-mode samples, and any "I have one renderable, draw it now" consumer. GumBatch is a thin wrapper that calls Renderer.Begin/Draw/End.
Key contract difference: each Renderer.Draw is one top-level renderable. If a consumer draws N elements, that's Begin → Draw → Draw → ... → End. Multiple Begin/End cycles per frame are normal. FRB2's Solitaire trace shows one cycle per card.
Renderer.End historically was asymmetric with RenderLayer's end-of-walk: it called EndSpriteBatch but did not flush the pending custom batch, so draws leaked across cycles. Fixed: Renderer.End now calls _batchOrchestrator.FlushAndReset(...) before EndSpriteBatch. If you change the End logic, preserve that ordering.
Renderer.GumBatchDrawMode.Deferred (optional Begin(mode:) param, issue #4573) accumulates Draw() calls into a scratch list instead of submitting immediately. End stable-sorts it by Z (Layer.SortByZ, extracted out of Layer.SortRenderables) and runs it through SiblingOrdering.BuildDrawList/Submit once, so separate Draw() calls can batch together (e.g. under BatchKeyGroupedOrderer). Immediate (the default) is unchanged.
Neither mode ever puts a renderable on _layers[0] — that layer is only a render-state and clip-bounds source — so Immediate does no sorting at all and submits in call order. That is why the deferred SortByZ keeps its default secondarySortOnY: false: passing _layers[0].SecondarySortOnY would reorder equal-Z draws that Immediate leaves in call order, creating the mode divergence rather than removing it. GumBatchDeferredDrawModeTests.SecondarySortOnYOnLayerZero_DoesNotReorderEqualZDraws_InEitherMode pins this.
PreRender Walk: Layered Path Has Two Phases, GumBatch Path Has One
The layered path runs a recursive PreRender pass on layer.Renderables before BeginSpriteBatch. That pass does two jobs:
- Calls
renderable.PreRender()on every visible renderable, depth-first. This is the hookRenderableShapeBase.PreRenderuses to invokeOnPreRender, which is wired byAposShapeRuntime.SetContainedShapeto callAposShapeRuntime.PreRender. That's where runtime-only properties (notablyStrokeWidthwith its unit handling) get pushed onto the contained renderable. Without this walk, the renderable keeps its own default values (e.g.RenderableShapeBase._strokeWidth = 2) regardless of what the runtime was assigned. - For any renderable with
IsRenderTarget == true, callsRenderToRenderTarget— which sets a render target on the GraphicsDevice and runs its own SpriteBatch cycle inside. Invisible render targets (Visible == false) skip this bake unless a visibleIRenderTargetTextureReferenceron any layer references them viaRenderTargetTextureSource(#1643) — the reference set is collected once per host frame across all layers before the bake pass runs.
Phase 2 is why the full PreRender walk must run before BeginSpriteBatch — once the outer SpriteBatch is begun, you can't safely change the render target or start a nested cycle.
The GumBatch path (Renderer.Begin/Draw/End) calls BeginSpriteBatch immediately in Begin, so it can't host phase 2. Renderer.Draw(IRenderableIpso) does run a phase-1-only walk via InvokePreRenderRecursively before forwarding to the inner draw, so AposShapeRuntime.PreRender and similar hooks fire correctly. Render targets nested inside a GumBatch.Draw tree are not supported on this path — phase 2 is intentionally skipped to avoid clobbering the outer SpriteBatch.
Practical consequence: any new "runtime resolves a property in PreRender and pushes it to the renderable" pattern (the AposShapeRuntime.StrokeWidth shape) works on both entry paths, but only the layered path renders nested render targets.
Cross-Layer RenderTargetTextureSource and Per-Layer Draw (issues #3416 / #3417)
Sprite.RenderTargetTextureSource lets a sprite sample a cached offscreen target owned by a render-target container on another layer. The multi-layer Draw(SystemManagers, List<Layer>) path already ran a two-pass pre-render (bake all layers, then bind referencer textures on all layers) before compositing. Per-layer Draw(SystemManagers, Layer) — the FRB / GumIdb default — did not, so cross-layer references went stale.
Per-layer draw contract (post-#3417):
- Once per host frame (first
Draw(Layer)or explicitPreRenderLayers):TryPreRenderAllLayersForHostFrame→PreRenderLayersCore(_layers)— bake every layer's render targets, then bind every layer'sIRenderTargetTextureReferencertextures. Token resets whenSystemManagers.Activitytime advances (NotifyHostFrameAdvanced) orEndFrame()runs. - Every
Draw(Layer)call (even when step 1 already ran):PreRender(currentLayer.Renderables)+PreRenderWithSourceRenderTargets(currentLayer.Renderables)— same per-layer hooks the legacy path always ran. Do not skip step 2 when the all-layer bake already ran; layout hooks and texture rebind still need to run for the layer being composited. - Compositing:
RenderLayer(..., prerender: false).
Optional explicit API: SystemManagers.PreRenderLayers(layers) / Renderer.PreRenderLayers(layers) — bake+bind without drawing (for hosts that want to separate pre-render from compositing).
ResolveRenderTargetCacheOwner maps a GraphicalUiElement RenderTargetTextureSource to its RenderableComponent for cache lookup — the cache key is always the contained IRenderableIpso, not the GUE wrapper.
Integration tests: CrossLayerRenderTargetTextureSourceTests (per-layer draw, consumer-first and source-first order) + RenderTargetSweepTests (#3416 sweep). Tests share SystemManagers.Default; advance Activity time uniquely each frame (AdvanceHostFrame) so once-per-frame tokens reset.
Render-Target Post-Process Effects (issue #816)
A render-target container can carry a post-process shader applied when its cached texture is blitted back to the screen — not while children render into the target. Storage is RenderableBase.RenderTargetEffect, typed object? so the shared (non-XNA) rendering layer stays backend-agnostic; the xnalike Renderer casts it to a MonoGame Effect. The user-facing setter is the strongly-typed ContainerRuntime.RenderTargetEffect (#if XNALIKE).
Both back-draw sites — SubmitDrawRenderable (the live flat-DrawCommand pass) and the legacy recursive Draw (GumBatch immediate path) — funnel through Renderer.DrawRenderTargetToScreen, the single place the effect is bound. When an effect is present the blit becomes its own SpriteBatch cycle: _batchOrchestrator.FlushAndReset the open batch, BeginSpriteBatch(..., effectOverride: effect), draw the target, then BeginSpriteBatch again with no override to restore the normal effect for following renderables. This mirrors the mid-walk clip-change flush.
SpriteRenderer.BeginSpriteBatch's effectOverride replaces Gum's BasicEffect/CustomEffect but keeps the same transformMatrix Gum passes for every sprite/shape. So the user effect receives its vertex transform via the SpriteBatch MatrixTransform convention (the standard MonoGame 2D shader template) exactly as the Apos.Shapes path consumes that matrix — the blit stays aligned with the rest of the layer with no new matrix math. Contract: user effects must follow that SpriteBatch convention (pixel-shader post-process over a MatrixTransform-driven vertex shader); an effect that hard-codes its own projection won't position correctly. Gum core never compiles or loads the shader — the consumer supplies a constructed Effect (content pipeline, new Effect(gd, bytes), or a runtime .fx compiler). Second half of the contract: the blit binds the effect and draws once, in a single pass. Per-container values set with ContainerRuntime.SetShaderParameter are written to the effect by Renderer.ApplyShaderParameters immediately before BeginSpriteBatch, so containers sharing one cached Effect each get their own value. Values set directly on the Effect by user code are not per container. A parameter that was never set keeps its shader default (often zero), so a blur whose Offset stays (0,0) renders unblurred and looks like "the shader did nothing." Gum has no way to chain passes on a render-target effect, so a separable two-pass blur cannot work through this path.
The top-level-vs-nested renderable asymmetry (a real gotcha — bit #816). The object the main-pass walk hands to SubmitDrawRenderable/DrawRenderTargetToScreen differs by depth: for a top-level render-target container it is the contained renderable (the InvisibleRenderable, a RenderableBase), because AddToManagers adds mContainedObjectAsIpso to the layer; for a nested one it is the GraphicalUiElement wrapper itself, because AddChild parents the GUE into the parent's child list. So any property the back-draw reads off renderable must be reachable on both forms. IsRenderTarget is fine because it's on the IRenderableIpso interface; RenderTargetEffect lives on the dedicated IRenderTargetRenderable interface (declared in IRenderableIpso.cs) — NOT on IRenderableIpso itself (that would force every backend's renderable to implement it), but a small mix-in implemented by the renderables that can be render-target containers. The renderer reads (renderable as IRenderTargetRenderable)?.RenderTargetEffect ?? (GUE.RenderableComponent as IRenderTargetRenderable)?.RenderTargetEffect. Reading only the contained-renderable form silently no-ops for every nested render target — and nested is the common case (any container built inside a Forms screen). Unit-test render-target features at depth, not just top-level.
Why a shared interface, not just RenderableBase (#3210). The original #816 read cast to RenderableBase, which works at runtime (containers are InvisibleRenderable : RenderableBase) but silently fails in the Gum editor: the editor backs a Container with a LineRectangle (the outline visual), which is a SpriteBatchRenderableBase, NOT a RenderableBase — so it had nowhere to hold the effect and the cast returned null, leaving the WYSIWYG preview unshaded. IRenderTargetRenderable is implemented by both RenderableBase (runtime container) and LineRectangle (editor container), so the same back-draw and the same AssignSourceShaderFileOnContainer(IRenderTargetRenderable, …) serve both. The dispatch is type-specific: the runtime path sets it in TrySetPropertyOnContainer, the editor path in TrySetPropertyOnLineRectangle — a Container in the tool is a LineRectangle, so a render-target property handled only on the InvisibleRenderable branch never fires in the editor. Lesson: render-target features must be carried on something both the runtime's InvisibleRenderable and the editor's LineRectangle share — verify them in the running tool, not just runtime unit tests.
Resolving the effect from a .fx file reference (#3206). ContainerRuntime.SourceShaderFile (#if XNALIKE, write-only) is the file-reference entry point, mirroring how a Sprite references a texture. It routes through the string path (base.SetProperty("SourceShaderFile", …)); CustomSetPropertyOnRenderable.AssignSourceShaderFileOnContainer resolves the path to a platform Effect and drops it into the same RenderTargetEffect slot. Gum core links nothing shader-specific — the actual .fx → Effect compile/load is a pluggable static CustomSetPropertyOnRenderable.RenderTargetEffectResolver (Func<string, object?>) that the consumer (or a future Gum.Shapes-style library) registers, typically capturing its own GraphicsDevice in the closure. No resolver registered (or one that returns null): the file fails like a missing file whatever its extension (honors MissingFileBehavior; the message names the ShadowDusk package for the compiled runtime, via ShaderResolverRequirement); ConsumeSilently is the opt-out. Gum must not encode which extensions need ShadowDusk, and Skia treats an explicit null resolver the same way (its default resolver handles .sksl). The Gum.<Runtime>.ShadowDusk packages register the resolver via UseShadowDusk(). The resolved effect is cached in LoaderManager by normalized path (one compile per .fx, even across containers); a registered-but-failed resolve honors GraphicalUiElement.MissingFileBehavior, mirroring Sprite source-file handling. The dispatch + resolver live in Gum/Wireframe/CustomSetPropertyOnRenderable.cs (linked into MonoGame/KNI/FNA and raylib); SkiaGum has its own parallel AssignSourceShaderFileOnContainer and RenderTargetEffectResolver (default SkSlRuntimeEffectLoader), so a change to one needs the same change in the other.
Render-Target Bake and Composite Allocate Nothing Per Frame (#7619)
A static scene of render-target containers allocates zero bytes per frame (RenderTargetAllocationTests), although every container still re-bakes and re-composites each frame. Two things used to allocate: ToXNA(Gum.BlendState) built a new XNA BlendState on every SpriteBatch.Begin for any non-preset state such as _bakeToRenderTargetBlendState (now cached per source instance in XNAExtensions, rebuilt when the source is edited or the cached state's device was disposed), and GraphicsDevice.GetRenderTargets() returns a new array per call (Renderer.GetBoundRenderTarget fills a reused one under #if MONOGAME). Any new per-Begin or per-bake call in this path needs the same check: a Gum-to-XNA conversion that constructs, or a MonoGame getter that returns an array.
Manual Refresh Mode: Cached Render-Target Containers
RenderTargetRefreshMode (IRenderTargetRenderable, strongly typed on ContainerRuntime) defaults to EveryFrame, the path above. Manual bakes once and then draws the result as a plain sprite; RefreshRenderTarget() bumps RenderTargetRefreshVersion, and the next draw re-bakes. Nothing else is tracked: a changed child, effect or shader parameter shows only after a refresh.
- The cache holds the post-effect image. The children bake into a pooled scratch target (
ScratchRenderTargetPool, shared by exact size, swept like the caches), thenBakeSubtreeInto(..., effectSource)runs the container'sRenderTargetEffectand shader parameters once into the final target. With no effect the children bake straight into it. Later draws bind no effect. GroupAlphais applied at draw time, so changing it needs no refresh. - Texture plus rectangle. The result is a
CachedRenderTargetImage(texture, source rectangle, plus the zoom and refresh version it was baked at). The rectangle is always the whole target today; draw code already passes it, so an atlas or user region needs no new draw path. - Whole bounds, not clamped to the camera (
ManualBakePlansize = absolute bounds times zoom), so scrolling or moving never makes the image stale. A side overMaxManualRenderTargetSize(8192) keeps the container on the every-frame path. - Valid means same pixel size, camera zoom and refresh version. Moving does not invalidate; the draw positions the image at the container's current origin.
- Eviction is by drawing, not baking. The bake never marks the owner used (
GetFor(markUsed: false));DrawRenderTargetContainerandTryGetBakedRenderTargetFor(aSprite.RenderTargetTextureSourceread) do, viaMarkUsed. Culled, invisible, off-camera (IsOnCamera) or removed means unmarked, so the next frame-boundary sweep releases it and the next draw re-bakes. The sweep runs at the start of a frame, so release shows two frames after the last draw.OnReleasedkeeps the image table in step with every release path. - Who bakes when. A manual container the layer draws is baked in
RenderLayerafterBuildDrawListand beforeBeginSpriteBatch(BakeManualContainersInDrawList), because only the draw list says it is really drawn (a clipped-away scroll item must not bake). One inside another render target's bake, or read by aRenderTargetTextureSource, is baked inPreRender, post-order. A valid cache skips its whole subtree'sPreRender. - Sprite sources and immediate paths. A
Sprite.RenderTargetTextureSourcepointing at a manual container shows the cached post-effect image (an every-frame source gives the unshaded target); pinned by a test. The GumBatch immediate and deferred paths never bake a manual container, so it draws nothing there unless a layered draw cached it; render targets nested inGumBatch.Draware unsupported there anyway. - Inside another render target's bake. A manual container whose enclosing clipping container does not overlap it is neither baked nor drawn (
IsClippedAwayInsideAncestorBakemirrors the orderer's cull), so it holds no target and the sweep releases any it had. - Size limit. The cap is the smaller of 8192 and the profile's guaranteed texture size (Reach 2048, HiDef 4096,
GetMaxManualRenderTargetSize); a bigger container keeps the every-frame path. A cached image whose texture reportsIsContentLostcounts as invalid and re-bakes (the GL backends never report it, so no test can force it). - Leaving manual mode drops the cached image in
RenderTargetService.GetRenderTargetFor;Renderer.Uninitializedisposes every target. - Tests:
Tests/MonoGameGum.IntegrationTests/.../Rendering/ManualRenderTarget/(ManualRenderTargetSceneis the harness;Renderer.RenderTargetBakeCountcounts bakes).
Render-Target Bake: Premultiplied vs Straight Alpha (#1696)
Gum runs in two alpha worlds and blend/render-target code must serve both. The tool and standalone MonoGameGum default to straight alpha (Renderer.NormalBlendState = NonPremultiplied). FRB runs premultiplied: GumIdb.StaticInitialize sets NormalBlendState = AlphaBlend and IsUsingPremultipliedAlpha = true, and the incoming color is premultiplied to match on the CPU in Sprite.Render's NormalBlendState == AlphaBlend branch. GumIdb does not set UseCustomEffectRendering, so that branch runs under FRB too, and any tint passed to Sprite.Render must be straight, not already premultiplied.
RenderToRenderTarget bakes children over a transparent clear; the bake substitutes _bakeToRenderTargetBlendState (color = SourceAlpha, "premultiply on bake") for unconfigured children so straight-alpha color composites correctly. That substitution double-darkens already-premultiplied content (a 50%-alpha child bakes to 25% color → composites to gray), so Renderer.AdjustBlendStateForRenderTargetBake skips it when NormalBlendState == AlphaBlend — the ambient AlphaBlend already accumulates premultiplied children correctly over the transparent clear. Two more premultiplied-pipeline rules sit in the same area. The composite-back blit in DrawRenderTargetToScreen must use AlphaBlend: a container's renderable defaults to NonPremultiplied, which on FRB is not NormalBlendState, so IsUnconfiguredRenderTargetCompositeBlend treats it as unconfigured. Its tint comes from CreateRenderTargetCompositeTint, which hands Sprite.Render a straight tint on that pipeline. In the bake itself, AdjustBlendStateForRenderTargetBake swaps ReplaceAlphaPremultiplied and MinAlphaPremultiplied for the *OnPremultipliedTarget states, because the premultiplied variants replace or Min the color with the mask's own.
Drawing a whole frame to a transparent target (#7992). Export as Image (ScreenshotService) and gumcli screenshot (MonoGameScreenshotService) set Renderer.IsDrawingToTransparentTarget, so top-level draws get the same bake blends (UsesRenderTargetBakeBlendStates), then save with TexturePremultiply.SaveAsUnpremultipliedPng. Without it the straight pipeline's NonPremultiplied writes alpha as srcA*srcA. Pinned by ExportAsImageAlphaTests (Avalonia, Linux Xvfb CI) and MonoGameScreenshotAlphaTests.
Testing gotcha: MonoGameGum.IntegrationTests does not run GumIdb's premultiplied setup, so a pixel test there won't match a real FRB scene. Pin premultiplied-pipeline blend decisions with a logic test (RenderTargetBakeBlendStateTests), and check the end-to-end pixels in Tests/FlatRedBall.GumRendering.Tests (see frb-pixel-harness). It runs by hand next to a FlatRedBall checkout and is not part of the compile-only FRB canary.
Clip and Cull Rectangles Inside a Turned Render-Target Bake
A turned IsRenderTarget container bakes its children upright, but a descendant's absolute position is where it sits turned in the world. Any scissor or cull rectangle computed inside the bake must go through GetAbsoluteBoundsInBake(bakedContainer, ...) (via GetScissorRectangleFor/GetCullTestBoundsFor with the bakedContainer argument, or ClipBoundsSource(camera, layer, container)), which turns the descendant's top-left back about the container. Renderer's _bakedContainer carries the container during the bake; raylib has _bakeContainer. A new place that builds a clip rect in the bake must pass it too.
Two Independent Batchers
- MonoGame
SpriteBatch— wrapped bySpriteBatchStack(push/pop of render-state parameters). Used by sprites, text, NineSlice, SolidRectangle. Anything inheritingSpriteBatchRenderableBasedeclaresBatchKey="SpriteBatch". - Apos.Shapes
ShapeBatch— owned byShapeRenderer.Self, started/ended byRenderableShapeBase.StartBatch/EndBatch. Anything inheriting that base declaresBatchKey="Apos.Shapes".
These are separate GPU command streams. Within a frame, paint order on screen is determined by the order each batch's End() is called — not the order draws were queued.
SB.Begin → SB.Draw(spriteA) → ShB.Begin → ShB.Draw(shapeX) → ShB.End → SB.End
^ ^
shapeX spriteA
flushed flushed
first second
(under) (on top)To get insertion-order paint order across the two batches, every batch transition must End the previous batch before queueing into the new one.
The BatchKey Transition Machinery
The transition logic lives in BatchOrchestrator.OnRenderable (RenderingLibrary/Graphics/BatchOrchestrator.cs), extracted from Renderer so it's unit-testable without a GPU (BatchOrchestratorTests). Renderer holds one instance as _batchOrchestrator; its CurrentBatchKey/LastBatchOwner persist across Begin/End cycles.
Three behaviors worth internalizing:
- Empty BatchKey is treated as "no transition required." A renderable with
BatchKey=""(containers, GUE wrappers) does NOT flush the current batch. This is intentional for plain wrappers but becomes a bug when something with a non-empty BatchKey claims a batch it doesn't actually start. SpriteBatchRenderableBase.StartBatchcallsspriteRenderer.Begin(false)followed byspriteRenderer.ForceSetRenderStatesToCurrent().EndBatchcallsspriteRenderer.End()— flushes SpriteBatch directly (does NOT pop the SpriteBatchStack). The pairing ofBegin(false)+ForceSetRenderStatesToCurrentis what re-applies the activeBeginParameters(scissor/raster/blend/sampler/transform) to the underlying SpriteBatch — see "SpriteBatchStack: Begin(false) must re-apply currentParameters" below for why both calls are required.RenderableShapeBase.StartBatch/EndBatchcallShapeBatch.Begin/End— separate GPU state stream, but the runtime now plumbs the active scissor rect through so shapes honorClipsChildren. See "Shape Clipping: ShapeBatch Honors Scissor via rasterizerState" below.
Draw Order Is a Separate, Pluggable Layer: IRenderableOrderer
Renderer.SiblingOrdering (Renderer.cs) decides what order renderables reach Submit — and therefore SpriteBatch.Draw() — before BatchOrchestrator ever runs. Default HierarchicalOrderer is plain DFS; BatchKeyGroupedOrderer (BatchKeyGroupedOrderer.cs, toggle: RenderDiagnosticsService.SortByBatchKey) reorders same-BatchKey draws into contiguous runs, sub-grouped by the finer IRenderable.BatchSortKey (e.g. a Texture2D reference — see SpriteBatchRenderableBase.BatchSortKey), without crossing overlapping bounds.
Overlap uses drawn bounds, not the layout box. Each renderable reports where it draws through IDrawnBoundsRenderable.TryGetLocalDrawnBounds (text lines past Height, shadows, strokes); the orderer applies rotation. A renderable that returns false or does not implement it overlaps every draw, so a new renderable that draws outside its box (or the line geometry, Svg, a per-piece-texture NineSlice) stays correct but stops batching until it reports real bounds.
Landmine: BatchOrchestrator only flushes on a BatchKey change, so its granularity caps what it can detect — a coarse key (e.g. one shared across many texture sources) means real per-texture draw-call cost hides inside MonoGame's own SpriteBatch batching over whatever order SiblingOrdering produced. Per-texture grouping goes through the separate BatchSortKey member instead, read only by BatchKeyGroupedOrderer — BatchOrchestrator never sees it, so it carries no flush cost under the default orderer.
BatchKeyGroupedOrderer.Instance exposes MergeBlockedByOverlapCount/NoCandidateInWindowBreakCount (issue #4575), reset every BuildDrawList call — read them right after a draw to tell an overlap-forced batch break from genuine content alternation, instead of guessing from GetDrawStateSummary alone.
SpriteBatchStack: Push / Pop / Replace
SpriteBatchStack wraps a single SpriteBatch instance with a stack of BeginParameters:
PushRenderStates(...)≈BeginType.Push: pushes current params onto stack, thenReplaceRenderStates.ReplaceRenderStates(...)≈BeginType.Begin: ends the SpriteBatch if Began, sets new currentParameters, callsSpriteBatch.Begin. Does not change stack depth.PopRenderStates(): pops top of stack. If popped value has params,ReplaceRenderStatesto it; if null, setscurrentParameters=nulland ends SpriteBatch.Begin(createNewParameters=false): ends SpriteBatch if Began, then begins it again, re-applying the activecurrentParametersto both the GraphicsDevice (ScissorRectangle, RasterizerState) and the underlyingSpriteBatch.Begincall (full 7-arg overload). Used bySpriteBatchRenderableBase.StartBatchto re-flush sprites mid-walk while keeping the same params. See "SpriteBatchStack: Begin(false) must re-apply currentParameters" below — this contract was silently violated before the fix in #2706 (the parameterlessSpriteBatch.Begin()was used, which resets to MonoGame defaults includingRasterizerState.CullCounterClockwisewithScissorTestEnable=false, silently dropping clip state).End(): just ends SpriteBatch (flushes pending sprites). Does not touch stack.
Invariant: every BeginType.Push must be balanced by exactly one EndSpriteBatch (which calls Pop). BeginType.Begin does not enter the stack and doesn't need a balancing pop.
Mid-walk End() from SpriteBatchRenderableBase.EndBatch does NOT pop the stack — it just flushes. Subsequent spriteRenderer.Begin(false) resumes with the same currentParameters. This is how sprite/text renderables can interleave with shape batches without imbalancing the stack.
Cross-Cycle State (Critical)
Renderer._batchOrchestrator's CurrentBatchKey and LastBatchOwner persist across Begin/End cycles. So when FRB2 draws Card N then Card N+1 in two separate GumBatch.Begin/End cycles:
- The outgoing state from Card N (e.g.
CurrentBatchKey="Apos.Shapes",LastBatchOwner=Back) is what Card N+1 sees on entry. - The Apos.Shapes
ShapeBatchmay still be Begun with queued shapes at the start of Card N+1's cycle —Renderer.Enddoesn't end it.
This cross-cycle leakage is the single biggest source of "draw order looks weird across N renderables" bugs. Any fix to flushing must end the custom batch at Renderer.End so cycle boundaries are clean.
RenderStateChangeStatistics and SpriteRenderer.LastFrameDrawStates follow the same rule. Renderer.Begin resets both once per host frame, gated by _perfStatsResetForHostFrame (cleared in NotifyHostFrameAdvanced/EndFrame, same as _allLayersPreRenderedForHostFrame). Renderer.End then adds that cycle's GraphicsDevice.Metrics.DrawCount delta. Multiple Begin/End cycles in one host frame accumulate into one total instead of overwriting each other (FRB2's per-camera-plus-overlay shape). A host that never advances SystemManagers.Activity/GumUI.Update never resets past the first frame (#4571).
SpriteBatchStack: Begin(false) must re-apply currentParameters
Begin(createNewParameters=false) runs whenever the BatchOrchestrator transitions back to SpriteBatch from a custom batch (Apos.Shapes, future custom batches). It's reached via SpriteBatchRenderableBase.StartBatch, which sequences:
spriteRenderer.Begin(createNewParameters: false);
spriteRenderer.ForceSetRenderStatesToCurrent(); // calls ReplaceRenderStates with currentParameters' valuesThe reason both calls are needed: SpriteRenderer.Begin(false) is a guarded passthrough that only invokes mSpriteBatch.Begin(false) if SpriteBatch is currently Ended. After ShapeBatch took over, SpriteBatch was indeed ended (by the previous SpriteBatchRenderableBase.EndBatch). So Begin(false) actually executes — and must re-apply currentParameters to both the GraphicsDevice and the underlying SpriteBatch.Begin(...) call. ForceSetRenderStatesToCurrent then immediately runs ReplaceRenderStates, which performs an End+Begin cycle with the same parameters.
The historical bug (latent pre-#2582, surfaced when the BatchOrchestrator made the path run on every batch transition): Begin(false) was calling parameterless SpriteBatch.Begin() instead of the 7-arg overload with currentParameters. That set MonoGame's default rasterizer (CullCounterClockwise, ScissorTestEnable=false), silently dropping scissor and clipping any subsequent sprites/text drawn under a ClipsChildren ancestor. The follow-up ReplaceRenderStates did re-apply the right state in theory, but the back-to-back Begin/End/Begin sequence ended up with the GPU in the wrong rasterizer state — visually, text labels bled outside their clip region.
Rule: any future change to SpriteBatchStack.Begin(bool) must keep Begin(false)'s behavior equivalent to "call SpriteBatch.Begin(p.SortMode, p.BlendState, p.SamplerState, p.DepthStencilState, p.RasterizerState, p.Effect, p.TransformMatrix) with p = currentParameters.Value" and explicitly assign GraphicsDevice.ScissorRectangle / GraphicsDevice.RasterizerState before the call. The empirical canary is "text labels inside a ScrollViewer or ListBox should clip to the container."
Shape Clipping: ShapeBatch Honors Scissor via rasterizerState
ShapeBatch.Begin (Apos.Shapes 0.6.8+) has this signature:
public void Begin(Matrix? view = null, Matrix? projection = null,
BlendState? blendState = null, SamplerState? samplerState = null,
DepthStencilState? depthStencilState = null, RasterizerState? rasterizerState = null)The rasterizerState parameter is how shapes opt into scissor testing. Setting GraphicsDevice.ScissorRectangle alone is not enough — Apos.Shapes' internal default rasterizer has ScissorTestEnable=false, which suppresses scissor regardless of the GraphicsDevice's rect. You must also pass a RasterizerState with ScissorTestEnable=true to ShapeBatch.Begin.
RenderableShapeBase.StartBatch reads the active SpriteBatch clip via:
SpriteRenderer.CurrentScissorRectangle—System.Drawing.Rectangle?, non-null when SpriteBatch'scurrentParameters.RasterizerState.ScissorTestEnableis true. MirrorsCurrentTransformMatrix(the same plumbing pattern for view-matrix sync between SpriteBatch and ShapeBatch).SpriteRenderer.ScissorTestRasterizerState— the sharedscissorTestEnabledrasterizer used by Sprite clipping. Same instance is passed toShapeBatch.Beginso both batches see identical scissor behavior.
When a clip is active, RenderableShapeBase.StartBatch assigns ShapeBatch.GraphicsDevice.ScissorRectangle = scissor.ToXNA() (belt-and-suspenders — the rect may already be set from the prior SpriteBatch.Begin, but the explicit assignment makes the contract clear) and passes ScissorTestRasterizerState to ShapeBatch.Begin. When no clip is active, both pass null and shapes render fullscreen.
Past wrong turn documented here so it doesn't get re-tried: an early diagnostic concluded "Apos.Shapes ignores externally-set scissor state" based on a probe that set GraphicsDevice.ScissorRectangle + GraphicsDevice.RasterizerState before/after sb.Begin() and saw no clipping. That was incomplete — the probe never tried sb.Begin(rasterizerState: scissorEnabled). Always check ShapeBatch.Begin's full overload before concluding a clipping-related limitation is upstream.
Mid-Walk Scissor Change Must Flush the Open Custom Batch
Renderer.AdjustRenderStates restarts SpriteBatch (BeginSpriteBatch(BeginType.Begin)) whenever blend / color / wrap / clip changes on a renderable. SpriteBatch state is reapplied in place, but a custom batch (Apos.Shapes ShapeBatch) opened earlier in the walk is not touched — it stays Begun with whatever scissor state it captured at its own sb.Begin call.
The hazard pattern: a shape sibling of a clip container is rendered first (e.g. a scrollbar thumb that lives outside ClipContainerInstance but in the same ScrollViewer). After the scrollbar, _currentBatchKey = "Apos.Shapes", ShapeBatch is Begun with no-scissor state. Then we descend into the clip container — AdjustRenderStates restarts SpriteBatch with the new scissor rect, but ShapeBatch is left alone. The first shape descendant inside the clip has BatchKey="Apos.Shapes" matching _currentBatchKey → OnRenderable is a no-op → no fresh StartBatch fires → the shape queues into the still-open stale-scissor ShapeBatch. The next non-shape renderable (e.g. a Text inside the same item) finally fires a transition, ShapeBatch.End flushes the queued shapes using the stale state, and the first shape bleeds past the clip. Item 2+ are fine because by then a transition has fired.
Rule: when a clip rect changes mid-walk (entry or exit), call _batchOrchestrator.FlushAndReset(managers) before spriteRenderer.BeginSpriteBatch(BeginType.Begin). The exit path in Renderer.Draw (the didClipChange branch) already does this; the entry path in AdjustRenderStates must mirror it. Empirical canary: an Apos-shape-backed item background as the first child inside a ScrollViewer's clip container should clip to the container when scrolled past the top edge.
This is clip-specific. Blend / color / wrap state changes don't propagate to ShapeBatch (each sb.Begin captures its own), so they don't need the flush. The orchestrator-level contract (BatchOrchestratorTests.ShapeAfterFlush_FiresFreshStartBatch_EvenWhenKeyMatchesPreFlushKey) documents the post-flush behavior the fix relies on.
Test gap: the orchestrator unit tests cover the "given flush, then next renderable fires Start" contract, but the integration — that Renderer.AdjustRenderStates actually invokes FlushAndReset on a clip change — isn't automated. The empirical canary in checklist item #9 is what catches regressions; a Renderer-level test would need GPU scaffolding similar to MatrixRoutingTests (MinimalGame.RunOneFrame) plus a way to observe orchestrator events through a real draw walk. Worth adding if this code path regresses again.
ContainerRuntime's BatchKey Override (Historical Pitfall)
MonoGameGum/GueDeriving/ContainerRuntime.cs historically had:
public override string BatchKey => Children?.LastOrDefault()?.BatchKey ?? string.Empty;This is a broken peephole optimization. It tries to pre-claim the batch the last child will need, so the transition fires once at the container instead of repeatedly inside. But the Container's StartBatch is a no-op (InvisibleRenderable.StartBatch does nothing), so the claim is a lie:
- Container reports
BatchKey="Apos.Shapes"but doesn't actually start ShapeBatch. - First child (e.g. a shape Background) matches the claimed key → transition skipped.
- Background's
Renderqueues into a stale or absent ShapeBatch.
Rule: a renderable's BatchKey must match what its StartBatch actually begins. If StartBatch is a no-op, BatchKey must be empty.
How Children Are Walked
Renderer.Draw(renderable) recurses via IRenderableIpso.Children, which GraphicalUiElement implements as:
ObservableCollection<IRenderableIpso> IRenderableIpso.Children
=> mContainedObjectAsIpso?.Children ?? EmptyIpsoChildren;So the rendered children list is the contained renderable's children — not the public GUE.Children wrapper. The two lists are populated together (when a child GUE is parented, it's added to mContainedObjectAsIpso.Children), but if you instrument or audit one and not the other, you'll get misleading results. Always verify against ((IRenderableIpso)visual).Children.
renderable.BatchKey invocation goes through GraphicalUiElement.BatchKey:
public virtual string BatchKey => mContainedObjectAsIpso?.BatchKey ?? string.Empty;So a GUE delegates to its contained renderable's BatchKey. Concrete BatchKey values:
| Renderable | BatchKey |
InvisibleRenderable, RenderableBase (default) | "" |
SpriteBatchRenderableBase (Sprite, Text, NineSlice, SolidRectangle, ColoredRectangle…) | "SpriteBatch" |
RenderableShapeBase (RoundedRectangle, Circle, Line, Arc — Apos.Shapes) | "Apos.Shapes" |
| Skia equivalents | "" (Skia doesn't use this batching machinery) |
Matrix Routing: SpriteBatch vs ShapeBatch Must Agree
Sprites and shapes go through different transform paths even when they're queued in the same Renderer.Draw walk. Lining them up on screen requires the effective vertex transform to match. There are three matrix sources to keep in mind:
SpriteBatch.Begin(transformMatrix:)— set bySpriteBatchStack.ReplaceRenderStates/PushRenderStatesto the composed view (see "Compose, don't replace" below). When a custom Effect is bound to SpriteBatch (which Gum always does inUsingEffectmode —BasicEffectforUseBasicEffectRendering=true, the custom effect manager otherwise), MonoGame stores this on the unused default_spriteEffectand ignores it for vertex transformation. Its only practical role in Gum is being read back viaSpriteRenderer.CurrentTransformMatrix(=mSpriteBatch.CurrentParameters?.TransformMatrix) soRenderableShapeBase.StartBatchcan pass it as ShapeBatch'sview.basicEffect.World/View/Projection(BasicEffect path) and the matchingeffectManager.ParameterViewProj(custom-effect path) — these are what actually transforms sprite vertices. Both branches now use the same composed view; see "Compose, don't replace" below for the formula.World=Identity,Projection = CreateOrthographic(W, -H, -1, 1)(centered ortho), with an optional* CenterTranslation(-W/2,-H/2)folded intoViewfor top-left /IsInScreenSpacecameras.ShapeBatch.Begin(view:)— Apos.Shapes' own view matrix, with its own default projectionCreateOrthographicOffCenter(0, W, H, 0, 0, 1)(top-left ortho).RenderableShapeBase.StartBatchreadsSpriteRenderer.CurrentTransformMatrixand passes it here so shape and sprite see the same view.
Equivalence: View(=Forced) * CenterTranslation * Ortho(W,-H) ≡ View(=Forced) * OrthoOffCenter(0,W,H,0). So passing ForcedMatrix as view to ShapeBatch produces the same effective transform as setting it on basicEffect.View (with center translate) — provided neither is also applied a second time.
Compose, don't replace. ForcedMatrix is a world transform that the consumer wants applied on top of the camera view — not a replacement for it. The current routing:
basicEffect.World = IdentitybasicEffect.View = ForcedMatrix.HasValue ? ForcedMatrix.Value * GetZoomAndMatrix(...) : GetZoomAndMatrix(...)(then* CenterTranslationifshouldOffset)- The custom-effect path (
Renderer.UseCustomEffectRendering=true) follows the same compose rule on its ownviewlocal before feedingview * projectionintoeffectManager.ParameterViewProj. Both branches must stay in sync — if you change one, change the other. SpriteBatch.transformMatrix = ForcedMatrix.HasValue ? ForcedMatrix.Value * spriteBatchTransformMatrix : spriteBatchTransformMatrix— read back by shapes viaSpriteRenderer.CurrentTransformMatrix, soShapeBatch.Begin(view:)sees the same composition.spriteBatchTransformMatrixisGetZoomAndMatrix(layer, camera)regardless ofUsingEffect(a pre-#2590 layer-zoom-only special case was the cause of one regression).
This keeps camera position/zoom contributing for GumBatch consumers (otherwise they render with no camera at all), and keeps sprite/shape vertices aligned (both apply the same composed view exactly once).
The double-application trap: the routing breaks the moment the consumer's ForcedMatrix already includes something that's also baked into Camera.Zoom / GetZoomAndMatrix. Example: FRB2's GumRenderBatch historically did both Camera.Zoom = scale and Begin(Matrix.Scale(scale)) — the comment said "the cursor reads Camera.Zoom for hit-testing, but rendering needs the matrix." Under compose semantics that gives sprites and shapes a consistent scale² (worse than the pre-fix s vs s² drift, but at least aligned). The clean answer is on the consumer side: set Camera.Zoom for hit-testing OR pass ForcedMatrix, not both. If hit-testing must keep reading Camera.Zoom, pass ForcedMatrix = null (or Identity) and let GetZoomAndMatrix do all the work.
Past wrong turns documented here so they don't get re-tried:
World = ForcedMatrix; View = GetZoomAndMatrix(pre-#2589): aligned for compose-style consumers but unaligned with shapes — shapes only sawForcedMatrix(orspriteBatchTransformMatrix), so sprite=F·Gvs shape=Fdrifted at non-1 scale.World = Identity; View = ForcedMatrix ?? GetZoomAndMatrix(#2589, replace semantics): aligned sprites with shapes BUT silently dropped camera position/zoom wheneverForcedMatrixwas set, breaking everyGumBatchconsumer that didn't bake camera into its own matrix. Reverted to compose in #2590.spriteBatchTransformMatrix = GetZoomMatrixFromLayerCameraSettings()underUsingEffect(pre-#2590): this matrix is ignored by MonoGame for sprite vertex transformation when a custom Effect is bound, so historically it was set to a weak layer-zoom-only matrix. But it's read back viaSpriteRenderer.CurrentTransformMatrixand fed intoShapeBatch.Begin(view:)— so it must matchbasicEffect.Viewor shapes desync from sprites at any non-zeroCamera.Zoom/position. Unified toGetZoomAndMatrix(layer, camera)for both paths in #2590.
Regression test: Tests/MonoGameGum.IntegrationTests/MonoGameGum/Rendering/MatrixRoutingTests.cs asserts that SpriteRenderer.CurrentTransformMatrix (the shape-side view) equals the composed ForcedMatrix * GetZoomAndMatrix for every combination of Camera.Zoom ∈ {1, 2}, scroll, and ForcedMatrix ∈ {null, scale}. Each of the past wrong turns above fails at least one row in this test. Run it before merging any change to matrix routing.
When changing matrix routing, verify alignment with a two-rectangle test (one ColoredRectangleRuntime, one RoundedRectangleRuntime, identical Gum coords) at a non-identity scale. Drift between them is the canary for a double-application bug.
Diagnostic: One-Frame Render Trace
When debugging draw-order bugs, the lowest-cost approach is to add a static RenderTrace.IsEnabled toggle and emit Debug.WriteLine calls from Renderer.Draw, Renderer.Begin/End, the StartBatch/EndBatch hooks, and SpriteBatchStack.Begin/End/Push/Pop/Replace. Indent by recursion depth. Toggle on for one frame via a key press. The trace shows you the exact GPU paint order.
When reading a trace:
- A
Render -> RoundedRectangleline means a shape was queued into ShapeBatch (NOT drawn yet). - A
Render -> Sprite/Textline means a draw call was queued into SpriteBatch. - Actual GPU draw happens at
>> ShapeBatch.Endand>> spriteRenderer.End()lines. - Cross-reference these against the renderable order to see when each pixel actually hits the framebuffer.
Alpha-Only Blends on Shapes Need a Bounds Clip
Apos.Shapes draws a quad larger than the shape and does not discard zero-coverage fragments, so ReplaceAlpha and MinAlpha write alpha 0 in a margin outside the shape's bounds. ShapeRenderer.BeginAlphaBoundsMask/EndAlphaBoundsMask clip every draw of the shape to its bounds with a stencil bit (a pixel counts when its center is inside) and then cover the rest of the bounds. A new shape renderable must call both, passing its own bounds. ShapeEdgePixelTests audits every shape type for pixels changed outside the bounds.
Alpha-Only Blends on Text Mask the Whole Text Bounds
Text with ReplaceAlpha or MinAlpha (character-by-character mode, while baking a render target) masks its measured block plus 2px (plus the drop shadow offset), like Skia, not just the glyph cells. A bounds quad drawn before the glyphs would wipe the color they read, so SpriteRenderer.BeginAlphaBoundsMask/EndAlphaBoundsMask use the same stencil scheme as shapes: mark the bounds, draw the glyphs inside them, then cover the unmarked part with an alpha-0 quad. Text implements IStencilRenderable so the bake target gets a stencil buffer. Glyph quads still overwrite neighbors they overlap (a t crossbar under the next letter), which TextAlphaBoundsMaskTests avoids by using non-overlapping glyphs.
Known Pitfalls Checklist
When changing batch logic:
- Does the new
BatchKeymatch whatStartBatchactually begins? IfStartBatchis a no-op,BatchKeymust be"". - Does
Renderer.EndflushlastBatchOwner? If not, custom-batch draws leak across cycles. - Does the transition logic flush in BOTH directions (custom→sprite and sprite→custom)? Empty BatchKey on a renderable with no real batch shouldn't trigger machinery, but transitions to/from non-empty keys must always flush the outgoing batch.
- Does mid-walk re-begin of SpriteBatch use
Begin(false)(preserves params, no stack change) orBeginType.Push(changes stack)? Mismatching causes stack underflow at outer EndSpriteBatch. - Are you assuming
_batchOrchestrator.CurrentBatchKeyis""at the start of a Renderer.Begin cycle? It's not — it persists from the previous cycle. CallFlushAndResetif you need a clean state. - If you touch
basicEffect.World/VieworShapeBatch.Begin(view:), doesForcedMatrixend up applied exactly once to sprite vertices and once to shape vertices? Remember thatSpriteBatch's owntransformMatrixis ignored when a custom Effect is bound — onlybasicEffect's WorldViewProjection moves sprite vertices. - If you touch
SpriteBatchStack.Begin(bool), doesBegin(false)still callSpriteBatch.Beginwith all sevencurrentParametersfields (sortMode, blendState, samplerState, depthStencilState, rasterizerState, effect, transformMatrix) AND assignGraphicsDevice.ScissorRectangle+GraphicsDevice.RasterizerStatefirst? Empirical canary: text labels inside aScrollViewerorListBoxclip to the container. - If you touch
RenderableShapeBase.StartBatchorShapeBatch.Beginplumbing, does the active scissor state still flow to the shape batch? Empirical canary: rounded shape bodies inside aScrollViewer/ListBoxclip to the container. SettingGraphicsDevice.ScissorRectangleis not sufficient —ShapeBatch.Beginmust also receive arasterizerStatewithScissorTestEnable=true. - If you touch
Renderer.AdjustRenderStatesor the clip-change paths inRenderer.Draw, does a clip change (entry OR exit) flush the orchestrator (_batchOrchestrator.FlushAndReset) BEFOREBeginSpriteBatch? Empirical canary: the first item's shape background inside aScrollViewerclips when scrolled past the top edge (not just the second item and beyond). - Investigating draw-call/batching cost? Check
Renderer.SiblingOrdering, not justBatchOrchestrator— they're separate layers (see "Draw Order Is a Separate, Pluggable Layer" above). - Reset immediate-mode perf stats once per host frame, not on every
Begin. Per-Beginreset wipes out an earlier camera pass's stats instead of accumulating them within the frame. - Touching the
Deferredflush? It owns its own scratch buffers (_deferredImmediateModeRoots/_deferredImmediateModeCommands), not_scratchCommands/_bakeCommands— those are already claimed byRenderLayer/the render-target bake.
Stroke Geometry: Arc Matches Circle
DrawCircle draws a stroke exactly as wide as asked (inset by GetAntiAliasWorldOffset); DrawRing/DrawArc draw it wider by that offset on each side. Arc.RenderInternal takes the offset off the half thickness (RenderableShapeBase.GetRingHalfThickness) so a 360 degree arc covers the same pixels as a stroked Circle. A new stroked shape built on DrawRing/DrawArc must use the helper; ArcMatchesCircleTests pins the equality.
Arc in a Non-Square Box (#6256)
Arc fills its box on every runtime (Skia's is an ellipse); a stroked Circle stays a circle at the shorter side. Apos.Shapes has no elliptical arc, so Arc.Render draws the circle at the shorter side and stretches the longer axis with ShapeRenderer.PushView/PopView (the way Svg does), centered on the box and turned with its rotation. In a non-square box the stroke is exact on the short axis and thicker along the long axis (by long / short), and a stroke under 2 world units draws as 2 so it cannot fall between pixel rows. The push costs two batch flushes, paid only when Width differs from Height (the dropshadow pass pushes again). The alpha bounds mask uses the box, outside the push. Dashes, round caps and a radial gradient stretch with the arc; linear gradient points are mapped back through the inverse matrix because Apos reads them before the view. ArcFillsBoxTests pins all of it; the raylib arc is still a shorter-side circle (#6267).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

