Skip to content

fix: NineTileBox draws tiles when Sprite's src does not cover the whole image - #4233

Open
NagaChiang wants to merge 7 commits into
flame-engine:mainfrom
NagaChiang:fix/nine-tile-box-sprite-src
Open

NagaChiang wants to merge 7 commits into
flame-engine:mainfrom
NagaChiang:fix/nine-tile-box-sprite-src

Conversation

@NagaChiang

@NagaChiang NagaChiang commented Nov 14, 2026 •

Copy link
Copy Markdown

Description

Canvas.drawImageNine() always uses the whole image as its source, so sprites with an offset or smaller than the image rendered the wrong region.

Draw the nine tiles with Canvas.drawImageRect() from sprite.src when the sprite does not cover the full image, and keep Canvas.drawImageNine() for full-image sprites.

Sprite Spritesheet
Image nine-tile-sprite nine-tile-spritesheet
Destination size the same as three tiles nine_tile_box_default
Destination size larger than three tiles nine_tile_box_large
Destination size between two and three tiles nine_tile_box_medium
Destination size smaller than two tiles nine_tile_box_small

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.

Breaking Change?

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

Related Issues

Fixes #4232

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Small destinations cause the nine-tile fallback to draw corners outside the destination and invert center rectangles, requiring border scaling and a regression test.

1 open issue
What changed in this PR

This PR addresses #4232 by making NineTileBox respect a sprite’s source region when rendering from an atlas.

Changes:

  • Draw cropped sprites as nine separate tiles using Canvas.drawImageRect.
  • Preserve Canvas.drawImageNine for full-image sprites.
  • Add a golden test for an offset sprite smaller than its atlas.
File Description
packages/​flame/​test/​nine_tile_box_test.dart Adds a golden test for atlas-based nine-tile rendering.
packages/​flame/​lib/​src/​nine_tile_box.dart Shares rendering dispatch and adds source-region-aware tile drawing.

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Changing the source region on a same-sized NineTileBoxWidget can leave stale content visible because shouldRepaint always returns false; visual-input comparisons and a region-only update regression test are needed.

1 open issue
1 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

The atlas fallback can bleed neighboring pixels when filtering is enabled and produce anti-aliased seams at fractional positions, causing rendering differences from the native nine-patch path.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Medium severity Antialiased fallback draws can leave seams between tiles

packages/​flame/​lib/​src/​nine_tile_box.dart:185

With the default anti-aliased paint, independently drawn tiles can leave background-colored seams where shared edges fall between pixels. Flutter's paint flags apply anti-aliasing to drawImageRect but not drawImageNine (default-branch commit e736af5). Pass a paint copy with isAntiAlias = false to the fallback without mutating the caller's paint, and add a fractional-position golden test.

Medium severity Filtered atlas draws sample neighboring pixels at sprite edges

packages/​flame/​lib/​src/​nine_tile_box.dart:230

With overridePaint.filterQuality = FilterQuality.low and 2× magnification, these draws can blend neighboring atlas pixels into the box's outer edges. drawImageRect permits sampling outside src, whereas Impeller's native nine-patch renderer clamps each tile with kStrict (Flutter default-branch commit e736af5). Thus the atlas and full-image paths still render differently when filtering is enabled. Please preserve clamped sampling—for example, by caching an isolated sprite image and using drawImageNine—and add a filtered atlas golden with contrasting neighboring pixels.

1 resolved since last review

Review effort: Balanced

@NagaChiang

Copy link
Copy Markdown
Author

🔵 Needs a closer look

The atlas fallback can bleed neighboring pixels when filtering is enabled and produce anti-aliased seams at fractional positions, causing rendering differences from the native nine-patch path.

No open issues 🎉
2 previously missed issues

1 resolved since last review

* <img alt="Medium severity" width="62" height="18" src="https://camo.githubusercontent.com/7dc8929f1372d7be218d83fe61e6c3fb67ed8bc61cd50c1e8e4696827da90595/68747470733a2f2f6769746875622e6769746875626173736574732e636f6d2f7374617469632f696d616765732f69636f6e732f636f70696c6f742d636f64652d7265766965772f6d656469756d2d76322d6c696768742e706e67"> [Repaint when the nine-tile source region changes](https://github.com/flame-engine/flame/pull/4233#discussion_r4608540799)

Review effort: Balanced

When using overridePaint with Paint.filterQuality enabled (other than .none), the seams between tiles bleed or blend with neighboring tiles, which differs from the behavior of the original Canvas.drawImageNine().

  • When filterQuality = .low, Canvas.drawImageNine() vs. _drawTiles():

    image

I intend not to handle this case, as I currently don't have a good solution in mind.

A possible solution is to crop and cache the sprite from the source image, then use Canvas.drawImageNine() throughout. However, this places the burden on the consumer to call dispose() to free the resource. Also, it potentially breaks sprite batching, though I haven't verified this.

@spydon What do you think?

@spydon

spydon commented Nov 18, 2026

Copy link
Copy Markdown
Member

@NagaChiang since the most common use-case is to use the whole image, this PR becomes a regression to current behavior right? We can't have that. Also even if you would fix it by cutting up the image manually, the performance would be worse. So I'm leaning to keeping it the way it is now and just document the behaviorinstead.

@spydon

spydon commented Nov 18, 2026

Copy link
Copy Markdown
Member

@NagaChiang aah right, this is only for the fallback, then it is fine. But make sure that the behavior is documented.

@spydon spydon left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks for your contribution!

This branch has not been deployed

No deployments
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.

NineTileBox renders the wrong region when the Sprite's src doesn't cover the whole image

3 participants