Skip to content

allow text atlas to be exported and replaced to support batching#124

Draft
fisherevans wants to merge 2 commits into
gopxl:mainfrom
fisherevans:fisher/external-text-atlas-copy
Draft

allow text atlas to be exported and replaced to support batching#124
fisherevans wants to merge 2 commits into
gopxl:mainfrom
fisherevans:fisher/external-text-atlas-copy

Conversation

@fisherevans
Copy link
Copy Markdown

@fisherevans fisherevans commented Oct 8, 2025

Problem

text.NewAtlas renders a font into a private *pixel.PictureData. Drawing text with pixel.Batch requires all sprites and glyphs to share the same backing picture, but there was no way to read the atlas image or create an atlas that references a larger shared picture.

Changes

  • Atlas.PictureDataCopy — returns a deep copy of the atlas's pixel data so callers can blit it into a shared atlas image.
  • Atlas.CloneWithPictureData(pic, frame) — returns a new Atlas backed by pic, with all glyph coordinates translated so they remain correct at their new location (frame) within the shared image.
  • Atlas.pic narrowed from pixel.Picture to *pixel.PictureData (internal only - the exported Picture() method signature is unchanged).

Usage

// Build a font atlas and copy its pixels into a shared sprite sheet.
fontAtlas := text.NewAtlas(face, text.ASCII)
atlasCopy := fontAtlas.PictureDataCopy()

x, y := 100, 200
placement := image.Rect(x, y, x+int(atlasCopy.Bounds().W()), y+int(atlasCopy.Bounds().H()))
sharedImage := image.NewRGBA(image.Rect(0, 0, 1024, 1024))
draw.Draw(sharedImage, placement, atlasCopy.Image(), atlasCopy.Image().Bounds().Min, draw.Src)
// ... add more sprites to sharedImage

sharedPic := pixel.PictureDataFromImage(sharedImage)
frame := pixel.R(float64(x), float64(y), float64(placement.Max.X), float64(placement.Max.Y))
sharedAtlas := fontAtlas.CloneWithPictureData(sharedPic, frame)

// Now text and sprites can share a single pixel.Batch.
batch := pixel.NewBatch(nil, sharedPic)
textDrawer := text.New(pixel.ZV, sharedAtlas)
textDrawer.WriteString("hello")
textDrawer.Draw(batch, pixel.IM)
batch.Draw(win)

Test plan

  • go build ./... unchanged.
  • go test ./ext/text/... — new tests cover deep-copy semantics for PictureDataCopy, identity and translated placements for CloneWithPictureData, and the wrong-dimensions panic.

…ctureData

Fix panic message typo ("do no match" -> "do not match"), expand doc
comments to document the frame argument and batch-sharing use case, and
add table-driven tests covering deep-copy semantics for PictureDataCopy
and identity/translated/wrong-size cases for CloneWithPictureData.
@fisherevans fisherevans marked this pull request as draft April 21, 2026 17:20
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.

1 participant