Introducing compressed textures with the ATF SDK

Adobe introduced Stage3D last year and the momentum behind it has never stopped growing. However, there is one area where Adobe did not give all the details—Adobe Texture Format and the ATF file format. You may have seen ATF mentioned in the Stage3D documentation as the compressed texture file format. The ATF SDK provides you with the tools you need to create and inspect ATF texture files, and this article provides an overview of the ATF SDK and how to use it when working with textures.

What is the ATF SDK?

First, you'll need some background on the different types of texture formats and how they're used.

When doing GPU programming with any technology, you have two options for how you handle your textures: you can use compressed or uncompressed images. When using uncompressed textures, an uncompressed file format like PNG is used and uploaded to the GPU. Because GPUs don't support the PNG file format natively, your texture is actually stored in CPU memory. The same thing applies for JPEG images—graphics chipsets don't know anything about JPEG so they are also decoded in CPU memory.

It would be better to use GPU memory instead of CPU memory. However, in order to use GPU memory you must use the right kind of texture file for the GPU. Each platform has different support for compressed textures depending on the hardware chipset being used. Table 1 lists the differences.

Table 1. Compressed texture formats by platform and chipset

Why ATF?

As you can imagine from looking at Table 1, if you develop a game targeting iOS, Android, and desktop platforms, you need to supply your textures compressed to each format for each platform, which would look like this (for each asset):

• DXT for Windows and Mac OS

• ETC1 or DXT for Android

• PVRTC for iOS

Of course it is a pain to provide all the required versions of the textures, detect at runtime the platform on which your application is running, and upload the corresponding texture. Wouldn't it be cool if you could just rely on one single container that would wrap all the textures for each platform, and then have Flash Player or Adobe AIR automatically extract the required texture depending on the platform? This is what ATF gives you.

Along with enabling you to use one file for all the different compressed texture formats, ATF offers these additional benefits:

• Faster rendering

• Lower texture memory requirements (extremely important on devices like the first-generation iPad on which memory is very limited)

• Faster texture uploads into texture memory

• Automatic generation of all required mipmaps (you can disable this if needed)

• Higher resolution textures with the same memory footprint (when using compressed textures)

ATF internals

You can think of the ATF format as a container for compressed images.  By default, all the texture formats (PVRTC, ETC1, and DXT1/DXT5) are embedded in the ATF file (see Figure 1).

Figure 1. Default ATF file structure

For each platform, AIR or Flash Player automatically extracts the appropriate texture. However, in some cases you may want to target only a limited set of platforms. Why should you embed desktop textures if you are only publishing for mobile, or Android textures if you are targeting iOS only? To accommodate this use case, you can choose to embed only one texture type inside the ATF file, making your assets smaller. An ATF asset that targets only iOS, only includes a PVRTC texture (see Figure 2).

Figure 2. ATF file structure for an iOS-only asset

The same applies to ETC1 if  you are targeting Android (see Figure 3).

Figure 3. ATF file structure for an Android only asset

Note: If you are familiar with the ETC1 format, you may be wondering how transparency is handled. The Flash runtime uses a dual ETC1 approach with two textures, one for the alpha channel and one for the colors. The ATF tools create these two textures for you.

An example ATF file for a desktop only asset would include only the DXT texture (see Figure 4).

Figure 4. ATF file structure for a desktop only asset

The difference between the DXT1 and DXT5 formats is alpha support. DXT1 does not support transparency, but DXT5 does. The ATF tools automatically detect if your images have transparency and select the proper DXT version for you. Also note that ATF is not alpha premultiplied.

If you want to store uncompressed textures inside an ATF file, you can also do that (see Figure 5).

Figure 5. ATF file structure with an uncompressed RGBA asset

This is helpful if you want to use uncompressed textures but still want to use a cube map, automatic mipmap support, or even texture streaming.

How to use the tools

Now that you know a little more about ATF, the next step is creating an ATF file. The ATF SDK includes command-line utilities for creating ATF files. It also includes command-line tools as well as the ATFViewer GUI tool for previewing and inspecting ATF files.

For the complete list of tools in the SDK and a full command-line reference, see the ATF tools user's guide.

png2atf

The main tool you need to know about is png2atf. As you can guess from the name, this tool takes a PNG file and produces an ATF file. The following examples demonstrate using the png2atf tool:

// package leaf.png with all 3 formats (DXT5, PVRTC and ETC1x2)> png2atf.exe ‐c ‐i leaf.png ‐o leaf.atf[In 213KB][Out 213KB][Ratio 99.9703%][LZMA:0KB JPEG‐XR:213KB]// package a specific range of mipmaps> png2atf.exe ‐c ‐n 0,5 ‐i leaf.png ‐o leaf0,5.atf[In 213KB][Out 213KB][Ratio 99.8825%][LZMA:0KB JPEG‐XR:213KB]//package only DXT format> png2atf.exe ‐c d ‐i leaf.png ‐o leaf_dxt5.atf[In 85KB][Out 85KB][Ratio 100.045%][LZMA:0KB JPEG‐XR:85KB]//package only ETC1 format> png2atf.exe ‐c e ‐i leaf.png ‐o leaf_etc1.atf[In 85KB][Out 85KB][Ratio 100.045%][LZMA:0KB JPEG‐XR:85KB]//package only PVRTC format> png2atf.exe ‐c p ‐i leaf.png ‐o leaf_pvrtc.atf[In 42KB][Out 42KB][Ratio 100.089%][LZMA:0KB JPEG‐XR:42KB]

If you want to store an uncompressed texture inside your ATF just leave off the -c argument:

//package as uncompressed (RGBA) format> png2atf.exe ‐i leaf.png ‐o leaf_uncompressed.atf[In 341KB][Out 43KB][Ratio 12.8596%][LZMA:0KB JPEG‐XR:43KB]

Another cool feature is that ATF files can also be used with streaming. To generate three subfiles you can do this:

png2atf ‐m ‐n 0,0 ‐c ‐i cubecat0.png ‐o cubecat_c_high.atfpng2atf ‐m ‐n 1,2 ‐c ‐i cubecat0.png ‐o cubecat_c_med.atfpng2atf ‐m ‐n 3,20 ‐c ‐i cubecat0.png ‐o cubecat_c_low.atf

Support for texture streaming shipped in Flash Player 11.3 and AIR 3.3. Make sure to create the texture with streaming on, by specifying a value for the streamingLevel argument when you use the Context3D object's createTexture()method to create the Texture instance.

You can also create an ATF file containing a cube map texture; for example:

// to create an ATF for a cube map texture// prepare a png file for each side of the cube as follows:// ‐X: cube0.png// +X: cube1.png// ‐Y: cube2.png// +Y: cube3.png// ‐Z: cube4.png// +Z: cube5.png> png2atf.exe ‐c ‐m ‐i cube0.png ‐o cube.atf

pvr2atf

If you have used the Apple texturetool to generate PVR textures, you can use the pvr2atf command-line tool from the ATF SDK to convert your PVR texture files to ATF files. The tool is similar to png2atf except that the input file must be in the PVR texture format.

To convert a PVR file named test.pvr to an RGB or RBGA ATF file, run this command:

> pvr2atf -r test.pvr -o test.atf[In 4096KB][Out 410 KB][Ratio 10.0241%][LZMA:0KB JPEG-XR:410KB]

ATFViewer

ATFViewer is a graphical tool that lets you preview and inspect ATF files. Its primary purpose is to audit DXT1, ETC1, and PVRTC compression artifacts. You can open and view an ATF file by choosing File > Open or by dragging the file from the file system into the window.

Figure 6 shows an example of using ATFViewer to view a test file from Starling. You can preview the texture for each format. ATFViewer also provides a code snippet preview that shows how to load the ATF file in raw ActionScript 3 Stage3D code.

Figure 6. The ATFViewer application

When you open an ATF texture that contains only one specific compression format, ATFViewer shows that. For example, when ATFViewer is used to preview an ATF file containing only DXT textures, the ETC1 and PVRTC entries in the texture list are grayed out (see Figure 7).

Figure 6. The ATFViewer application

Note: The screenshots in Figures 6 and 7 include some minor errors in the generated ActionScript code snippet, which will be fixed in the ATFViewer tool. For the correct code see the next section, Using compressed textures in ActionScript.

Other tools

In addition to the primary tools described here, the ATF SDK includes command-line tools for creating ATF files from other formats, inspecting PNG files, and getting information about ATF files.  See the ATF tools user's guide for more details.

Using compressed textures in ActionScript

The way you use compressed textures from ActionScript depends on whether you're working directly in the Stage3D APIs or whether you're using Starling. To cover the entire set of capabilities for ATF textures, you need to meet these requirements:

• If you are using Starling, you need at least Starling 1.2. Get the latest version.

• If you are using Stage3D directly, you need to use the latest AGALMiniAssembler.

• You need the AIR SDK 3.4 or newer. (Flash Builder 4.7 comes with the AIR 3.4 SDK.)

• You need to target Flash Player 11.4 or AIR 3.4 or newer.

• You need to add the following compiler argument: "-swf-version=17"

Using compressed textures with Stage3D

To use compressed textures with Stage3D, you need to create a Texture object using theContext3D.createTexture() method. For the format argument, use the valueContext3DTextureFormat.COMPRESSED_ALPHA or Context3DTextureFormat.COMPRESSED. Finally, call your Texture object's uploadCompressedTextureFromByteArray() method, passing your ATF file's bytes as the first argument; for example:

[Embed(source="mytexture.atf", mimeType="application/octet‐stream")]public static const TextureAsset:Class;public var context3D:Context3D;public function init():void{    var texture:Texture = context3D.createTexture(256, 256, Context3DTextureFormat.COMPRESSED_ALPHA, false);    var textureAsset:ByteArray = new TextureAsset() as ByteArray;    texture.uploadCompressedTextureFromByteArray(textureAsset, 0);}

If you're using a cube map texture, use the Context3D.createCubeTexture() method to create a CubeTexture instance instead:

var texCubemap:CubeTexture = context3D.createCubeTexture(256, Context3DTextureFormat.COMPRESSED_ALPHA, false);var textureAsset:ByteArray = new TextureAsset() as ByteArray;texCubemap.uploadCompressedTextureFromByteArray(textureAsset, 0);

In addition, depending on the format of the texture, you need to specify either "dxt1" or "dxt5" as the texture sampler of your fragment shader:

• Use "dxt1" if your texture format is Context3DTextureFormat.COMPRESSED (regardless of whether the texture format is DXT, PVRTC, or ETC1)

• Use "dxt5" if your texture format is Context3DTextureFormat.COMPRESSED_ALPHA (regardless of whether the texture format is DXT, PVRTC, or ETC1)

• Use nothing if your texture format is Context3DTextureFormat.BGRA

To see a real-world example of integrating ATF in ActionScript, check out the Starling commit for ATF support on GitHub, which shows how Starling loads ATF textures.

Using compressed textures with Starling

The good news for Starling users is that Starling has built-in support for ATF textures through Starling'sTexture.fromAtfData() method. The following code listing shows an example of using an ATF texture with a Starling Image object:

[Embed(source="starling.atf", mimeType="application/octet-stream")]public static const CompressedData:Class;var data:ByteArray = new CompressedData();var texture:Texture = Texture.fromAtfData(data);var image:Image = new Image(texture);addChild(image);

For the full details, see the Starling Wiki page on using ATF textures.

Where to go from here

Refer to the ATF tools user's guide for details and usage examples for the tools that make up the ATF SDK.  For more information on Stage3D, see the Stage3D page in the Game Development Center.

From: http://www.adobe.com/devnet/flashruntimes/articles/introducing-compressed-textures.html

You must Sign up as a member of Effecthub to view the content.