Introduction

ATF is a new format from Adobe that allows us to use optimally compressed textures format on the GPU. This allows better performance and quality across different desktop & mobile platforms. Using them with Away3D is extremely easy and recommended. Here’s how.

Creating and managing ATF files

Thibault Imbert made an excellent post on what ATF is and how to use Adobe’s ATF tool. We will continue the overview to reveal further best practices to consider when working with these tools, and how to apply the results in Away3D. This tutorial is written from the OSX perspective, however the approach and tools work pretty much same way on other OS’s.

The main tool we’ll be using is the png2atf command line tool. This will allow us to turn our PNG files into ATF files in a single step. To make things easier for future quality tweaking, we’ll make a batch file. Creating a batch file in OSX is a very easy task:

1. Create a text file and rename it lets say batch_basic_shading and save to same folder with aft tools (atftools/mac/)
2. To give it a proper permissions open terminal, navigate to that folder and type “chmod 755 batch_basic_shading”
3. Edit the file and type your commands in as written below.

./png2atf -c d -r -q 0 -f 0 -i YOUR_PROJECT_PATH/asset/ball/beachball_diffuse.png -o YOUR_PROJECT_PATH/asset/ball/beachball_diffuse.atf
./png2atf -c d -r -q 0 -f 0 -i YOUR_PROJECT_PATH/asset/ball/beachball_specular.png -o YOUR_PROJECT_PATH/asset/ball/beachball_specular.atf

./png2atf -c d -r -q 0 -f 0 -i YOUR_PROJECT_PATH/asset/cube/trinket_diffuse.png -o YOUR_PROJECT_PATH/asset/cube/trinket_diffuse.atf
./png2atf -c d -r -q 0 -f 0 -i YOUR_PROJECT_PATH/asset/cube/trinket_normal.png -o YOUR_PROJECT_PATH/asset/cube/trinket_normal.atf
./png2atf -c d -r -q 0 -f 0 -i YOUR_PROJECT_PATH/asset/cube/trinket_specular.png -o YOUR_PROJECT_PATH/asset/cube/trinket_specular.atf

./png2atf -c d -r -q 0 -f 0 -i YOUR_PROJECT_PATH/asset/floor/floor_diffuse.png -o YOUR_PROJECT_PATH/asset/floor/floor_diffuse.atf
./png2atf -c d -r -q 0 -f 0 -i YOUR_PROJECT_PATH/asset/floor/floor_normal.png -o YOUR_PROJECT_PATH/asset/floor/floor_normal.atf
./png2atf -c d -r -q 0 -f 0 -i YOUR_PROJECT_PATH/asset/floor/floor_specular.png -o YOUR_PROJECT_PATH/asset/floor/floor_specular.atf

./png2atf -c d -r -q 0 -f 0 -i YOUR_PROJECT_PATH/asset/torus/weave_diffuse.png -o YOUR_PROJECT_PATH/asset/torus/weave_diffuse.atf
./png2atf -c d -r -q 0 -f 0 -i YOUR_PROJECT_PATH/asset/torus/weave_normal.png -o YOUR_PROJECT_PATH/asset/torus/weave_normal.atf

It’s good practice to write all these lines since you’ll probably end up editing quality settings many times for individual textures. So what about those cryptic letters?

-c d -r (creates a block based compression texture. d means it’ll be dxt1/dxt5 and works only on windows and osx. If we take this ‘d’ flag out texture will work on every platform)
-q and -f are for quality adjustment. Basically higher the number more compression.

The ATF tools package also contains an application called atfinfo. It’s a great tool to see inspect the internals of what you just created.

./atfinfo -i YOUR_PROJECT_PATH/asset/cube/trinket_diffuse.atf

will return

File Name       : YOUR_PROJECT_PATH/asset/cube/trinket_diffuse.atf
ATF File Type     : Compressed (DXT1)
Size           : 512x512
Cube Map       : no
Embeded Levels   : XXXXXXXXXX (512x512,256x256,128x128,64x64,32x32,16x16,8x8,4x4,2x21x1)
AS3 Texture Class : Texture (flash.display3D.Texture)
AS3 Texture Format : Context3DTextureFormat.COMPRESSED (flash.display3D.Context3DTextureFormat)

As you can see it pull out DXT1 Compressed, size 512x512 file and it contains all the mipmap levels.

In our case, we want to make a CubeTexture for use in the Away3D SkyBox primitive. With the tool, you’ll need to do the following.

1. Rename your cubemap texture images in numerical order eg -X: hourglass0.png, +X: hourglass1.png, -Y: hourglass2.png, +Y: hourglass3.png, -Z: hourglass4.png, +Z: hourglass5.png
2. add new flag -m

./png2atf -c d -r -q 0 -f 0 -m -i YOUR_PROJECT_PATH/sky/cubetexture/hourglass0.png -o YOUR_PROJECT_PATH/sky/cubetexture/hourglass_cubemap2.atf

Once you have your batch file ready it’s just a matter of adjusting the settings and testing in your project. To execute the batch simply type ./batch_basic_shading in your terminal window.

Once you have created your first ATF files, you can check out a preview using the ATFViewer (also supplied in ATF tools).

If you project takes a long time to compile or you just need to quickly check if the resulting texture quality is good enough for your puposes, ATFViewer is the tool for you. It’ll also show the contents of the information file containing mipmap levels and contained formats eg DXT* (works on desktops and browsers), ETC (Android) and/or PVRTC (iOS)

Using the ATFTexture class

If you’ve ever used the BitmapTexture class in Away3D, you’ll find using ATF textures very easy. The only adjustments you’ll need to make is at the point where you create your BitmapTexture objects - replacing them with ATFTexture object. These wrap the contents of an ATF file as a ByteArray (rather than the more usual BitmapData). Away3D understands your ATF file once it is wrapped in an ATFTexture object,  and doesn’t require any further information. The new object can now be used in place of the BitmapTexture object for all your texture assignments.

In order to get your ATF files into your Flash application you can do one of two approaches - either embed it:

 // Embed ATF-file
[Embed(source="/../asset/compressed_texture.atf", mimeType="application/octet-stream")]
private const _bytesAtf:Class;

// Create the material
var _texture:ATFTexture = new ATFTexture(new _bytesAtf());
var textureMaterial:TextureMaterial = new TextureMaterial(_texture);

Or load at runtime using a standard URLLoader object:

 var url:String = "../asset/compressed_texture.atf";
 loader = new URLLoader();
 loader.dataFormat = URLLoaderDataFormat.BINARY;
 loader.addEventListener(Event.COMPLETE, textureLoadComplete);
 var urlReq:URLRequest = new URLRequest(url);
 loader.load(urlReq);

function textureLoadComplete(event:Event):void
{
 // Create the material
 var _texture:ATFTexture = new ATFTexture(loader.data);
 var textureMaterial:TextureMaterial = new TextureMaterial(_texture); 
}

Shading with ATF Textures

The one limitation of ATF textures over using BitmapData in Away3D is that they cannot be created and modified at runtime. However, not having to worry about runtime editing can mean that an ATF file can be optimised ready for use by the GPU with mipmaps etc. As they are pre-compressed they will upload to the GPU faster, and take up less GPU memory once they are there. In the previous example, the textures used for the beach ball, trinket etc are created and assigned like so:

//cube textures
[Embed(source="/../asset/cube/trinket_diffuse.atf", mimeType="application/octet-stream")]
public static var TrinketDiffuse:Class;
[Embed(source="/../asset/cube/trinket_specular.atf", mimeType="application/octet-stream")]
public static var TrinketSpecular:Class;
[Embed(source="/../asset/cube/trinket_normal.atf", mimeType="application/octet-stream")]
public static var TrinketNormals:Class;

cubeMaterial = new TextureMaterial(new ATFTexture(new TrinketDiffuse()));
cubeMaterial.specularMap = new ATFTexture(new TrinketSpecular());
cubeMaterial.normalMap = new ATFTexture(new TrinketNormals());
cubeMaterial.lightPicker = lightPicker;

Once you have your ATF texture assigned to your TextureMaterial, that’s it! Away3D will take care of the rest.

ATF in SkyBox

Creating a skybox normally takes only few lines of code, but is made simpler with ATF because the texture comes pre-packed as a cube texture in the ATF file. As a result, you can assign an ATFCubeTexture directly to a SkyBox like so:

private var _skyMap:ATFCubeTexture;
[Embed(source="/../asset/sky/hourglass_cubemap2.atf", mimeType="application/octet-stream")]
public static var SkyMapCubeTexture : Class;

_skyMap = new ATFCubeTexture(new SkyMapCubeTexture());
scene.addChild(new SkyBox(_skyMap));

Conclusion

This new workflow is a feature currently available in Away3D 4.1 Alpha. The ATF format improves loading and runtime performance, and for speed-critical apps it is highly recommended that you start using them.