imretro

README

Imretro

This is the Go implementation of the imretro image format.

Import

import "github.com/imretro/go" // Imports the "imretro" package

Documentation

Overview

Encode and decode retro-style images in the imretro format.

Example (Decode)

package main

import (
	"bytes"
	"fmt"
	"image"
	"io"
	"log"

	_ "github.com/imretro/go"
)

// ImgBytes declares a 2x2 image with no in-file palette, 1 bit per pixel, and
// an alternating white/black checkerboard pattern.
var ImgBytes = []byte{'I', 'M', 'R', 'E', 'T', 'R', 'O', 0x00, 0, 2, 0, 2, 0b1001_0000}

func main() {
	var reader io.Reader = bytes.NewBuffer(ImgBytes)
	img, format, err := image.Decode(reader)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Format: %s\n", format)

	bounds := img.Bounds()

	for y := bounds.Min.Y; y < bounds.Max.Y; y++ {
		for x := bounds.Min.X; x < bounds.Max.X; x++ {
			r, g, b, _ := img.At(x, y).RGBA()
			fmt.Printf("r = %04X, g = %04X, b = %04X\n", r, g, b)
		}
	}

}

Output:

Format: imretro
r = FFFF, g = FFFF, b = FFFF
r = 0000, g = 0000, b = 0000
r = 0000, g = 0000, b = 0000
r = FFFF, g = FFFF, b = FFFF

Example (Decode_config)

package main

import (
	"bytes"
	"fmt"
	"image"
	"io"
	"log"

	_ "github.com/imretro/go"
)

// ImgBytes declares a 2x2 image with no in-file palette, 1 bit per pixel, and
// an alternating white/black checkerboard pattern.
var ImgBytes = []byte{'I', 'M', 'R', 'E', 'T', 'R', 'O', 0x00, 0, 2, 0, 2, 0b1001_0000}

func main() {
	var reader io.Reader = bytes.NewBuffer(ImgBytes)
	config, format, err := image.DecodeConfig(reader)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Format: %s\n", format)
	fmt.Printf("width: %d\nheight: %d\n", config.Width, config.Height)

}

Output:

Format: imretro
width: 2
height: 2

Index

• Constants
• Variables
• func ChannelAsByte(channel uint32) byte
• func ColorAsBytes(c color.Color) (r, g, b, a byte)
• func ColorFromBytes(bs []byte) color.Color
• func DecodeConfig(r io.Reader, customModels ModelMap) (image.Config, error)
• func Encode(w io.Writer, m image.Image, pixelMode PixelMode) error
• func IsBitCountSupported(count PixelMode) bool
• type ColorModel
  • func NewOneBitColorModel(off color.Color, on color.Color) ColorModel
  • func NewTwoBitColorModel(off, light, strong, full color.Color) ColorModel
  • func (model ColorModel) Convert(c color.Color) color.Color
  • func (model ColorModel) Index(c color.Color) uint8
  • func (model ColorModel) PixelMode() PixelMode
• type DecodeError
  • func (e DecodeError) Error() string
• type DimensionsTooLargeError
  • func (e DimensionsTooLargeError) Error() string
• type ImretroImage
  • func Decode(r io.Reader, customModels ModelMap) (ImretroImage, error)
• type MissingModelError
  • func (mode MissingModelError) Error() string
• type ModelMap
• type PixelMode
• type UnsupportedBitModeError
  • func (e UnsupportedBitModeError) Error() string

Examples

• Package (Decode)
• Package (Decode_config)

Constants

const ImretroSignature = "IMRETRO"

ImretroSignature is the "magic string" used for identifying an imretro file.

const MaximumDimension int = 0xFF_FF

MaximumDimension is the maximum size of an image's boundary in the imretro format.

const PaletteIndex byte = 2

PaletteIndex is the "index" (from the left) of the bit in the mode byte that signifies if there is an in-file palette.

const WithPalette byte = 1 << (7 - PaletteIndex)

WithPalette can be used with a union with the bit count when setting the header.

Variables

var (
	Default1BitColorModel = NewOneBitColorModel(Black, White)
	Default2BitColorModel = NewTwoBitColorModel(Black, DarkGray, LightGray, White)
	Default8BitColorModel = make(ColorModel, 256)
)

var (
	// NoColor is "invisible" and signifies a lack of color.
	NoColor color.Color = color.Alpha{0}
	Black   color.Color = color.Gray{0}
	// DarkerGray is 25% light.
	DarkerGray = color.Gray{0x40}
	// DarkGray is 33% light, and can be used for splitting a monochromatic
	// color range into 4 parts (0, 33%, 66%, 100%).
	DarkGray = color.Gray{0x55}
	// MediumGray is the exact middle between black and white.
	MediumGray = color.Gray{0x80}
	// LightGray is 66% light, and can be used for splitting a monochromatic
	// color range into 4 parts (0, 33%, 66%, 100%).
	LightGray = color.Gray{0xAA}
	// LighterGray is 75% light.
	LighterGray = color.Gray{0xC0}
	White       = color.Gray{0xFF}
)

var DefaultModelMap = ModelMap{
	OneBit:   Default1BitColorModel,
	TwoBit:   Default2BitColorModel,
	EightBit: Default8BitColorModel,
}

DefaultModelMap maps bit modes to the default color models.

var ErrUnknownModel = errors.New("Color model not recognized")

ErrUnknownModel is raised when an unknown color model is interpreted.

Functions

func ChannelAsByte

func ChannelAsByte(channel uint32) byte

ChannelAsByte converts a uint32 color channel ranging within [0, 0xFFFF] to a byte.

func ColorAsBytes

func ColorAsBytes(c color.Color) (r, g, b, a byte)

ColorAsBytes converts a color to a 4-byte (one byte for each channel) representation.

func ColorFromBytes

func ColorFromBytes(bs []byte) color.Color

ColorFromBytes converts 4 bytes into a color. Panics if the slice has less than 4 bytes.

func DecodeConfig

func DecodeConfig(r io.Reader, customModels ModelMap) (image.Config, error)

DecodeConfig returns the color model and dimensions of an imretro image without decoding the entire image.

Custom color models can be used instead of the default model.

func Encode

func Encode(w io.Writer, m image.Image, pixelMode PixelMode) error

Encode writes the image m to w in imretro format.

func IsBitCountSupported

func IsBitCountSupported(count PixelMode) bool

IsBitCountSupported checks if the bit count is supported by the imretro format.

Types

type ColorModel

type ColorModel color.Palette

ColorModel is color model for imretro images.

func NewOneBitColorModel

func NewOneBitColorModel(off color.Color, on color.Color) ColorModel

NewOneBitColorModel creates a new color model for 1-bit-pixel images.

func NewTwoBitColorModel

func NewTwoBitColorModel(off, light, strong, full color.Color) ColorModel

NewTwoBitColorModel creates a new color model for 2-bit-pixel images.

func (ColorModel) Convert

func (model ColorModel) Convert(c color.Color) color.Color

func (ColorModel) Index

func (model ColorModel) Index(c color.Color) uint8

Index returns the index of the palette color.

func (ColorModel) PixelMode

func (model ColorModel) PixelMode() PixelMode

PixelMode gets the bits-per-pixel according to the color model.

type DecodeError

type DecodeError string

DecodeError is an error signifying that something unexpected happened when decoding the imretro reader.

func (DecodeError) Error

func (e DecodeError) Error() string

Error reports that the format could not be decoded as imretro.

type DimensionsTooLargeError

type DimensionsTooLargeError int

DimensionsTooLargeError should be returned when an encoded image would have boundaries that are not valid in the encoding.

func (DimensionsTooLargeError) Error

func (e DimensionsTooLargeError) Error() string

Error makes a string representation of the too-large error.

type ImretroImage

type ImretroImage interface {
	image.PalettedImage
	// Palette gets the palette of the image.
	Palette() color.Palette
	// PixelMode returns the pixel mode of the image.
	PixelMode() PixelMode
	// BitsPerPixel returns the number of bits used for each pixel.
	BitsPerPixel() int
}

ImretroImage is an image decoded from the imretro format.

func Decode

func Decode(r io.Reader, customModels ModelMap) (ImretroImage, error)

Decode decodes an image in the imretro format.

Custom color models can be used instead of the default color models. See the documentation for the model types for more details. If the decoded image contains an in-image palette, the model will be generated from that instead of the custom value passed or the default models.

type MissingModelError

type MissingModelError PixelMode

MissingModelError is raised when there is no model for the given pixel bit mode.

func (MissingModelError) Error

func (mode MissingModelError) Error() string

Error reports the pixel mode lacking the color model.

type ModelMap

type ModelMap = map[PixelMode]color.Model

ModelMap maps bit modes to color models.

type PixelMode

type PixelMode = byte

PixelMode is the type for managing the number of bits per pixel.

const (
	OneBit PixelMode = iota << 6
	TwoBit
	EightBit
)

type UnsupportedBitModeError

type UnsupportedBitModeError byte

UnsupportedBitModeError should be returned when an unexpected number of bits is received.

func (UnsupportedBitModeError) Error

func (e UnsupportedBitModeError) Error() string

Error converts to an error string.