The net.mfiano.lisp.patchwork Reference Manual

Table of Contents

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

The net.mfiano.lisp.patchwork Reference Manual

This is the net.mfiano.lisp.patchwork Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 11:55:40 2020 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 :net.mfiano.lisp.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/")

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

License

Copyright © 2017-2020 Michael Fiano mail@mfiano.net.

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 net.mfiano.lisp.patchwork

Author

Michael Fiano <mail@mfiano.net>

Home Page

https://mfiano.net/projects/patchwork

Source Control

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

Bug Tracker

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

License

MIT

Description

A spritesheet packer for games.

Dependencies
Source

net.mfiano.lisp.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 net.mfiano.lisp.patchwork.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/patchwork-20200610-git/net.mfiano.lisp.patchwork.asd

Systems

net.mfiano.lisp.patchwork (system)


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

3.1.2 net.mfiano.lisp.patchwork/package.lisp

Parent

net.mfiano.lisp.patchwork (system)

Location

package.lisp

Packages

net.mfiano.lisp.patchwork


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

3.1.3 net.mfiano.lisp.patchwork/packer.lisp

Dependency

package.lisp (file)

Parent

net.mfiano.lisp.patchwork (system)

Location

packer.lisp

Exported Definitions
Internal Definitions

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

3.1.4 net.mfiano.lisp.patchwork/unpacker.lisp

Dependency

packer.lisp (file)

Parent

net.mfiano.lisp.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 net.mfiano.lisp.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

net.mfiano.lisp.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

net.mfiano.lisp.patchwork

Source

packer.lisp (file)

Function: unpack-atlas ATLAS-FILE &key OUT-PATH

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.

Package

net.mfiano.lisp.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

net.mfiano.lisp.patchwork

Source

packer.lisp (file)

Function: collect-files PATH &key RECURSIVE
Package

net.mfiano.lisp.patchwork

Source

packer.lisp (file)

Function: make-atlas-coords ATLAS DATA
Package

net.mfiano.lisp.patchwork

Source

unpacker.lisp (file)

Function: make-id ROOT FILE
Package

net.mfiano.lisp.patchwork

Source

packer.lisp (file)

Function: make-rects FILES
Package

net.mfiano.lisp.patchwork

Source

packer.lisp (file)

Function: make-sprite-path DIRECTORY ID
Package

net.mfiano.lisp.patchwork

Source

unpacker.lisp (file)

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

net.mfiano.lisp.patchwork

Source

packer.lisp (file)

Function: rect FILE ID X Y W H
Package

net.mfiano.lisp.patchwork

Source

packer.lisp (file)

Function: remove-padding RECTS PADDING
Package

net.mfiano.lisp.patchwork

Source

packer.lisp (file)

Function: unpack-sprite ATLAS DATA OUT-PATH
Package

net.mfiano.lisp.patchwork

Source

unpacker.lisp (file)

Function: write-atlas ATLAS SPRITE RECT
Package

net.mfiano.lisp.patchwork

Source

packer.lisp (file)

Function: write-metadata DATA OUT-FILE
Package

net.mfiano.lisp.patchwork

Source

packer.lisp (file)

Function: write-sprite ATLAS RECT OUT-FILE
Package

net.mfiano.lisp.patchwork

Source

unpacker.lisp (file)


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

5.2.2 Generic functions

Generic Function: %make-atlas-coords ATLAS DATA NORMALIZED
Package

net.mfiano.lisp.patchwork

Source

unpacker.lisp (file)

Methods
Method: %make-atlas-coords ATLAS DATA NORMALIZED
Method: %make-atlas-coords ATLAS DATA (NORMALIZED (eql t))
Generic Function: file OBJECT
Package

net.mfiano.lisp.patchwork

Methods
Method: file (RECT rect)

automatically generated reader method

Source

packer.lisp (file)

Generic Function: make-coords RECT WIDTH HEIGHT NORMALIZE FLIP-Y
Package

net.mfiano.lisp.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

net.mfiano.lisp.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   N  
Index Entry  Section

F
File, Lisp, net.mfiano.lisp.patchwork.asd: The net․mfiano․lisp․patchwork․asd file
File, Lisp, net.mfiano.lisp.patchwork/package.lisp: The net․mfiano․lisp․patchwork/package․lisp file
File, Lisp, net.mfiano.lisp.patchwork/packer.lisp: The net․mfiano․lisp․patchwork/packer․lisp file
File, Lisp, net.mfiano.lisp.patchwork/unpacker.lisp: The net․mfiano․lisp․patchwork/unpacker․lisp file

L
Lisp File, net.mfiano.lisp.patchwork.asd: The net․mfiano․lisp․patchwork․asd file
Lisp File, net.mfiano.lisp.patchwork/package.lisp: The net․mfiano․lisp․patchwork/package․lisp file
Lisp File, net.mfiano.lisp.patchwork/packer.lisp: The net․mfiano․lisp․patchwork/packer․lisp file
Lisp File, net.mfiano.lisp.patchwork/unpacker.lisp: The net․mfiano․lisp․patchwork/unpacker․lisp file

N
net.mfiano.lisp.patchwork.asd: The net․mfiano․lisp․patchwork․asd file
net.mfiano.lisp.patchwork/package.lisp: The net․mfiano․lisp․patchwork/package․lisp file
net.mfiano.lisp.patchwork/packer.lisp: The net․mfiano․lisp․patchwork/packer․lisp file
net.mfiano.lisp.patchwork/unpacker.lisp: The net․mfiano․lisp․patchwork/unpacker․lisp file

Jump to:   F   L   N  

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

A.2 Functions

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

%
%make-atlas-coords: Internal generic functions
%make-atlas-coords: Internal generic functions
%make-atlas-coords: Internal generic functions

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-coords: Internal 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, %make-atlas-coords: Internal generic functions
Generic Function, file: Internal generic functions
Generic Function, make-coords: Internal generic functions

M
make-atlas: Exported functions
make-atlas-coords: Internal 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, %make-atlas-coords: Internal generic functions
Method, %make-atlas-coords: Internal generic functions
Method, file: 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   N   P   R   S  
Index Entry  Section

C
Class, rect: Internal classes

N
net.mfiano.lisp.patchwork: The net․mfiano․lisp․patchwork system
net.mfiano.lisp.patchwork: The net․mfiano․lisp․patchwork package

P
Package, net.mfiano.lisp.patchwork: The net․mfiano․lisp․patchwork package

R
rect: Internal classes

S
System, net.mfiano.lisp.patchwork: The net․mfiano․lisp․patchwork system

Jump to:   C   N   P   R   S