codec

Documentation

Overview

Package codec is go-gfx's unified image-decoding registry: one Decode entry point that sniffs a byte slice's container format and dispatches to the appropriate REFERENCE decoder, returning the shared raster.Image substrate the rest of go-gfx consumes.

It reimplements NO decoder. Every format is handed to a battle-tested pure-Go (CGO-free) reference library, and this package only sniffs the format, delegates, and converts the reference's image.Image into a straight-alpha raster.Image:

format  reference decoder                          module
------  ----------------------------------------   ------------------------------------
PNG     image/png                                  standard library
JPEG    image/jpeg                                 standard library
GIF     image/gif                                  standard library
WEBP    golang.org/x/image/webp                    golang.org/x/image
TIFF    golang.org/x/image/tiff                    golang.org/x/image
BMP     golang.org/x/image/bmp                     golang.org/x/image
ICO     github.com/sergeymakinen/go-ico            github.com/sergeymakinen/go-ico
ICNS    image/png (per embedded PNG representation)  standard library  [see icns.go]

ICNS is the single format with no clean pure-Go decode reference (see the verdict in icns.go): its container is demuxed here by a bounds-checked TLV walk and each embedded PNG representation is decoded by the standard library — so no image decoder is reimplemented, only the container is unpacked, exactly as go-ico unpacks the .ico container around the standard BMP/PNG decoders.

Decode returns the primary (largest, most detailed) image of a container. DecodeBest additionally lets a caller target a pixel size for the multi-representation formats (ICO, ICNS), picking the smallest representation at least as large as the target, or the largest available when none reaches it. All decoders are pure-Go; the package never shells out and never needs CGO.

Index

• Variables
• func Decode(data []byte) (*raster.Image, error)
• func DecodeBest(data []byte, targetSize int) (*raster.Image, error)
• type Format
  • func Sniff(data []byte) Format
  • func (f Format) String() string

Variables

var ErrUnknownFormat = fmt.Errorf("codec: unrecognised image format")

ErrUnknownFormat is returned by Decode and DecodeBest when the input's leading bytes match no format the registry knows how to decode.

Functions

func Decode

func Decode(data []byte) (*raster.Image, error)

Decode sniffs data's format, delegates to the matching reference decoder, and returns the image as a straight-alpha raster.Image. For multi-representation containers (ICO, ICNS) it returns the largest, most detailed representation; use DecodeBest to target a size. It returns ErrUnknownFormat for an unrecognised input and the reference decoder's own error for a corrupt one.

func DecodeBest

func DecodeBest(data []byte, targetSize int) (*raster.Image, error)

DecodeBest is Decode with a target pixel size for the multi-representation formats. For ICO and ICNS it selects the representation whose larger side is the smallest that is still >= targetSize, falling back to the largest representation when none reaches the target; a targetSize <= 0 always selects the largest. targetSize is ignored for single-image formats, whose sole image is returned regardless.

Types

type Format

type Format int

Format identifies a decodable image-container format recognised by Sniff.

const (
	Unknown Format = iota
	PNG
	JPEG
	GIF
	WEBP
	TIFF
	BMP
	ICO
	ICNS
	PNM // Netpbm: PBM/PGM/PPM, ASCII (P1–P3) and binary (P4–P6)
	QOI // Quite OK Image
)

The container formats codec can decode. Unknown is the zero value returned when a byte slice matches no known signature.

func Sniff

func Sniff(data []byte) Format

Sniff identifies the container format of data from its magic bytes, without decoding it. It returns Unknown when the input is too short or matches no known signature.

func (Format) String

func (f Format) String() string

String returns the format's short uppercase name (e.g. "PNG"), or "unknown".