assetrender

Documentation

Overview

Package assetrender turns Total Annihilation game files into the byte streams a browser can display: raw passthrough, format-specific "describe" metadata, and image/video renderings.

Every operation that needs to read a file — including the sidecar files a render depends on, such as a TNT map's companion .ota or a GAF's palette — hangs off a Renderer that owns a VirtualFileSystem. Callers construct one Renderer per mounted game and invoke its methods; nothing here reaches for a package-global filesystem.

Index

• func RawContentType(ext string) (string, bool)
• func TransparencyFromQuery(q string) (gaf.RenderOptions, string)
• type Options
• type RenderRequest
  • func (req RenderRequest) CacheTag() string
  • func (req RenderRequest) IsRender() bool
• type Rendered
• type Renderer
  • func New(vfs *filesystem.VirtualFileSystem, opts Options) *Renderer
  • func (r *Renderer) Cache(name string) *cache.Cache
  • func (r *Renderer) CacheKey(path string, data []byte) string
  • func (r *Renderer) Describe(vpath string, data []byte) (map[string]any, bool)
  • func (r *Renderer) GlobalPalette() color.Palette
  • func (r *Renderer) Render(vpath string, data []byte, req RenderRequest) (Rendered, error)
  • func (r *Renderer) ResolvePalette(gafPath, override string) (*gaf.Palette, string)
  • func (r *Renderer) VFS() *filesystem.VirtualFileSystem

Functions

func RawContentType

func RawContentType(ext string) (string, bool)

RawContentType maps a file extension to the MIME type used when serving the file's bytes verbatim. The bool reports whether the type was recognised (false means the octet-stream default was used).

func TransparencyFromQuery

func TransparencyFromQuery(q string) (gaf.RenderOptions, string)

TransparencyFromQuery converts the ?transparency= query value into a gaf.RenderOptions plus a short cache tag. Accepted forms: "" / "auto" (heuristic), "metadata", "none", or a "0".."255" palette index. Unknown values fall back to auto so a stale query can't break rendering.

Types

type Options

type Options struct {
	// CacheDir is the root directory under which per-representation caches
	// (gaf-png, tnt-png, …) are created. When empty the Renderer runs without
	// an on-disk cache.
	CacheDir string
	// NoCache disables the on-disk cache even when CacheDir is set.
	NoCache bool
}

Options configures a Renderer.

type RenderRequest

type RenderRequest struct {
	Format       string // output encoding hint: png, gif, apng, jpg, bmp
	View         string // TNT/SCT view: tilemap, minimap, heightmap, buildmap, voidmap, ascii
	Sequence     int    // GAF sequence index (used when SequenceName is empty)
	SequenceName string // GAF sequence by name (wins over Sequence when set)
	Frame        int    // GAF frame index; -1 renders the whole sequence
	Text         string // FNT preview text (empty falls back to a pangram)
	Palette      string // palette override path (VFS-relative)
	Transparency string // GAF transparency mode or index
}

RenderRequest captures the query options a representation URL can carry. The studio HTTP layer parses it from the request's query string; the cache-warmer builds it directly. Unset numeric selectors use -1 so "frame 0" stays distinct from "no frame".

func (RenderRequest) CacheTag

func (req RenderRequest) CacheTag() string

CacheTag is a short, stable digest of the request options. Folded into an HTTP ETag it ensures a palette/view/frame change yields a distinct validator so browsers don't serve a stale representation from a 304.

func (RenderRequest) IsRender

func (req RenderRequest) IsRender() bool

IsRender reports whether req asks for a rendered representation rather than the raw bytes. The handler uses it to decide between Render and a plain passthrough.

type Rendered

type Rendered struct {
	ContentType string
	Body        []byte
	Path        string
}

Rendered is one produced representation ready to write to an HTTP response. Most renders carry their bytes in Body. Large, seekable results (transcoded video) instead set Path to an on-disk cache file so the HTTP layer can serve it with http.ServeFile and honour Range requests; when Path is set Body is empty.

type Renderer

type Renderer struct {
	// contains filtered or unexported fields
}

Renderer produces representations of VFS files. It is safe for concurrent use: the cache map is guarded by a mutex and the underlying caches are themselves stateless filesystem wrappers.

func New

func New(vfs *filesystem.VirtualFileSystem, opts Options) *Renderer

New builds a Renderer backed by vfs.

func (*Renderer) Cache

func (r *Renderer) Cache(name string) *cache.Cache

Cache returns the named on-disk cache (e.g. "gaf-png"), creating it on first use. It returns nil when caching is disabled or the directory can't be created, so callers must tolerate a nil cache and simply render fresh.

func (*Renderer) CacheKey

func (r *Renderer) CacheKey(path string, data []byte) string

CacheKey returns a stable content hash for path. It prefers the MD5 the VFS precomputes at mount time and falls back to hashing data directly, so a representation's cache entry is keyed to the exact bytes that produced it.

func (*Renderer) Describe

func (r *Renderer) Describe(vpath string, data []byte) (map[string]any, bool)

Describe returns a structured description of the file at vpath given its bytes. The bool reports whether a format-specific describer recognised the extension; when false the returned map carries only the seeded "format" key and the caller should fall back to generic metadata.

func (*Renderer) GlobalPalette

func (r *Renderer) GlobalPalette() color.Palette

GlobalPalette returns the install-wide color.Palette used to render index formats that carry no palette of their own (TNT, SCT). It reads palettes/palette.pal from the VFS and falls back to the embedded TA palette. Index 0 is forced transparent to match the game's treatment of the void.

func (*Renderer) Render

func (r *Renderer) Render(vpath string, data []byte, req RenderRequest) (Rendered, error)

Render produces a non-raw representation of the file at vpath. It dispatches on the file extension and caches the encoded result keyed to the file's content plus the request options, so palette/transparency/view changes each get their own entry.

func (*Renderer) ResolvePalette

func (r *Renderer) ResolvePalette(gafPath, override string) (*gaf.Palette, string)

ResolvePalette picks the palette for rendering gafPath, honoring an optional override and otherwise using palettepick's auto-detection chain. It returns the palette plus a short provenance tag suitable for folding into a cache key so swapping palettes invalidates stale renders.

func (*Renderer) VFS

func (r *Renderer) VFS() *filesystem.VirtualFileSystem

VFS exposes the underlying filesystem so HTTP handlers can list directories and stat files without a second mount.