writer

Documentation

Overview

Package writer serialises a render.Canvas into bytes.

Writers are registered by format name and looked up through the registry. Adding an output format is one new file plus one Register call; no caller switches on a format string.

Sizing is resolved here rather than in render, because pixels are an output concern: the same Canvas becomes a 10-pixels-per-module PNG, a resolution independent SVG, and a grid of terminal half-blocks without being rendered three times.

Index

• Constants
• Variables
• func Formats() []string
• func PixelSize(c render.Canvas, o OutputOpts) (w, h, scale int, err error)
• func Rasterize(c render.Canvas, o OutputOpts) (*image.NRGBA, error)
• func Register(w Writer)
• type OutputOpts
  • func DefaultOutputOpts(format string) OutputOpts
• type Unit
• type Writer
  • func All() []Writer
  • func Get(format string) (Writer, error)

Constants

const (
	// ASCII is the registry name of the ASCII-art writer.
	ASCII = "ascii"
	// Text is the registry name of its alias.
	Text = "txt"
)

Registry names of the plain-text writers. Both produce identical bytes; "txt" exists because that is what people type when they want a file and "ascii" because that is what they type when they want to look at it.

const ANSI = "ansi"

ANSI is the registry name of the true-colour terminal writer.

const DataURI = "datauri"

DataURI is the registry name of the data-URI writer.

const DefaultQuality = 92

DefaultQuality is the JPEG quality used when none is given. Ninety-two is high enough that the ringing around a module edge stays well inside one module at the default scale, which is what keeps a JPEG code scannable.

const DefaultScale = 10

DefaultScale is the pixels-per-module used when neither a scale nor an explicit size is given. Ten pixels per module reproduces reliably on screen and on a consumer printer.

const FormatEPS = "eps"

FormatEPS is the registry name of the Encapsulated PostScript writer.

const FormatPDF = "pdf"

FormatPDF is the registry name of the PDF writer.

const FormatSVG = "svg"

FormatSVG is the registry name of the SVG writer.

const JPEG = "jpeg"

JPEG is the registry name of the JPEG writer.

const JSON = "json"

JSON is the registry name of the JSON writer.

const PNG = "png"

PNG is the registry name of the PNG writer.

const Unicode = "unicode"

Unicode is the registry name of the half-block writer.

const WebP = "webp"

WebP is the registry name of the WebP writer.

Variables

var (
	// ErrUnknownFormat means no writer is registered under that name.
	ErrUnknownFormat = errors.New("unknown output format")
	// ErrCanvasTooLarge means the requested pixel dimensions exceed the
	// configured cap. It is a limit, not a bug: it exists so that
	// output.scale=99999 cannot exhaust memory.
	ErrCanvasTooLarge = errors.New("output exceeds the maximum canvas size")
	// ErrInvalidOutput means the output options are inconsistent, such as a
	// negative scale or a JPEG quality outside 1..100.
	ErrInvalidOutput = errors.New("invalid output options")
	// ErrUnsupportedOutput means the writer cannot represent this canvas, for
	// example a terminal writer asked for a logo.
	ErrUnsupportedOutput = errors.New("output format cannot represent this canvas")
)

Sentinel errors. The HTTP layer maps these onto stable error codes.

Functions

func Formats

func Formats() []string

Formats lists every registered format, sorted. It backs the format list in /v1/symbologies and the closest-match suggestion on an unknown format.

func PixelSize

func PixelSize(c render.Canvas, o OutputOpts) (w, h, scale int, err error)

PixelSize resolves the output dimensions for a canvas in pixels.

Precedence is explicit Size first, then Scale, then DefaultScale. The result is always a whole number of pixels per module: a fractional module width is the most common cause of a code that looks fine and scans badly, because the rasteriser rounds different modules differently.

func Rasterize

func Rasterize(c render.Canvas, o OutputOpts) (*image.NRGBA, error)

Rasterize draws a canvas into an NRGBA image.

It is the single raster path: PNG, JPEG, WebP and anything else pixel-based differ only in how they encode the result, so sizing, shape dispatch, eye painting and the human-readable text all live here and are exercised by every raster format at once.

The drawing happens in two layers. Every module, eye and glyph is painted onto a transparent ink layer, which is then composited over the background in one pass. That indirection is not decoration: EyePainter.RasterFrame punches the centre of a finder frame back to transparent, and a painter may use a translucent colour. Painting straight onto a filled background would leave a hole through an opaque background and would make a translucent module blend with nothing. Compositing once makes both cases correct without the rasteriser knowing the shape of any particular hole.

The background is a single flat colour, so the composite happens in place against that colour rather than into a second image. It saves a full-image allocation and a copy on every render, which on a default QR is most of the rasteriser's cost.

func Register

func Register(w Writer)

Register adds a writer under its own format name. It panics on a duplicate, because two writers claiming one format is a programming error that must surface at startup rather than resolve arbitrarily.

Register is intended for init functions.

Types

type OutputOpts

type OutputOpts struct {
	// Format is the registry key, e.g. "png".
	Format string

	// Scale is pixels per module. Zero means derive from Size, or fall back
	// to DefaultScale.
	Scale int
	// Size is the target width of the whole image, including the quiet zone,
	// expressed in Unit. Zero means derive from Scale.
	Size float64
	// Unit interprets Size. Empty means UnitPx.
	Unit Unit
	// DPI converts physical units to pixels and is written into formats that
	// record it. Zero means 300, the usual print default.
	DPI int

	// Quality is the JPEG and WebP quality, 1..100. Zero means 92.
	Quality int

	// MaxPixels caps width*height. Zero means no cap, which only tests and
	// the CLI should use; the HTTP layer always sets it.
	MaxPixels int64

	// Filename and Attachment drive the Content-Disposition header. They are
	// carried here so one struct describes the whole output.
	Filename   string
	Attachment bool
}

OutputOpts are the format-level options for a single write.

func DefaultOutputOpts

func DefaultOutputOpts(format string) OutputOpts

DefaultOutputOpts returns the options a request with no output section gets.

type Unit

type Unit string

Unit is the measurement system for an explicit output size.

const (
	// UnitPx sizes in pixels and ignores DPI.
	UnitPx Unit = "px"
	// UnitMM sizes in millimetres, converted through DPI.
	UnitMM Unit = "mm"
	// UnitIn sizes in inches, converted through DPI.
	UnitIn Unit = "in"
)

Supported units.

type Writer

type Writer interface {
	// Name is the registry key and the value of output.format.
	Name() string
	// MIME is the Content-Type to serve the result with.
	MIME() string
	// Extension is the filename suffix, without the dot.
	Extension() string
	// Binary reports whether the output is binary rather than text. It drives
	// data-URI base64 selection and terminal-safety checks.
	Binary() bool
	// Write serialises the canvas.
	Write(c render.Canvas, o OutputOpts) ([]byte, error)
}

Writer serialises a Canvas.

Implementations must be safe for concurrent use and must not retain the Canvas they are given.

func All

func All() []Writer

All returns every registered writer, sorted by format name.

func Get

func Get(format string) (Writer, error)

Get returns the writer registered for a format.