Share to EffectHub.com

You can earn money or coins from your share:)

Tips: you can use Sparticle for uploading away3D effects.

Tips: you can download Sparticle for uploading effects.

Tips: The ActionScript editor is supporting Away3D, Starling, Dragonbones and Flex frameworks.

Tips: paste the web page URL then click button:)

EffectHub.com: Your Best Source for Gaming
Login    or

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: DXT1ETC1, 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


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.
If the PNG file includes transparency, png2atf creates an RGBA texture instead. Use theatfinfo tool to find out what format an ATF file includes. Use the pngalpha tool to find out if a particular PNG file has transparent pixels before creating an ATF file.

-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).
The arrangement of the files is shown in Figure 1.

-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 <start>,<end>, where 0 is the main texture and the mipmaps start with level 1. If you leave off this parameter, png2atf generates all applicable mipmap levels. However, in some cases (such as for sky maps) it is not desirable to enable mipmaps.

-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.
A value of 0 means lossless compression (the default for block-based compression textures). Adobe recommends that you do not use lossy compression for block-based compression. However, it might be worthwhile to experiment with this value on a case-by-case basis.
The default value for RGB and RGBA textures is 30.
This value should not be confused with the standard JPEG compression factor. It is similar in concept, but it applies in a different nonlinear range.

-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.

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

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


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.
A value of 0 means lossless compression (the default for block-based compression textures). Adobe recommends that you do not use lossy compression for block-based compression. However, it might be worthwhile to experiment with this value on a case-by-case basis.
The default value for RGB and RGBA textures is 30.
This value should not be confused with the standard JPEG compression factor. It is similar in concept, but it applies in a different nonlinear range.

-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.

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

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.

10980 views    4 comments

You must Sign up as a member of Effecthub to join the conversation.

Join Effecthub.com


Or Login with Your Email Address:

Or Sign Up with Your Email Address:
This field must contain a valid email
Password should be at least 1 character