Adobe Texture Format (ATF) tools user's guide

Adobe Texture Format, or ATF is the recommended file type for fixed texture assets that are used with the Flash runtime's Stage3D API.

This guide is a reference for the following tools, which Adobe provides to create and manage ATF files (Adobe Texture Files):

• png2atf

• pvr2atf

• atf2pvr

• ATFViewer

• atfinfo

• pngalpha

• pngsquare

ATF basics

ATF files rely on compression, and there are some limitations that you need to keep in mind.

ATF compression

An ATF file is a file container for storing texture data. The ATF file format achieves its lossy compression through the use of two common techniques: JPEG XR compression and block-based compression. JPEG XR compression provides a competitive method to save storage space and network bandwidth. Block-based compression provides a way to reduce texture memory usage on the client, at a fixed ratio of 1:8 compared to RGBA textures. ATF supports three types of block-based compression: DXT1, ETC1, and PVRTC.

In ATF files, compression is performed on two levels. The first type of compression is optional block-based compression. On top of that, standard lossless or lossy JPEG XR compression is applied. Other features of the ATF file format include:

• Embedding mipmaps

• Optionally embedding a complete cube map (sky map)

• Optional support for selecting an internal color space (4:4:4, 4:2:2, and 4:2:0)

ATF limitations

ATF files have various limitations that are the direct result of existing hardware capabilities on various mobile devices. These limitations include:

• The maximum size for a texture is 2048 by 2048 pixels.

• The length of each side of a texture must be a power of two: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, or 2048.

• To use block-based compression a texture's dimensions must be equal (the texture must be a square): 1x1, 2x2, 4x4, 8x8, 16x16, 32x32, 64x64, 128x128, 256x256, 512x512, 1024x1024, or 2048x2048.

• Block-based compression can't be used with an alpha channel (transparency) of any kind at this time.

• If your texture uses the maximum 2048x2048 size, you must provide at least one regular mipmap level. This is because certain devices only allow texture sizes up to 1024x1024. The Flash runtime will automatically switch the texture size to 1024x1024 if necessary.

png2atf

The png2atf command-line utility converts a PNG file to an ATF file. The resulting ATF file can then be used with the Texture class's uploadCompressedTextureFromByteArray() method. It takes any valid PNG file as input. By default it converts the PNG file to either an RGB or RGBA ATF file, depending on whether the PNG file includes transparency. The png2atf tool can optionally create a texture with block-based compression if the source PNG does not have transparency.

Example usage

To convert a PNG file to an RGB or RGBA ATF file run the png2atf command:

> png2atf -i test.png -o test.atf.[In 4096 KB][Out 410 KB][Ratio 10.0241%][LZMA:0KB JPEG-XR:410KB]

To create a texture file with block-based compression run the command with the -c parameter; for example:

> png2atf -c -i test.png -o test.atf..........................................................[In 2048KB][Out 1704KB][Ratio 83.2007%][LZMA:937KB JPEG-XR:766KB]

Command-line options

Table 1 shows png2atf command-line options.

Table 1. png2atf command-line options

Figure 1. Texture files used to create a cube map ATF file

pvr2atf

The pvr2atf command-line utility converts a PVR texture file to an ATF file. The resulting ATF file can be used with the Texture class's uploadCompressedTextureFromByteArray() method. This tool works similarly to png2atf except that the input file is in the PVR texture format. For block-based compression, you must provide precompressed textures in the form of three PVR files.

Example usage

To convert a PVR file to an RGB or RGBA ATF file run the pvr2atf command; for example:

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

To create a texture file with block-based compression run the command shown below, in which each PVR file represents a block-compressed format file:

> pvr2atf -d test_dxt1.pvr -e test_etc1.pvr -p test_pvrtc.pvr -o test.atf..........................................................[In 2048KB][Out 1704KB][Ratio 83.2007%][LZMA:937KB JPEG-XR:766KB]

Accepted PVR texture types

The pvr2atf tool accepts the following types of PVR files:

• OpenGL ES 2.0 RGB 888 (OGL_RGB_888)

• OpenGL ES 2.0 RBGA 8888 (OGL_RGBA_8888)

• DirectX 9 DXT 1 (D3D_DXT1)

• OpenGL ES 2.0 ETC (ETC_RGB_4BPP)

• OpenGL ES 2.0 PVRTC 4BPP (OGL_PVRTC4)

• Cube maps (PVRTEX_CUBEMAP)

• Mipmaps (PVRTX_MIPMAP)

It does not accept flipped textures. Make sure that you create your PVR texture with the flipping option turned off. This can be done using the -yflip0 option of the PVRTexTool command-line tool or by deselecting the Flipped checkbox in the PVRTexTool GUI tool.

Command-line options

Table 2 shows pvr2atf command-line options.

Table 2. pvr2atf command-line options

atf2pvr

The atf2pvr tool converts ATF files into PVR texture files, splitting one ATF file into multiple PVR files. If you specify an ATF file with block-based compression, atf2pvr generates three PVR files with distinct file extensions to designate each output file's type. The following is an example invocation of the atf2pvr command:

> atf2pvr -i test.atf -o test

ATFViewer

ATFViewer is a GUI tool for previewing and inspecting ATF files. The primary purpose of ATFViewer is to audit DXT1, ETC1, and PVRTC compression artifacts.

To open and view an ATF file, launch the ATFViewer application, and then choose File > Open or drag an ATF file into the window from the file system. The ATF file's contents appear in the main window (see Figure 2).

Figure 2. The ATFViewer tool

The snippet preview area (also shown below) shows an example of how to load the ATF file in ActionScript 3 code.

[Embed( source = "mytexture.atf", mimeType="application/octet-stream")]    public static const CubeTextureAsset:Class;    public var context3D:Context3D;    public function init():void{        var cubeTexture:CubeTexture = context3D.createCubeTexture(512, Context3DTextureFormat.COMPRESSED, false);        var cubeTextureAsset:ByteArray = new CubeTextureAsset() as ByteArray;        cubeTexture.uploadCompressedTextureFromByteArray(cubeTextureAsset, 0);    }

atfinfo

The atfinfo&n...



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