Documentation
¶
Index ¶
- Constants
- Variables
- func EnsureMagentaImage() *ebiten.Image
- func MagentaRegion() types.TextureRegion
- func ResetGlobalManager()
- func SortStagedByArea(s []StagedEntry)
- type Atlas
- func (a *Atlas) Add(name string, img *ebiten.Image) (types.TextureRegion, error)
- func (a *Atlas) Free(name string) error
- func (a *Atlas) Has(name string) bool
- func (a *Atlas) Pack() error
- func (a *Atlas) Region(name string) types.TextureRegion
- func (a *Atlas) RegionCount() int
- func (a *Atlas) Remove(name string)deprecated
- func (a *Atlas) Replace(name string, img *ebiten.Image) error
- func (a *Atlas) Stage(name string, img *ebiten.Image) error
- func (a *Atlas) Update(name string, img *ebiten.Image) (types.TextureRegion, error)
- type Manager
- func (am *Manager) AllocPage() int
- func (am *Manager) Cleanup()
- func (am *Manager) NextPage() int
- func (am *Manager) Page(index int) *ebiten.Image
- func (am *Manager) PageCount() int
- func (am *Manager) RegisterPage(index int, img *ebiten.Image)
- func (am *Manager) Release(index int)
- func (am *Manager) Retain(index int)
- func (am *Manager) SetStatic(index int)
- type PackerConfig
- type RectPacker
- type ShelfPacker
- type StagedEntry
Constants ¶
const MagentaPlaceholderPage = 0xFFFF
MagentaPlaceholderPage is a sentinel page index used for magenta placeholders. It's high enough to never collide with real atlas pages.
const MaxPackerPageIdx = MagentaPlaceholderPage - 1
MaxPackerPageIdx is the highest page index the packer may allocate. Page 0xFFFF is reserved as the magenta placeholder sentinel.
Variables ¶
var Debug bool
Debug enables debug logging (e.g. missing region warnings). Set by the root package.
Functions ¶
func EnsureMagentaImage ¶
EnsureMagentaImage returns the 1×1 magenta placeholder image, creating it if needed.
func MagentaRegion ¶
func MagentaRegion() types.TextureRegion
MagentaRegion returns a 1×1 placeholder region on the sentinel page.
func ResetGlobalManager ¶
func ResetGlobalManager()
ResetGlobalManager resets the global singleton for test isolation.
func SortStagedByArea ¶
func SortStagedByArea(s []StagedEntry)
SortStagedByArea sorts staged entries by area descending using insertion sort.
Types ¶
type Atlas ¶
type Atlas struct {
// Pages contains the atlas page images indexed by page number.
Pages []*ebiten.Image
Regions map[string]types.TextureRegion
// contains filtered or unexported fields
}
Atlas holds one or more atlas page images and a map of named regions.
func LoadAtlas ¶
LoadAtlas parses TexturePacker JSON data and associates the given page images. Supports both the hash format (single "frames" object) and the array format ("textures" array with per-page frame lists).
func New ¶
func New(cfg ...PackerConfig) *Atlas
New creates an empty Atlas ready for dynamic packing via Add. An optional PackerConfig controls page size and padding; defaults are 2048×2048 with 1 pixel padding.
func NewBatch ¶
func NewBatch(cfg ...PackerConfig) *Atlas
NewBatch creates an empty Atlas in batch mode. Use Stage to buffer images, then Pack to run MaxRects and finalize. No additions after Pack.
Batch mode packs more efficiently than shelf mode because all images are known upfront, allowing optimal placement via the MaxRects algorithm.
func (*Atlas) Add ¶
Add packs img into the atlas under the given name and returns its TextureRegion. If name already exists the existing region is returned (idempotent). Returns an error for nil, zero-size, or oversized images.
func (*Atlas) Free ¶
Free removes the named region and reclaims its space for reuse by future Add calls. The pixels on the atlas page are cleared to prevent stale bleeding. Returns an error if the name doesn't exist or if called on a batch atlas.
func (*Atlas) Pack ¶
Pack runs the MaxRects algorithm on all staged images and copies their pixels onto atlas pages. After Pack, Stage returns an error and Region returns valid regions.
func (*Atlas) Region ¶
func (a *Atlas) Region(name string) types.TextureRegion
Region returns the TextureRegion for the given name. If the name doesn't exist, it logs a warning (debug stderr) and returns a 1×1 magenta placeholder region on page index MagentaPlaceholderPage.
func (*Atlas) RegionCount ¶
RegionCount returns the number of named regions in the atlas.
func (*Atlas) Replace ¶
Replace swaps the pixels for an existing region in-place. The new image must be exactly the same size as the existing region. Returns an error if the name doesn't exist, sizes differ, or if called on a batch atlas.
func (*Atlas) Stage ¶
Stage buffers an image for later packing via Pack. Only valid on batch atlases (created with NewBatch). Returns an error if already packed, image is nil/zero-size, or name is a duplicate.
type Manager ¶
type Manager struct {
Refs []int // reference counts per page (exported for test access)
Static []bool // static pages that are never cleaned up (exported for test access)
// contains filtered or unexported fields
}
Manager is the global singleton that owns atlas page images. Pages are shared across Scenes, enabling fonts and atlases to be created independently of any particular Scene. Single-threaded (no sync needed).
func GlobalManager ¶
func GlobalManager() *Manager
GlobalManager returns the global Manager singleton, lazily initialised.
func (*Manager) Cleanup ¶
func (am *Manager) Cleanup()
Cleanup deallocates dynamic pages with zero references. Static pages and pages with non-zero refs are left untouched.
func (*Manager) Page ¶
Page returns the atlas page image at the given index, or nil if out of range.
func (*Manager) RegisterPage ¶
RegisterPage stores an atlas page image at the given index, growing internal slices as needed.
func (*Manager) Release ¶
Release decrements the reference count for the given page index. Does not go below zero.
type PackerConfig ¶
type PackerConfig struct {
PageWidth int // atlas page width in pixels (default 2048)
PageHeight int // atlas page height in pixels (default 2048)
Padding int // pixel gap between packed images (default 1); use NoPadding for 0
// contains filtered or unexported fields
}
PackerConfig controls the dynamic atlas packer created by New. Zero-value fields use defaults: 2048×2048 pages with 1 pixel padding. Set Padding to 0 explicitly via NoPadding to disable padding (risk of texture bleeding).
func NormalizePackerConfig ¶
func NormalizePackerConfig(c PackerConfig) PackerConfig
NormalizePackerConfig fills in defaults for any unset fields.
func (PackerConfig) NoPadding ¶
func (c PackerConfig) NoPadding() PackerConfig
NoPadding returns a PackerConfig modifier that explicitly sets padding to 0. Without this, a zero Padding field is treated as "use default (1)".
type RectPacker ¶
type RectPacker struct {
// contains filtered or unexported fields
}
RectPacker implements MaxRects bin packing for a single page.
func NewRectPacker ¶
func NewRectPacker(w, h int) *RectPacker
NewRectPacker creates a MaxRects packer for one page of size w × h.
func (*RectPacker) Place ¶
func (rp *RectPacker) Place(x, y, pw, ph int)
Place commits a placement at (x, y) with padded size (pw × ph). Splits overlapping free rects and prunes contained ones.
type ShelfPacker ¶
type ShelfPacker struct {
Padding int
// contains filtered or unexported fields
}
ShelfPacker manages shelf-based bin packing across multiple atlas pages.
func NewShelfPacker ¶
func NewShelfPacker(pageW, pageH, padding int) *ShelfPacker
NewShelfPacker creates a shelf packer with the given page dimensions and padding.
func (*ShelfPacker) Free ¶
func (sp *ShelfPacker) Free(pageIdx, x, y, pw int)
Free marks the region at (x, y) with padded width pw on the given page as a reusable free slot. The shelf height at that Y coordinate determines the slot's vertical extent.
Source Files