Adobe Texture Format (ATF) tools user's guide
Created
3 December 2012
Requirements
Prerequisite knowledge
Some familiarity with command-line tools and texture file formats will help you make the most of this guide.
User level
Intermediate
Required products
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 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.
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
Parameter |
Description |
-i <file> |
Specifies the input file name. |
-o <file> |
Specifies the output file name. |
-c |
Creates the output file with block-based compression. Three types of block-based compression textures are created and embedded into the output ATF file: DXT1, ETC1, and PVRTC 4bpp. When you load this type of texture into Flash Player or AIR, the runtime uses the appropriate format for the device. |
-m |
Creates a cube map texture. A cube map texture requires six input files. The input files need to be named consecutively in the form XXXn.png where XXX is the base file name and n=0-5, for example: cube0.png, cube1.png, cube2.png, cube3.png, cube4.png, cube5.png. You only specify the first file as the input file with the -i parameter (cube0.png in this example). |
-n <start>,<end> |
Turns off auto-generation of mipmaps and only embeds a specific range of texture levels (the main texture plus mipmaps). The range is defined in the form |
-x |
Reads mipmap images from input files instead of auto-generating them. The input files need to be named XXXnn.png where XXX is the base file name and nn=00-12. File 00 is the main texture and files 01 through 12 are the mipmaps. You only specify the first file (XXX00.png) as the input file with the -x parameter. |
-s |
Silences the tool's output during compression. You may want to use this parameter for batch processing. |
-4 |
Instructs the JPEG XR encoder to use the 4:4:4 color space internally. This is the default for block-based compression. In some cases it is desirable to use this color space for RGB/RGBA textures, for example if you see color bleeding artifacts around red or blue shapes or for normal maps. |
-2 |
Instructs the JPEG XR encoder to use the 4:2:2 color space internally. Adobe recommends that you do not use this color space for block-based compression because it can cause severe artifacts. |
-0 |
Instructs the JPEG XR encoder to use the 4:2:0 color space internally. In general, Adobe recommends that you do not use this color space for block-based compression because it can cause severe artifacts. However, it might be worth experimenting with this option if the image data is monochromatic. |
-q <0-180> |
Selects the quantization level, which determines how much the image data should be compressed. Higher values create more artifacts and smaller values reduce artifacts. |
-f <0-15> |
Selects how many flex bits are trimmed during JPEG XR compression. This option is not related to the quantization level. Rather, it selects how much noise is retained across the image. Higher values create more artifacts and lower values create fewer artifacts. The default value is 0. |
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
Parameter |
Description |
-r <file> |
Specifies the input RGB or RGBA PVR file. This option can't be used together with the -d, -e, or -p options. |
-d <file> |
Specifies the input DXT1 PVR file. |
-e <file> |
Specifies the input ETC1 PVR file. |
-p <file> |
Specifies the input PVRTC PVR file. |
-o <file> |
Specifies the output file. |
-s |
Silences the tool's output during compression. You may want to use this parameter for batch processing. |
-4 |
Instructs the JPEG XR encoder to use the 4:4:4 color space internally. This is the default for block-based compression. In some cases it is desirable to use this color space for RGB/RGBA textures, for example if you see color bleeding artifacts around red or blue shapes or for normal maps. |
-2 |
Instructs the JPEG XR encoder to use the 4:2:2 color space internally. Adobe recommends that you do not use this color space for block-based compression because it can cause severe artifacts. |
-0 |
Instructs the JPEG XR encoder to use the 4:2:0 color space internally. In general, Adobe recommends that you do not use this color space for block-based compression because it can cause severe artifacts. However, it might be worth experimenting with this option if the image data is monochromatic. |
-q <0-180> |
Selects the quantization level, which determines much the image data should be compressed. Higher values create more artifacts and smaller values reduce artifacts. |
-f <0-15> |
Selects how many flex bits are trimmed during JPEG XR compression. This option is not related to the quantization level. Rather, it selects how much noise is retained across the image. Higher values create more artifacts and lower values create fewer artifacts. The default value is 0. |
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 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).
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);
}
The atfinfo command-line utility displays internal information about ATF files. It prints the size, mipmap count, texture type, and texture format of the ATF file, as well as whether the file contains a cube map. It also lists the ActionScript 3 class and texture format that correspond to the format of the ATF file. The following is an example invocation of atfinfo and its output:
> atfinfo -i test.atf
File Name : test.atf
ATF File Type : Compressed (DXT1+ETC1+PVRTC4bpp)
Size : 1024x1024
Cube Map : no
Mip Map Count : 10 (512x512,256x256,128x128,64x64,32x32,16x16,8x8,4x4,2x2,1x1)
AS3 Texture Class : Texture (flash.display3D.Texture)
AS3 Texture Format : Context3DTextureFormat.COMPRESSED (flash.display3D.Context3DTextureFormat)
The pngalpha command-line utility detects transparent pixels in PNG files. The output is one of two values: alpha if the PNG has transparent pixels, or opaque if it does not have transparent pixels. The following is an example invocation of pngalpha and its output:
> pngalpha -i test.png
alpha
The pngsquare can be used to determine if a PNG file is square or rectangular. The output is one of two values: square if the PNG is square or rectangle if it is not square. The following is an example invocation of pngsquare and its output:
> pngsquare -i test.png
square
For more information on the benefits of using ATF files, see Introducing compressed textures with the ATF SDK.
This work is licensed under a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 Unported License.
