README
¶
TileConv
This project is aimed at being a library for converting images to retro 8x8 tile graphics formats (and back), and for convenience also includes a CLI tool that uses the library to do that conversion for basic images.
It is targeted at consoles and images that use indexed-color (paletted) graphics, and at images that are specifically designed for that console.
As such, this library works on the color indexes themselves, rather than their colors, since that is more useful and easier to reason about.
Each kind of tile graphics format is handled by an implementation of the Codec interface, usually with a field to specify the bit depth you want.
E.g. for a basic packed-pixel format, with 4 bits per pixel:
codec := tileconv.Packed{BitDepth: tileconv.BD4}
Some additional functionality, like handling multiple tiles per image, is built on top of that interface as separate top-level functions.
E.g. to convert an image with multiple tiles to an output file:
err := tileconv.Encode(img, outfile, codec)
Note that the codec implementations in this package often support more variations (e.g. bit depths) than are supported by the retro consoles themselves, so you still need to do your own due diligence on that.
Documentation
¶
Overview ¶
Package tileconv provides conversion between images and several retro 8x8 tile graphics formats.
It is targeted at consoles and images that use indexed-color (paletted) graphics, and at images that are specifically designed for that console.
As such, this package works on the color indexes themselves, rather than their colors, since that is more useful and easier to reason about.
Organization ¶
The main abstraction that this package provides is that of the Codec interface. A Codec represents a tile graphics format, and provides a way to encode or decode a single tile using that format.
Additional functionality, like handling multiple tiles, is then built on top of that abstraction.
This makes it fairly easy both to pick which format you need to use, and to extend the library with other formats if necessary.
To avoid a proliferation of types, it is common for an implementation to support multiple closely related formats, with a field to specify which.
This is where the BitDepth type comes in, to specify which bit depth (how many bits per pixel) should be used during the conversion.
Note that the codec implementations in this package often support more variations (e.g. bit depths) than are supported by the retro consoles themselves, so you still need to do your own due diligence on that.
Example ¶
package main
import (
"fmt"
"image"
"image/color/palette"
"os"
"github.com/edorfaus/tileconv"
)
func main() {
input := []byte("12345678abcdefgh")
tile := image.NewPaletted(image.Rect(0, 0, 8, 8), palette.Plan9)
codec1 := tileconv.TilePlanar{BitDepth: tileconv.BD2}
tileconv.Decode(input, tile, codec1)
codec2 := tileconv.RowPlanar{BitDepth: tileconv.BD2}
err := tileconv.Encode(tile, os.Stdout, codec2)
if err != nil {
fmt.Fprintln(os.Stderr, "Error:", err)
}
}
Output: 1a2b3c4d5e6f7g8h
Index ¶
Examples ¶
Constants ¶
const BytesPerPlane = 8
BytesPerPlane is the number of bytes taken up by each bit plane of a single tile.
Since each tile is 8x8 pixels, and each plane only stores 1 bit per pixel, each row fits in a single byte. Thus, this is just the height.
Variables ¶
This section is empty.
Functions ¶
func Decode ¶
Decode all the tiles in the given byte slice into the given image, using the given codec to decode each tile.
The tiles are placed on the destination image in row-major order from top to bottom, left to right; starting from the top-left corner.
If the image size is not an even multiple of the tile size, then some of the tile graphics may be lost due to being rendered partially outside of the image. Similarly, if the image is not large enough to fit all the source tiles, then the remaining tiles will be lost.
The destination image must have a palette that is large enough for the bit depth of the codec, otherwise this may break the image.
func Encode ¶
Encode all the tiles in the given image into the given writer, using the given codec to encode each tile.
The tiles are written in row-major order from top to bottom, left to right.
If the image size is not an even multiple of the tile size, then the size is rounded up by adding to the right and bottom coordinates. This will make Encode ask the image for pixels outside of its bounds, which typically returns a default color index (usually 0).
Types ¶
type BitDepth ¶
type BitDepth uint8
BitDepth represents the number of bits to use per pixel of each tile.
E.g. for a 4-color palette, there are 2 bits per pixel, so depth 2.
Note that the methods on this type assume tiles are 8x8 pixels.
func (BitDepth) BytesPerTile ¶
BytesPerTile returns the number of bytes that will be necessary to store a single tile using this bit depth.
func (BitDepth) ColorMask ¶
ColorMask returns a bitmask containing a 1 for each bit of the color index that is actually used when using this bit depth.
func (*BitDepth) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler.
type Codec ¶
type Codec interface {
// Encode the given part of the image into the given buffer.
//
// The x and y args specify the top-left corner of the tile in src.
//
// The dst slice must be large enough - at least Size() bytes long.
//
// Encode is not allowed to modify src, nor any part of dst that is
// beyond the first Size() bytes.
Encode(src SourceImage, x, y int, dst []byte)
// Decode the source data into an image at the given coordinates.
//
// The x and y args specify the top-left corner of the tile in dst.
//
// The src slice must be at least Size() bytes long; any data after
// that is ignored.
//
// Decode is not allowed to modify src, nor any part of dst except
// the color indexes inside the target area (the 8x8 tile at x,y).
Decode(src []byte, dst DestImage, x, y int)
// Size returns the size of the encoded data for this codec.
//
// It thus gives the minimum size of any buffers that are given to
// the Encode or Decode methods.
Size() int
}
Codec is the interface implemented by each tile image format type.
Each system can thus pick the codec that corresponds to the way it encodes its tile/sprite graphics, while reusing the surrounding code.
type DestImage ¶
DestImage represents an indexed-color image that can be used as a destination image by Codec.Decode() (its pixels can be changed).
type Image ¶
type Image interface {
SourceImage
DestImage
}
Image represents an indexed-color image that a Codec can use as both a source and a destination, both encoding from and decoding into it.
type Packed ¶
type Packed struct {
BitDepth BitDepth
}
Packed is a Codec that encodes each tile as a packed-pixel image, with the bits for each pixel of the tile stored contiguously, such that at depth 8, each byte is one pixel.
type RowPlanar ¶
type RowPlanar struct {
BitDepth BitDepth
}
RowPlanar is a Codec that encodes each tile as a planar image, with the planes for each row stored contiguously. In other words, all the data for the first row is stored before the data for the second, and so on.
type SourceImage ¶
SourceImage represents an indexed-color image that can be used as a source image by Codec.Encode() (its pixels can be read).
type TilePlanar ¶
type TilePlanar struct {
BitDepth BitDepth
}
TilePlanar is a Codec that encodes each tile as a planar image, with each plane of the tile stored contiguously - such that a tile with bit depth N can be extended to N+1 bits by appending a zeroed plane.
func (TilePlanar) Decode ¶
func (c TilePlanar) Decode(src []byte, dst DestImage, x, y int)
Decode implements Codec, decoding bytes into an image.
func (TilePlanar) Encode ¶
func (c TilePlanar) Encode(src SourceImage, x, y int, dst []byte)
Encode implements Codec, encoding a tile image into bytes.
func (TilePlanar) Size ¶
func (c TilePlanar) Size() int
Size implements Codec, returning the size of a tile.
type TileRowPairPlanar ¶
type TileRowPairPlanar struct {
BitDepth BitDepth
}
TileRowPairPlanar is a Codec that encodes each tile as a planar image, with the planes stored in pairs (as if it was a sequence of 2bpp tiles), and each plane pair stored in a row-planar manner.
Thus: r0p0, r0p1, r1p0, r1p1, ..., r7p1, r0p2, r0p3, r1p2, ..., r7pN.
This codec only really supports even bit depths; odd bit depths will be rounded up to the next even bit depth, except that the extra bit plane will be forced to zero.
func (TileRowPairPlanar) Decode ¶
func (c TileRowPairPlanar) Decode(src []byte, dst DestImage, x, y int)
Decode implements Codec, decoding bytes into an image.
func (TileRowPairPlanar) Encode ¶
func (c TileRowPairPlanar) Encode(s SourceImage, x, y int, d []byte)
Encode implements Codec, encoding a tile image into bytes.
func (TileRowPairPlanar) Size ¶
func (c TileRowPairPlanar) Size() int
Size implements Codec, returning the size of a tile.
Source Files
Directories