The patchwork Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The patchwork Reference Manual

This is the patchwork Reference Manual, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Jul 29 16:23:12 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

patchwork

A spritesheet packer for games.

Overview

This simple utility will pack images into a larger spritesheet, suitable for game development. It uses the 'maxrects' algorithm as described here.

Install

(ql:quickload :patchwork)

Usage

Pack Sprites into a Spritesheet

A spritesheet is created from a collection of smaller files. To tell this library which files you would like packed, you can do this one of three ways:

(make-atlas-from-directory "/home/user/sprites"
                           :out-file #p"/tmp/spritesheet.png"
                           :width 1024
                           :height 1024)
(make-atlas-from-directory "/home/user/sprites"
                           :recursive t
                           :out-file #p"/tmp/spritesheet.png"
                           :width 1024
                           :height 1024)

To manually add files, you must construct a file-spec, which is an association list mapping absolute pathnames of files to their unique ID. The unique ID is what will be written to the resulting metadata file. As an example, you can create a list such as:

'((#p"/path/to/file1.png" . "bomb")
  (#p"/path/to/file2.png" . "missile"))

Once you have a file-spec, you can pass it to MAKE-ATLAS as follows:

(make-atlas file-spec
            :out-file #p"/tmp/spritesheet.png"
            :width 1024
            :height 1024)

The above three methods will write an image to disk, as well as a metadata file of the same name with the extension ".spec". The metadata file is a list of property lists, specifying the ID's of the images and their positions and sizes in the spritesheet. An example metadata file looks like the following:

((:ID "ship01" :X 1316 :Y 1060 :W 140 :H 140)
 (:ID "ship02" :X 3770 :Y 1944 :W 268 :H 178)
 (:ID "ship03" :X 3502 :Y 1944 :W 268 :H 185)
 (:ID "ship04" :X 2823 :Y 3089 :W 266 :H 118)
 (:ID "ship05" :X 3234 :Y 2134 :W 268 :H 164)
 (:ID "ship06" :X 1751 :Y 3849 :W 268 :H 198)
 (:ID "ship07" :X 1584 :Y 932 :W 140 :H 88)
 (:ID "ship08" :X 3089 :Y 3129 :W 263 :H 168)
 (:ID "ship09" :X 3868 :Y 2886 :W 192 :H 184)
 (:ID "ship10" :X 3600 :Y 2453 :W 147 :H 136)
 (:ID "ship11" :X 3868 :Y 2598 :W 211 :H 146)
 (:ID "ship12" :X 2823 :Y 3207 :W 260 :H 194)
 (:ID "ship13" :X 1189 :Y 1577 :W 130 :H 128)
 (:ID "ship14" :X 3868 :Y 2744 :W 197 :H 142)
 (:ID "ship15" :X 1436 :Y 2113 :W 183 :H 110)
 (:ID "ship16" :X 3083 :Y 3297 :W 137 :H 137))

For the first two automatic generation methods above, IDs are automatically generated based on the filename without the extension, and the path relative to the root directory starting point. This disambiguates files of the same name located in different directories.

You can also supply the :normalize argument to make-atlas or make-atlas-from-directory to map pixels to the [0..1] domain when writing the resulting metadata file. This is useful for use with OpenGL texture coordinates.

You can optionally supply the :flip-y argument to make-atlas or make-atlas-from-directory to flip the Y axis when writing coordinates to the metadata file. This is useful when using OpenGL which assumes the origin is at the bottom-left.

Lastly, you can also supply the :padding argument to make-atlas or make-atlas-from-directory to specify the amount of padding in pixels separating each sprite in the atlas.

Unpacking Sprites from a Spritesheet

You can perform the reverse operation, and reconstruct the original individual sprite images given a spritesheet's image and metadata files.

(unpack-atlas #p"/tmp/spritesheet.png"
              :out-path #p"/tmp/sprites/"
              :denormalize nil
              :flip-y nil)

This will unpack all the sprites in /tmp/spritesheet.png to the directory /tmp/sprites/, assuming the metadata file /tmp/spritesheet.spec exists.

You can optionally supply :denormalize t if the metadata was created with normalized floats rather than pixel integers.

You can also supply the :flip-y t option if the metadata was written with the Y axis flipped.

License

Copyright © 2017 Michael Fiano.

Licensed under the MIT License.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 patchwork

Maintainer

Michael Fiano <mail@michaelfiano.com>

Author

Michael Fiano <mail@michaelfiano.com>

Home Page

https://www.michaelfiano.com/projects/patchwork

Source Control

(:git "https://github.com/mfiano/patchwork.git")

Bug Tracker

https://github.com/mfiano/patchwork/issues

License

MIT

Description

A spritesheet packer for games.

Dependencies
Source

patchwork.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 patchwork.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/patchwork-20190710-git/patchwork.asd

Systems

patchwork (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 patchwork/package.lisp

Parent

patchwork (system)

Location

package.lisp

Packages

patchwork


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 patchwork/packer.lisp

Dependency

package.lisp (file)

Parent

patchwork (system)

Location

packer.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 patchwork/unpacker.lisp

Dependency

packer.lisp (file)

Parent

patchwork (system)

Location

unpacker.lisp

Exported Definitions

unpack-atlas (function)

Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 patchwork

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: make-atlas FILE-SPEC &key OUT-FILE WIDTH HEIGHT NORMALIZE FLIP-Y PADDING OPTIMIZE-PACK AUTO-SIZE-GRANULARITY-X AUTO-SIZE-GRANULARITY-Y

Pack the sprites defined by FILE-SPEC into a spritesheet.

OUT-FILE: A pathname specifying where to write the image file.

WIDTH: The width in pixels of the spritesheet. :AUTO to calculate width automatically.

HEIGHT: The height in pixels of the spritesheet. :AUTO to calculate height automatically.

NORMALIZE: Boolean specifying whether to map the metadata’s coordinates to the [0..1] range.

FLIP-Y: Boolean specifying whether to flip the Y axis when writing the metadata.

PADDING: The padding in pixels to use around each sprite in the spritesheet.

OPTIMIZE-PACK: Calculate size automatically, and try multiple sizes to find a better size. (ignores WIDTH, HEIGHT if set)

AUTO-SIZE-GRANULARITY-X,
AUTO-SIZE-GRANULARITY-Y: Automatically generated sizes will be multiples of these.

See MAKE-ATLAS-FROM-DIRECTORY if you want to automatically generate FILE-SPEC from the files under a
given filesystem path.

Package

patchwork

Source

packer.lisp (file)

Function: make-atlas-from-directory PATH &key RECURSIVE OUT-FILE WIDTH HEIGHT NORMALIZE FLIP-Y PADDING AUTO-SIZE-GRANULARITY-X AUTO-SIZE-GRANULARITY-Y OPTIMIZE-PACK

Pack the sprites located under the given filesystem path, PATH.

RECURSIVE: Boolean specifying whether to scan recursively for files.

OUT-FILE: A pathname specifying where to write the image file.

WIDTH: The width in pixels of the spritesheet. :AUTO to calculate width automatically.

HEIGHT: The height in pixels of the spritesheet. :AUTO to calculate height automatically.

NORMALIZE: Boolean specifying whether to normalize the metadata’s coordinates in the [0..1] range.

FLIP-Y: Boolean specifying whether to flip the Y axis when writing the metadata.

PADDING: The padding in pixels to use around each sprite in the spritesheet.

OPTIMIZE-PACK: Calculate size automatically, and try multiple sizes to find a better size. (ignores WIDTH, HEIGHT if set)

AUTO-SIZE-GRANULARITY-X,
AUTO-SIZE-GRANULARITY-Y: Automatically generated sizes will be multiples of these.

See MAKE-ATLAS if you want to manually specify a file-spec, in case you want to be in control of the
names chosen to identify the sprites written to the metadata file.

Package

patchwork

Source

packer.lisp (file)

Function: unpack-atlas ATLAS-FILE &key OUT-PATH DENORMALIZE FLIP-Y

Unpack the sprites contained in the image, specified by the filesystem path, ATLAS-FILE. A file of the same name with a "spec" file extension must also exist in the same directory on the filesystem.

OUT-PATH: A pathname specifying a directory to write all the sprite images to.

DENORMALIZE: Boolean specifying whether to convert metadata normalized in the [0..1] range, back into pixel coordinates.

FLIP-Y: Boolean specifying whether to flip the Y axis when reading the metadata.

Package

patchwork

Source

unpacker.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: add-padding RECTS PADDING
Package

patchwork

Source

packer.lisp (file)

Function: collect-files PATH &key RECURSIVE
Package

patchwork

Source

packer.lisp (file)

Function: make-id ROOT FILE
Package

patchwork

Source

packer.lisp (file)

Function: make-rects FILES
Package

patchwork

Source

packer.lisp (file)

Function: make-sprite-path DIRECTORY ID
Package

patchwork

Source

unpacker.lisp (file)

Function: map-files PATH EFFECT &key FILTER RECURSIVE
Package

patchwork

Source

packer.lisp (file)

Function: rect FILE ID X Y W H
Package

patchwork

Source

packer.lisp (file)

Function: remove-padding RECTS PADDING
Package

patchwork

Source

packer.lisp (file)

Function: unpack-sprite ATLAS DATA DENORMALIZE FLIP-Y OUT-PATH
Package

patchwork

Source

unpacker.lisp (file)

Function: write-atlas ATLAS SPRITE RECT
Package

patchwork

Source

packer.lisp (file)

Function: write-metadata DATA OUT-FILE
Package

patchwork

Source

packer.lisp (file)

Function: write-sprite ATLAS RECT OUT-FILE
Package

patchwork

Source

unpacker.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Generic functions

Generic Function: file OBJECT
Package

patchwork

Methods
Method: file (RECT rect)

automatically generated reader method

Source

packer.lisp (file)

Generic Function: make-atlas-coords ATLAS DATA DENORMALIZE FLIP-Y
Package

patchwork

Source

unpacker.lisp (file)

Methods
Method: make-atlas-coords ATLAS DATA (DENORMALIZE (eql t)) FLIP-Y
Method: make-atlas-coords ATLAS DATA DENORMALIZE FLIP-Y
Generic Function: make-coords RECT WIDTH HEIGHT NORMALIZE FLIP-Y
Package

patchwork

Source

packer.lisp (file)

Methods
Method: make-coords RECT WIDTH HEIGHT NORMALIZE FLIP-Y
Method: make-coords RECT WIDTH HEIGHT (NORMALIZE (eql t)) FLIP-Y

Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Classes

Class: rect ()
Package

patchwork

Source

packer.lisp (file)

Direct superclasses

rect (class)

Direct methods
  • rect-initargs (method)
  • file (method)
Direct slots
Slot: file
Initargs

:file

Readers

file (generic function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   P  
Index Entry  Section

F
File, Lisp, patchwork.asd: The patchwork<dot>asd file
File, Lisp, patchwork/package.lisp: The patchwork/package<dot>lisp file
File, Lisp, patchwork/packer.lisp: The patchwork/packer<dot>lisp file
File, Lisp, patchwork/unpacker.lisp: The patchwork/unpacker<dot>lisp file

L
Lisp File, patchwork.asd: The patchwork<dot>asd file
Lisp File, patchwork/package.lisp: The patchwork/package<dot>lisp file
Lisp File, patchwork/packer.lisp: The patchwork/packer<dot>lisp file
Lisp File, patchwork/unpacker.lisp: The patchwork/unpacker<dot>lisp file

P
patchwork.asd: The patchwork<dot>asd file
patchwork/package.lisp: The patchwork/package<dot>lisp file
patchwork/packer.lisp: The patchwork/packer<dot>lisp file
patchwork/unpacker.lisp: The patchwork/unpacker<dot>lisp file

Jump to:   F   L   P  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   F   G   M   R   U   W  
Index Entry  Section

A
add-padding: Internal functions

C
collect-files: Internal functions

F
file: Internal generic functions
file: Internal generic functions
Function, add-padding: Internal functions
Function, collect-files: Internal functions
Function, make-atlas: Exported functions
Function, make-atlas-from-directory: Exported functions
Function, make-id: Internal functions
Function, make-rects: Internal functions
Function, make-sprite-path: Internal functions
Function, map-files: Internal functions
Function, rect: Internal functions
Function, remove-padding: Internal functions
Function, unpack-atlas: Exported functions
Function, unpack-sprite: Internal functions
Function, write-atlas: Internal functions
Function, write-metadata: Internal functions
Function, write-sprite: Internal functions

G
Generic Function, file: Internal generic functions
Generic Function, make-atlas-coords: Internal generic functions
Generic Function, make-coords: Internal generic functions

M
make-atlas: Exported functions
make-atlas-coords: Internal generic functions
make-atlas-coords: Internal generic functions
make-atlas-coords: Internal generic functions
make-atlas-from-directory: Exported functions
make-coords: Internal generic functions
make-coords: Internal generic functions
make-coords: Internal generic functions
make-id: Internal functions
make-rects: Internal functions
make-sprite-path: Internal functions
map-files: Internal functions
Method, file: Internal generic functions
Method, make-atlas-coords: Internal generic functions
Method, make-atlas-coords: Internal generic functions
Method, make-coords: Internal generic functions
Method, make-coords: Internal generic functions

R
rect: Internal functions
remove-padding: Internal functions

U
unpack-atlas: Exported functions
unpack-sprite: Internal functions

W
write-atlas: Internal functions
write-metadata: Internal functions
write-sprite: Internal functions

Jump to:   A   C   F   G   M   R   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   F   S  
Index Entry  Section

F
file: Internal classes

S
Slot, file: Internal classes

Jump to:   F   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   R   S  
Index Entry  Section

C
Class, rect: Internal classes

P
Package, patchwork: The patchwork package
patchwork: The patchwork system
patchwork: The patchwork package

R
rect: Internal classes

S
System, patchwork: The patchwork system

Jump to:   C   P   R   S