Although it’s far from perfect, we have decided to make the tool (along with its source code) available to the public in the hope that, if you find it useful, you might also want to contribute to help improve it.

Click here for download links and more information.

This is a texture atlas tool we created during the development of Prisoner 84. It allowed us to quickly and efficiently produce texture atlases for the 40+ levels that appeared in the game. We have decided to release it to the public for anybody out there who might be looking for a texture atlas solution for their project. It is on the fussy side, however, so we have also made the source code available in the hope that, if you find it useful, you might also wish to contribute by helping to improve it.

Downloads

mayaTextureAtlas.zip 1.0 (109.01 kB) - This zip contains the final release version of the TextureAtlas tool, which can be installed for Maya 2012 x64.

mayaTextureAtlas-src.zip 1.0 (19.83 MB) - This zip contains the complete source code for the TextureAtlas tool.

Prerequisites

Before doing anything you should first make sure you have the following redistributions installed on your system:-

Visual Studio x64 re-distributable
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=bd512d9e-43c8-4655-81bf-9350143d5867

DirectX dlls
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=3b170b25-abab-4bc3-ae91-50ceb6d8fa8d

Please note this plug-in is currently built ONLY for the 64-bit Windows version of Maya 2012. Hopefully in the future – or through community help – we can get this cross-platform, the way it should be!

Installation

1. Copy “hg_TextureAtlas2012x64.mll” into your Maya “plug-ins” folder. This can be in either your “C:\Users\*YOURUSERNAME*\Documents\Maya\plug-ins” folder, or in “C:\Program Files\Autodesk\Maya2012\bin\plug-ins” (or wherever your copy of Maya 2012 is installed).

2. Copy “nvatlas.exe” into your Maya “bin” folder. This is usually in “C:\Program Files\Autodesk\Maya2012\bin” (or wherever your copy of Maya 2012 is installed).

3. Open up Maya and go to “Window > Settings/Preferences > Plug-in Manager”. Provided steps 1 and 2 were completed without error, “hg_TextureAtlas2012x64.mll” will now appear in your list of available
plug-ins. Tick the box next to “Loaded” to enable it (and optionally tick the “Auto load” box so that the plug-in is automatically loaded each time you open Maya).

How it works

Our TextureAtlas tool has two methods of atlasing: “Standard Atlas” and “Prebake Atlas”.

The standard method atlases by texture; so if your scene contains 10 separate textures then those 10 textures will be added to your atlas regardless of how many times they are used in the scene, and regardless of how many meshes there are in the scene (meshes that share textures are each allocated the same UV offsets within the atlas). This method is perfect when your artwork is going to be lit in real-time and doesn’t require pre-baked lighting of any kind.

An example of a standard texture atlas from Prisoner 84…

The prebake method atlases by mesh rather than by texture. For example, if you have a single texture applied to 10 separate meshes in your scene, 10 instances of that texture (along with the corresponding UV offsets of each of those meshes) will be created inside the atlas. This means all 10 textures can be pre-lit (or altered in some other way) within the texture atlas itself.

An example of a prebake texture atlas from Prisoner 84…

Commands / How to use it

The TextureAtlas tool is run via Maya’s command line–although we recommend that you save each command to your shelf. Commands are as follows:-

“TextureAtlas”
Creates a standard texture atlas of selected meshes only

“TextureAtlas -all”
Creates a standard texture atlas of all meshes in the scene

“TextureAtlas -prebake”
Creates a prebake texture atlas of selected meshes only

“TextureAtlas -prebake -all”
Creates a prebake texture atlas of all meshes in the scene

I’ve run it, but what now?

Once the texture atlasing process has completed successfully, you will find the following files in your project’s “textures” folder:-

atlasTexList.txt
This is a list of all textures that have been added to your atlas (together with their absolute paths).

level-atlas.tai
This is the Texture Atlas Index file; it lists all textures together with their new UV offsets within the atlas itself.

level-atlas0.tga, level-atlas1.tga, and so on
These are your new texture atlas files. They are automatically assigned to your existing materials in Maya. It is recommended, however, that you move these to a different folder and create a new material in your scene to assign them to. This will avoid overwriting existing texture atlas data if you run the TextureAtlas tool again in the same Maya project.

Known Issues, Limitations and Workarounds

This tool is still very much a work in progress, so there are a few issues. However, most of these issues are avoidable if you follow the steps outlined in this section.

1. TEXTURES/UVS OVERLAP

Sometimes multiple texture UVs are allocated coordinates which cause them to overlap with one another inside the texture atlas.

This issue is usually caused by one of two things: 1) when rectangular textures–particularly those with a significant difference between width and height (i.e. 16×256)–are allocated atlas space near to a square texture, or 2) when the atlas tool is attempting to use up “odd space” caused by inconsistent texture sizes, non-power of two textures, or poorly grouped texture UVs.

Workarounds…

The order in which a mesh is atlased is determined by its position in the scene hierarchy–a mesh that comes first in the scene will be dealt with first by the atlasing tool and will be placed in the top left corner of the file. To edit the scene hierarchy, open Maya’s outliner (“Window > Outliner”) and make sure “Display > Sort Order” is set to “Scene Hierarchy”. Now re-order your meshes in the outliner so that they are grouped by their texture sizes: meshes which have larger textures should appear first in the scene (when the texture atlas has more space to work with) and meshes which have smaller textures should appear last (when the texture atlas has less space available).

2) MATERIALS SEEM BROKEN WHEN MULTIPLE TEXTURE ATLASES ARE CREATED

When more than one texture atlas is created, Maya will automatically assign the last atlas file created to all of your existing materials. To avoid this we recommend limiting atlas usage to one per scene/level. It is, however, possible to manually re-assign separate texture atlas materials to the relevant meshes.

3) MESHES CAN ONLY HAVE ONE TEXTURE ASSIGNED (PREBAKE METHOD ONLY)

When using the prebake method, make sure multiple textures aren’t assigned to a single mesh, otherwise the atlas will get stuck in a loop. Individual meshes can only have one texture assigned to them.

4) A TIP TO SAVE SPACE (PREBAKE METHOD ONLY)

If you want to save space in your texture atlas, you can combine meshes that share a single texture and only one texture will be added to the atlas.

This is useful if you know two meshes that share the same texture are going to be lit in the same way (e.g. a symmetrical corridor), or if an object or tile appears in a level multiple times but doesn’t require a unique instance of its assigned texture (e.g. a door sign used throughout the level that doesn’t require lighting to ensure it is always legible).

Code

What you’ll need…

• Visual Studio 2010 (any version should do-–even Express)
• Maya 64 bit headers and libraries (the headers and libraries are part of a Maya install)

To compile the code you will need a version of Visual Studio 2010 with 64 bit compilation tools and the 64 bit versions of the Maya libraries. It is possible to build the 32 bit versions of everything if you wanted to, you just need to add the new target and make sure to link against the Maya 32 bit libraries.

You will have to set up the header and library paths for your Maya install into the project settings (you can just replace the defaults I’ve left in the project).

That’s pretty much all there is to change to get it compiling so long as the folder structure stays as it was in the zip file. The final mll files go into the ‘mll’ folder and should be copied to your document Maya path as you do each build, or you can tell visual studio to just place it there by default (be aware you can’t have the plug-in running in Maya when you compile this way as the file will be locked).

NVidia Texture Tool

The original code can be picked up here…
http://developer.nvidia.com/legacy-texture-tools

What you’ll need…

• DirectX SDK http://www.microsoft.com/downloads/en/details.aspx?displaylang=en&FamilyID=3021d52b-514e-41d3-ad02-438a3ba730ba

To compile the version supplied in the zip, you just need the latest DirectX SDK (I used the June 2010 as of writing). Again you need to make sure the headers and libraries are set up for the project to see them.

Changes to the original code…

The options in the nvatlas tool should really go into some sort of dialogue in Maya so you can pick and choose what you want. There are some parts of the code that are slightly broken by my changes. For example the important part of placing the textures into an atlas is not quite as precise as it used to be because I stopped it ordering textures by size.

Future plans

The codebase could do with a thorough clean-up; as is always the case it was created quickly for a specific purpose, and it never really went through a proper design phase, nor was it tested properly.

Below are a few things I believe should be done to get this tool nearer to what it should be in terms of functionality:-

• The plug-in should not be reliant on the nVidia tool as this is preventing the tool from being cross-platform. It is also an inefficient way to implement such a tool. Using the rectangle bin packing code here http://clb.demon.fi/projects/rectangle-bin-packing is a very viable alternate which we are considering.
• An “Undo” feature that fully supports Maya’s command history, so that an atlas can be generated at any time to check progress.
• Better texture support (resolutions, bit types, formats, etc.)
• Add a dialogue-based interface that can be used to customise atlas output as well as provide a convenient place to implement future additions to the available options.
• More flexibility with Maya’s HyperShade system (i.e. it shouldn’t matter how everything was originally mapped and what materials were used)

Disclaimer

This tool is released as is. Please use at your own risk!

Texture Atlasing is a concept whereby you place multiple textures into a single bigger texture or textures so that you drastically reduce your texture binding and swaps during the rendering of a complex scene.

Atlasing has existed for a while and has been used on many older games as a primary technique — the Quake games for example started using atlasing for a level’s lightmap information. We have recently been looking into this technique because we have increased our texture usage, plus atlasing has a lot of benefits on devices such as the iPhone where texture bandwidth is limited.

Usage

Previously we had been using a limited form of a texture atlas for our UI elements in our games. Here is an example of the atlas for the Air Cadets UI artwork.

As you can see we used a 1024×1024 texture which contains every button, character and element seen throughout the games’ menus and HUD. This atlas was created manually and we had to store image positions and dimensions in a spreadsheet which then was used to create the correct UV coordinates for the in game buttons/images. Although it worked, it was terribly slow for both of us and meant changes to the menu artwork caused many headaches!

For the current project we need to take advantage of atlasing for the main level scenes because our texture usage has drastically increased. After some research, I found that nVidia had released a command line driven tool back in 2004 that had various features to create an atlas automatically and output a useful text-based file (.TAI Texture Atlas Information file) that listed the original texture, its new atlas file and the UV offsets of the position in the atlas (see links at the bottom of this page).

After a few tests and most importantly having the source code to the tool, it looked like the perfect option to get this working within our pipeline with a few changes to help us make sure everything would work on the final iPod/iPhone hardware.

The route I chose was to create a new maya ‘command’ plug-in that would externally call the command line tool with the scene textures, read the created TAI file, then use the new offsets to update all the UV coordinates for the scene. After some testing and custom changes to the nVidia tool, we can now generate atlases efficiently and have all our geometry updated in maya referencing the atlas with the correct texture coordinates.

This now has multiple uses across everything we do as we can decide to place multiple similar objects into an atlas or keep them separate. For example, if we have a scene that contains various prefab objects like tables, chairs, cups or other general incidental items (and we know that these items are going to have a high probability of always being drawn together even if they are separate models) we can simply put all their textures into the same atlas thus cutting down multiple texture swaps when the renderer is drawing these objects.

Once we iron out the few remaining bugs – and once we have got all of its features documented – we hope to release the maya tool at some point in the not-too-distant future.

The Pros and Cons of Atlasing

I’ve been quite positive about atlasing so far, however I should probably make a rundown of all the pros and cons so you can judge for yourself if this would be useful to projects you might be working on or if you are just researching the technique.

Pros

Texture batching / Speed
Mentioned throughout this post, this is pretty much your main benefit. It is not guaranteed to give you a speed up, but with good render ordering it most likely will. For iPhone if you make your atlas a PVR texture as well, you will see much better bandwidth usage.

No power of two limitation within the atlas
With an atlas you get the benefit of placing non-power of two textures into a large power of two atlas – thus allowing much greater freedom creating odd texture shapes and UV setups.

Multiple use – UI elements, UV Animations
You can use the atlas in various forms as mentioned earlier: Air Cadets placed all UI elements into an atlas; you could also (for example) have a waterfall texture animation in your game that uses separate textures for each frame — if you place all the animation frames into an atlas all you have to do is perform UV coordinate shifts on a single atlas.

Image assets easier to manage
Having all your texture information in a single big texture can make life a little simpler for art changes as everything is there in a single image resource for tweaks throughout development.

Cons

Mipmapping and Filtering
Since all your textures are tightly packed, if your UVs are right on the edge of an image within the atlas and you want some sort of mipmap filtering on the atlas to smooth out pixelation, then when the image is mipmapped and using as an example, bilinear filtering — since it uses nearest neighbour you’ll potentially get pixels bleeding from unrelated textures which will look jarring in the final render. A solution to this can be to shift your UVs away from the exact edge of the image or make the image bigger itself inside the atlas with extra pixels so there is a safety border between two images.

Limited texture wrapping / Texture tricks (rotate/scale) will not work
Since your UVs are all referencing the same texture, you are pretty much limited to the (GL_)REPEAT texture wrapping mode. It also means if you were using various texture matrix tricks to increase the repetition or to rotate/scale a texture image you become incredibly limited to small changes, otherwise you will see the surrounding images in the atlas.

Moving/changing images within the atlas can be restrictive
The main point of creating an atlas is to pack as many images into a single texture as possible. Problems may arise when you decide that you want to remove an image from the atlas, which leaves a large wasteful hole that you don’t want. Simply moving the other images about in an image editor is no good as this breaks your UV values for the images that you move. I’d always recommend doing atlasing at a late stage in level creation so you can make more of a correct judgement on what images should be atlased on what objects.

Round up

I know this post is a bit text heavy, but I hope it provides some information to those looking into this technique. We’ve found this system to very beneficial in our current game as it allows us to push the uniqueness of an environment by using more textures than we could have previously. As mentioned, we hope to release our which you might find useful, so watch this space. As ever comments, corrections or any other information is always welcome.

Links

 nVidia Texture Atlas Tools – Tools and source.
Algorithm plus another usage example – Good example.