packer

Documentation

Overview

Package packer provides a texture packing implementation that will take a list on input images and build them into a larger image and a descriptor file.

Texture packing is usually used to optimise runtime performance where a number of textures must be drawn to the screen at high frequency but can also be used to improve load times for pages loaded with HTTP 1.x.

A simple example of usage is;

params := packer.Params{
	Name:   "myatlas",
	Format: target.Love,
	Input:  packer.NewFileStream("./assets"),
	Output: packer.NewFileOutputter("./build"),
}
log.Fatal(packer.Run(context.Background(), &params))

You can specify maximum width and height of an atlas to conform to platform limitations and you can build multiple atlases with a single command.

The Input and Output parameters have been designed to be highly flexible. Simple file system readers and writers are provided out of the box but consumers could implement the AssetStreamer and Outputter interfaces to support more complex texture packing environments eg. Reading and writing to Google Cloud Storage.

For example, here is a complete AssetStreamer that reads assets from memory.

// Define the Asset that we will return
// The Asset interface simply augments the
// io.ReadCloser interface with another simple
// method Asset, that returns the asset name
type BytesAsset struct {
	Name string
	*bytes.Reader
}

func (b *BytesAsset) Asset() string { return b.Name }
func (b *BytesAsset) Close() error  { return nil } // noop, implement ReadCloser

// Create the Asset and reader
func NewBytesAsset(name string, data []byte) *BytesAsset {
	return &BytesAsset{
		Name:   name,
		Reader: bytes.NewReader(data),
	}
}

// Here is the bulk of the implementation, we input a number of assets
// and output them on an asset stream for decoding. There is no chance
// of error here so we leave errc unbuffered.
func NewBytesAssetStream(images ...*BytesAsset) packer.AssetStreamer {
	return packer.AssetStreamerFunc(func(ctx context.Context) (<-chan packer.Asset, <-chan error) {
		stream := make(chan packer.Asset)
		errc := make(chan error)
		go func() {
			defer close(stream)
			defer close(errc)
			for _, img := range images {
				select {
				case stream <- img:
				case <-ctx.Done():
					break
				}
			}
		}()
		return stream, errc
	})
}

Though that seems like a lot, for the majority of use cases, a custom asset streamer implementation will not be necessary.

Index

• Variables
• func Run(ctx context.Context, params *Params) error
• type Asset
• type AssetStreamer
  • func NewFileStream(inputDirectory string) AssetStreamer
  • func NewFilenameStream(directory string, files ...string) AssetStreamer
• type AssetStreamerFunc
  • func (f AssetStreamerFunc) AssetStream(ctx context.Context) (<-chan Asset, <-chan error)
• type Outputter
  • func NewFileOutputter(outputDirectory string) Outputter
• type OutputterFunc
  • func (f OutputterFunc) GetWriter(filename string) (io.WriteCloser, error)
• type Params

Variables

var (
	// DefaultAtlasName is the default base name for
	// outputted files when no name is provided
	DefaultAtlasName = "atlas"
	// DefaultAtlasWidth is the width used if no width is specified
	DefaultAtlasWidth = 2048
	// DefaultAtlasHeight is the height used if no height is specified
	DefaultAtlasHeight = 2048
)

Functions

func Run

func Run(ctx context.Context, params *Params) error

Run performs the texture packing. It reads files from the given AssetStreamer and outputs the results to the given Outputter returning an error if any critical failures are encountered.

Context is used to immediately cancel any further work on the the texture packing. A context must be supplied.

Params are provided to the Run method to configure the texture packing output. Input, Ouput and Format parameters are required all other parameters are optional. You can use the public 'Default' properties to configure the defaults used when parameters are missing.

Name is the name that will be prepended to the atlas files outputted. Eg. a value of "myatlas" would result in "myatlas-1.png"

Input is used to provide readers for the assets that will be packed. In most cases packer.NewFileStream can be used to read from the local filesystem, but you could write an input that reads from a server, network etc. Input is a required parameter.

Output is used to provide writers for the atlas files to be written. In most cases packer.NewFileOutputter will suffice. Output is a required parameter.

Format should be a target format, used to define the descriptor format of the atlas. The descriptor acompanies the image to indicate where subimages can be found within the atlas. A target format should include a valid template and file extension format, all other settings are optional.

Width and Height configure the maximum size of the atlases outputted. TODO 0 should be interpreted as no maxumum size.

MaxAtlases can be used to limit the number of atlases outputted. A value of 0 is interpreted as no limit.

Types

type Asset

type Asset interface {
	Reader() (io.ReadCloser, error)

	// Asset returns the name of the given asset
	Asset() string
}

Asset represents a single input source into the texture packer. Many assets are supplied and packed together to create a single atlas.

Assets commonly represent files in a filesystem, but could also be blobs in a blobstore or images on a remote server.

type AssetStreamer

type AssetStreamer interface {
	AssetStream(ctx context.Context) (<-chan Asset, <-chan error)
}

AssetStreamer is a factory responsible for piping assets to a channel

func NewFileStream

func NewFileStream(inputDirectory string) AssetStreamer

NewFileStream creates an asset streamer that streams files from a given input directory. The input directory will be walked and readers will be created using the standard os package.

func NewFilenameStream

func NewFilenameStream(directory string, files ...string) AssetStreamer

NewFilenameStream creates an asset streamer that streams the specified files. The files will be read relative to the given directory. Readers will be created using the standard os package.

type AssetStreamerFunc

type AssetStreamerFunc func(ctx context.Context) (<-chan Asset, <-chan error)

AssetStreamerFunc is a function that conforms to the AssetStreamer interface

func (AssetStreamerFunc) AssetStream

func (f AssetStreamerFunc) AssetStream(ctx context.Context) (<-chan Asset, <-chan error)

AssetStream implements the AssetStreamer interface

type Outputter

type Outputter interface {
	GetWriter(filename string) (io.WriteCloser, error)
}

Outputter is a factory responsible for creating writers that atlas files can be written to. In most cases FileOutputter will be used to allow you to easilly write to a system directory but outputters can be used to write to any destination.

func NewFileOutputter

func NewFileOutputter(outputDirectory string) Outputter

NewFileOutputter is most common form of atlas outputter. Specify an empty output directory and it will write all atlas contents to this new directory using the os standard library.

type OutputterFunc

type OutputterFunc func(filename string) (io.WriteCloser, error)

OutputterFunc is a function that conforms to the Outputter interface

func (OutputterFunc) GetWriter

func (f OutputterFunc) GetWriter(filename string) (io.WriteCloser, error)

type Params

type Params struct {
	Name          string
	Input         AssetStreamer
	Output        Outputter
	Format        target.Format
	Width, Height int
	Padding       int
	MaxAtlases    int
}

Params are passed to the packer.Run to configure the texture packing. Input, Output and Format are required, all other options will use sensible defaults if not explicitly provided.