Documentation
¶
Overview ¶
Package cover draws the artwork behind the menu. Two artworks ship: Photo projects the picture in assets — the project's own flat-poster reduction of the 1962 box lid composition, whose provenance assets/README.md records — and Homage is a composition drawn from scratch in character art. Both exist because they fail differently: the projection carries the lid itself and wins wherever the grid is fine enough to hold it, while the homage is drawn in cells to begin with and survives the small boxes and the monochrome terminals that turn any projection to noise. Best says which one a given box deserves.
Everything here is characters and ANSI colour. Terminal graphics protocols (kitty, sixel) reach a minority of terminals and fail unevenly through multiplexers, so the cover is drawn with the one facility every terminal has. The output is a slice of lines rather than a framed screen because the caller owns layout: it knows where the box is, this package only knows what goes inside it.
Index ¶
Constants ¶
const EnvArt = "TWIXTUI_COVER_ART"
EnvArt overrides which artwork Best answers with: "photo" or "homage".
TWIXTUI_COVER_ART=homage twixtui
const EnvImage = "TWIXTUI_COVER_IMAGE"
EnvImage names an image file for Photo to project instead of the shipped picture.
TWIXTUI_COVER_IMAGE=/path/to/scan.jpg twixtui
Variables ¶
This section is empty.
Functions ¶
func FromEnvironment ¶
FromEnvironment configures the photograph from EnvImage. It reports whether one was configured; an unset variable is normal life, not an error, but a set variable naming an unreadable or undecodable file is reported, because silently falling back to the shipped picture would leave the player staring at the wrong picture with nothing to debug.
func MinSize ¶
MinSize reports the smallest box the artwork is legible in.
The homage bound is where the compact wordmark and a three-peg scene still fit; below it the composition stops being the cover and becomes noise, and the caller should draw a plain title instead. The photograph bound is looser because legibility depends on the picture, but below roughly a thousand braille dots no picture survives, so that is where the line is drawn.
func ParseEnvironment ¶
func ParseEnvironment() []error
ParseEnvironment applies both environment variables and returns every complaint it has, so the command line can report them once, before the program switches the terminal to its alternate screen. Nothing on a drawing path reports anything: Best is called for every frame, so a diagnostic there would repeat for as long as the menu is open and would be written over the picture.
A bad value is reported and then ignored, rather than being fatal. Somebody who mistypes the name of an artwork wants to play the game, not to be stopped by it.
func Render ¶
Render lays the artwork out to fit within w by h character cells and returns the lines to draw, which may be fewer and narrower than the box. Styling is embedded as ANSI unless depth is DepthMono. It never returns lines wider than w or more than h of them.
func SetPhoto ¶
SetPhoto decodes the image at path and makes Photo project it instead of the shipped picture. Where the path comes from — a flag, a settings file, EnvImage — is the caller's business; this package only insists the file is a decodable JPEG or PNG, and says which of those went wrong when it refuses one.
Types ¶
type Art ¶
type Art int
Art selects which artwork to draw.
func Best ¶
Best says which artwork a box deserves, which is the rule the side-by-side evaluation of both artworks settled. That evaluation, the converters that were tried and dropped, and the sizes each artwork wins at are written up in docs/COVER.md; it used to cite a file in the development tree, which no reader of the repository could ever have, since that tree is not published.
An explicit choice in EnvArt is honoured first and wins whatever the size and depth suggest, including in monochrome, where the projection becomes braille. Failing that: monochrome takes the homage, because it is drawn for runes and a dithered projection there is noise; and in colour the projection answers once the grid its picture occupies is fine enough to keep the wordmark and the figure readable, the homage under that. A caller that wants neither default passes its own choice to Render.
Source Files