textureatlas

A simple, cross-platform tool and C library for creating and using a texture atlas in your application or game. Distributed under the terms of the MIT license.

What is a Texture Atlas?

A Texture Atlas is a texture (raster image) composed of multiple smaller textures. By loading a single large texture, you can reduce resource load time and improve performance by minimizing the number texture bind calls during rendering. A texture atlas is accompanied by a map file that identifies the coordinates and dimensions of each texture in the atlas.

textureatlas.py

textureatlas.py is a Python-based command line tool that can be used to generate a texture atlas and accompanying map file from one or more images. Images can be grouped together as individual frames of the same texture (for animated sequences, for instance). Each texture has a name that is used to identify the texture in the atlas map file.

Map File

The .map file generated by textureatlas.py is a simple binary file intended to be loaded with libtextureatlas from your C or C++ game/application. The format of the map file is documented in the source code.

Supported Image Formats

textureatlas.py uses the Python Imaging Library to handle image manipulation, loading, and saving and hence supports many commonly used image file formats including PNG, BMP, GIF, JPEG, and TGA.

System Requirements

• Python 2.7
• Python Image Library (PIL) or Pillow.

Usage

usage: textureatlas.py [-h] [-o output-file] [-m mode] [-s size]
                       texture [texture ...]

Packs many smaller images into one larger image, a Texture Atlas. A companion
file (.map), is created that defines where each texture is mapped in the atlas.

positional arguments:
  texture               filename of texture

optional arguments:
  -h, --help            show this help message and exit
  -o output-file        output filename (atlas.png)
  -m mode, --mode mode  output file mode (RGBA)
  -s size, --size size  size of atlas (n x n)

Texture Parameter Format

The format of a texture parameter is as follows:

[<name>=]<frame0.png>
[<name>=]"<frame0.png> <frame1.png>"

The <name> of a texture is used to identify the texture in the texture atlas map file. If you omit the <name> of the texture, the filename of the first frame, without the extension, will be used.

Example 1

textureatlas.py crate=texture1.png texture2.png

This example generate an atlas containing two textures, each of one frame, with names 'crate' and 'texture2', respectively.

You may specify additional frames of a texture (e.g. for animated sequences) by enclosing the filenames of the frames in quotes.

Example 2

textureatlas.py "texture_frame0.png texture_frame1.png" texture2.png

This example generate an atlas containing two textures. The first texture, named 'texture_frame0', contains two frames. The second texture, named 'texture2', contains only a single frame.

Example 3

textureatlas.py apple=picture_of_an_apple.png fire="fire0.png fire1.png"

This example generate an atlas containing two textures. The first texture, named 'apple', contains only a single frame. The second texture, named 'fire', contains two frames.

Using command-line tools, you can easily specify multiple frames for a texture from a directory listing.

Example 4

textureatlas.py fire="`ls sample/fire/*.png | xargs`"

This example list all the .png files in the sample/fire directory as frames for the 'fire' texture.

libtextureatlas

libtextureatlas is a small C library with a simple API for loading and accessing a binary texture atlas map file created by textureatlas.py. It has no dependencies on other libraries and can be easily integrated with your existing project, especially if you are using CMake.

Please note that libtextureatlas will not load the image data of the texture, just the map file. There exist several good libraries for loading images; for loading and decompressing PNG images, you may be interested in LodePNG.

Example Usage

Loading a Texture Atlas Map File

texture_atlas_t *ta;
int result;

result = texture_atlas_load("atlas.map", &ta);
if (result) return 1;

Looking Up a Texture by Name

texture_atlas_texture_t *texture;

texture = texture_atlas_lookup(ta, "blaster");
if (texture == NULL)
{
    free(ta);
    return 1;
}

Stepping Through Texture Frames

texture_atlas_texture_t *texture;
texture_atlas_frame_t *frame;
unsigned int i;

for (i=0; i < texture->num_frames; i++)
{
    frame = texture->frames + i;
    printf("Frame %d is at %d, %d.\n", i, frame->x, frame->y);
}

License

Licensed under the terms of the MIT license:

The MIT License (MIT)

Copyright (c) 2014 Matthew Borgerson

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.

Resources

• nVidia Whitepaper on batching using texture atlases.