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(), ¶ms))
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 ¶
Examples ¶
Constants ¶
This section is empty.
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 // DefaultNameFormatter DefaultNameFormatter = func(name string, index int) string { return fmt.Sprintf("%s-%d", name, index) } )
Functions ¶
func Run ¶
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.
Example ¶
package main
import (
"context"
"fmt"
"github.com/psucodervn/lovepac/packer"
"github.com/psucodervn/lovepac/target"
)
func main() {
params := packer.Params{
Name: "myatlas",
Format: target.Love,
Input: packer.NewFileStream("./assets"),
Output: packer.NewFileOutputter("./build"),
Width: 512,
Height: 512,
}
if err := packer.Run(context.Background(), ¶ms); err != nil {
fmt.Print("Texture packing complete")
}
}
Output: Texture packing complete
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 ¶
AssetStreamer is a factory responsible for piping assets to a channel
func NewFileGlobStream ¶
func NewFileGlobStream(globPattern string) AssetStreamer
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 ¶
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 NameFormatter ¶
type Outputter ¶
type Outputter interface {
GetWriter(filename string, append bool) (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 ¶
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, append bool) (io.WriteCloser, error)
OutputterFunc is a function that conforms to the Outputter interface
func (OutputterFunc) GetWriter ¶
func (f OutputterFunc) GetWriter(filename string, append bool) (io.WriteCloser, error)
type Params ¶
type Params struct {
Name string
Input AssetStreamer
Output Outputter
Format target.Format
Width, Height int
Padding int
MaxAtlases int
Scale float64
CombineDescFiles bool
NameFormatter NameFormatter
}
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.
Source Files