The gamebox-sprite-packer Reference Manual

Table of Contents

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

The gamebox-sprite-packer Reference Manual

This is the gamebox-sprite-packer Reference Manual, version 1.0.5, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 14:39:16 2018 GMT+0.


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

1 Introduction

gamebox-sprite-packer

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 :gamebox-sprite-packer)

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 michael.fiano@gmail.com.

Licensed under the MIT License.

A copy of the license is available here.


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 gamebox-sprite-packer

Maintainer

Michael Fiano <michael.fiano@gmail.com>

Author

Michael Fiano <michael.fiano@gmail.com>

Home Page

https://github.com/mfiano/gamebox-sprite-packer

Source Control

(:git "https://github.com/mfiano/sprite-packer.git")

Bug Tracker

https://github.com/mfiano/gamebox-sprite-packer/issues

License

MIT

Description

A spritesheet packer for games.

Long Description

# gamebox-sprite-packer

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](http://clb.demon.fi/files/RectangleBinPack.pdf).

## Install

“‘ lisp
(ql:quickload :gamebox-sprite-packer)
“‘

## 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:

- Automatically scan for files in the current directory, and add them to a spritesheet:

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

- Automatically scan for files in the current directory recursively, and add them to a spritesheet:

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

- Manually specify the files to be added to a spritesheet:

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:

“‘ lisp
’((#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:

“‘ lisp
(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:

“‘ lisp
((: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.

“‘lisp
(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 <michael.fiano@gmail.com>.

Licensed under the MIT License.

A copy of the license is available [here](LICENSE).

Version

1.0.5

Dependencies
Source

gamebox-sprite-packer.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 gamebox-sprite-packer.asd

Location

/home/quickbuilder/quicklisp/dists/quicklisp/software/gamebox-sprite-packer-20171019-git/gamebox-sprite-packer.asd

Systems

gamebox-sprite-packer (system)


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

3.1.2 gamebox-sprite-packer/package.lisp

Parent

gamebox-sprite-packer (system)

Location

package.lisp

Packages

gamebox-sprite-packer


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

3.1.3 gamebox-sprite-packer/packer.lisp

Dependency

package.lisp (file)

Parent

gamebox-sprite-packer (system)

Location

packer.lisp

Exported Definitions
Internal Definitions

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

3.1.4 gamebox-sprite-packer/unpacker.lisp

Dependency

packer.lisp (file)

Parent

gamebox-sprite-packer (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 gamebox-sprite-packer

Source

package.lisp (file)

Nickname

box.packer

Use List
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-SPECS &key OUT-FILE WIDTH HEIGHT NORMALIZE FLIP-Y PADDING
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: make-atlas-from-directory PATH &key RECURSIVE OUT-FILE WIDTH HEIGHT NORMALIZE FLIP-Y PADDING
Package

gamebox-sprite-packer

Source

packer.lisp (file)

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

gamebox-sprite-packer

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

gamebox-sprite-packer

Source

packer.lisp (file)

Function: collect-files PATH &key RECURSIVE
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: containsp OUTER INNER
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: delta-weight WIDTH HEIGHT RECT
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: find-free-rect WIDTH HEIGHT RECTS
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: intersectsp RECT1 RECT2
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: make-id ROOT FILE
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: make-rects FILES
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: make-sprite-path DIRECTORY ID
Package

gamebox-sprite-packer

Source

unpacker.lisp (file)

Function: normalize-free-space RECTS
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: pack-rects RECTS WIDTH HEIGHT
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: place-rect RECT FREE-RECTS
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: rect FILE ID X Y W H
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: remove-padding RECTS PADDING
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: resolve-free-rects RECT FREE-RECTS
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: sort-rects RECTS
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: subdivide-rect RECT PLACED
Package

gamebox-sprite-packer

Source

packer.lisp (file)

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

gamebox-sprite-packer

Source

unpacker.lisp (file)

Function: write-atlas ATLAS SPRITE RECT
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: write-metadata DATA OUT-FILE
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Function: write-sprite ATLAS RECT OUT-FILE
Package

gamebox-sprite-packer

Source

unpacker.lisp (file)


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

5.2.2 Generic functions

Generic Function: file OBJECT
Package

gamebox-sprite-packer

Methods
Method: file (RECT rect)

automatically generated reader method

Source

packer.lisp (file)

Generic Function: h OBJECT
Package

gamebox-sprite-packer

Methods
Method: h (RECT rect)

automatically generated reader method

Source

packer.lisp (file)

Generic Function: id OBJECT
Package

gamebox-sprite-packer

Methods
Method: id (RECT rect)

automatically generated reader method

Source

packer.lisp (file)

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

gamebox-sprite-packer

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

gamebox-sprite-packer

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
Generic Function: w OBJECT
Package

gamebox-sprite-packer

Methods
Method: w (RECT rect)

automatically generated reader method

Source

packer.lisp (file)

Generic Function: x OBJECT
Package

gamebox-sprite-packer

Methods
Method: x (RECT rect)

automatically generated reader method

Source

packer.lisp (file)

Generic Function: y OBJECT
Package

gamebox-sprite-packer

Methods
Method: y (RECT rect)

automatically generated reader method

Source

packer.lisp (file)


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

5.2.3 Classes

Class: rect ()
Package

gamebox-sprite-packer

Source

packer.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
  • h (method)
  • w (method)
  • y (method)
  • x (method)
  • id (method)
  • file (method)
Direct slots
Slot: file
Initargs

:file

Readers

file (generic function)

Slot: id
Initargs

:id

Readers

id (generic function)

Slot: x
Initargs

:x

Readers

x (generic function)

Slot: y
Initargs

:y

Readers

y (generic function)

Slot: w
Initargs

:w

Readers

w (generic function)

Slot: h
Initargs

:h

Readers

h (generic function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   G   L  
Index Entry  Section

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

G
gamebox-sprite-packer.asd: The gamebox-sprite-packer<dot>asd file
gamebox-sprite-packer/package.lisp: The gamebox-sprite-packer/package<dot>lisp file
gamebox-sprite-packer/packer.lisp: The gamebox-sprite-packer/packer<dot>lisp file
gamebox-sprite-packer/unpacker.lisp: The gamebox-sprite-packer/unpacker<dot>lisp file

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

Jump to:   F   G   L  

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

A.2 Functions

Jump to:   A   C   D   F   G   H   I   M   N   P   R   S   U   W   X   Y  
Index Entry  Section

A
add-padding: Internal functions

C
collect-files: Internal functions
containsp: Internal functions

D
delta-weight: Internal functions

F
file: Internal generic functions
file: Internal generic functions
find-free-rect: Internal functions
Function, add-padding: Internal functions
Function, collect-files: Internal functions
Function, containsp: Internal functions
Function, delta-weight: Internal functions
Function, find-free-rect: Internal functions
Function, intersectsp: 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, normalize-free-space: Internal functions
Function, pack-rects: Internal functions
Function, place-rect: Internal functions
Function, rect: Internal functions
Function, remove-padding: Internal functions
Function, resolve-free-rects: Internal functions
Function, sort-rects: Internal functions
Function, subdivide-rect: 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, h: Internal generic functions
Generic Function, id: Internal generic functions
Generic Function, make-atlas-coords: Internal generic functions
Generic Function, make-coords: Internal generic functions
Generic Function, w: Internal generic functions
Generic Function, x: Internal generic functions
Generic Function, y: Internal generic functions

H
h: Internal generic functions
h: Internal generic functions

I
id: Internal generic functions
id: Internal generic functions
intersectsp: Internal 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
Method, file: Internal generic functions
Method, h: Internal generic functions
Method, id: 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
Method, w: Internal generic functions
Method, x: Internal generic functions
Method, y: Internal generic functions

N
normalize-free-space: Internal functions

P
pack-rects: Internal functions
place-rect: Internal functions

R
rect: Internal functions
remove-padding: Internal functions
resolve-free-rects: Internal functions

S
sort-rects: Internal functions
subdivide-rect: Internal functions

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

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

X
x: Internal generic functions
x: Internal generic functions

Y
y: Internal generic functions
y: Internal generic functions

Jump to:   A   C   D   F   G   H   I   M   N   P   R   S   U   W   X   Y  

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

A.3 Variables

Jump to:   F   H   I   S   W   X   Y  
Index Entry  Section

F
file: Internal classes

H
h: Internal classes

I
id: Internal classes

S
Slot, file: Internal classes
Slot, h: Internal classes
Slot, id: Internal classes
Slot, w: Internal classes
Slot, x: Internal classes
Slot, y: Internal classes

W
w: Internal classes

X
x: Internal classes

Y
y: Internal classes

Jump to:   F   H   I   S   W   X   Y  

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

A.4 Data types

Jump to:   C   G   P   R   S  
Index Entry  Section

C
Class, rect: Internal classes

G
gamebox-sprite-packer: The gamebox-sprite-packer system
gamebox-sprite-packer: The gamebox-sprite-packer package

P
Package, gamebox-sprite-packer: The gamebox-sprite-packer package

R
rect: Internal classes

S
System, gamebox-sprite-packer: The gamebox-sprite-packer system

Jump to:   C   G   P   R   S