Stage3D compressed textures – Introducing the ATF SDK

We introduced Stage3D last year and the momentum behind has never stopped growing but there is one area we did not give all the details. The ATF file format, it is mentioned here and there, so what's up with this? Some of you may have seen it in the documentation for Stage3D referred as the compressed texture file format, but we never shared any tools to create those famous ATF textures.

Before we package the ATF tools with the AIR SDK, I am happy to share here in advance the ATF tools so that you guys can start leveraging the ATF format now!

So what is it?

First, let's start by talking about what compressed textures are.

When doing GPU programming with any technology, you have two options for how you handle your textures. You can go compressed or uncompressed, very simple. So, what is the difference?

  1. When using uncompressed textures, a good old uncompressed file format like PNG is used and uploaded to the GPU.
  2. Because GPUs don't support such a file format natively, your texture is actually stored in RAM, when it could actually be uncompressed by and on the GPU memory.
  3. Same thing applies for JPEG images, make no mistake, graphics chipsets don't know anything about JPEG which would also be decoded on the RAM.
  4. Of course, each platform has different support for compressed textures depending on the hardware chipset being used.
Now get ready for the fun! Here is below a little table to illustrate it:

Date Published
1June 1997
2June 1998
3December 1999
5December 2009
5.1June 2011
6 (Harmony)In progress

Why ATF?

As you can imagine, if you would develop a game targeting iOS, Android and desktop, you would need to supply your textures compressed to each format for each platform. Which would look like this:

  1. leaf.png encoded to DXT for Windows and MacOS
  2. leaf.png encoded to ETC1 or DXT for Android (Nvidia)
  3. leaf.png encoded to PVRTC for iOS (ImgTech)

Of course it is a pain to provide all the different versions of the textures, detect at runtime which platform you are running on 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 Flash Player or AIR would extract automatically the texture required depending on the platform? So here comes ATF.

The ATF internals

Really, think about the ATF format as a container for lossy images. Here is below a little figure showing very sinply the structure of a default compressed ATF file:

ATF (cross-platform)

By default, all textures format (PVRTC (4bpp), ETC1, and DXT1/5) are embedded in the ATF file so that for each platform, AIR or Flash Player automatically extracts the appropriate texture. But in some cases, you may want to target mobile only and why should you embed desktop related textures or Android if you are targeting iOS only? To cover this, you can also embed the PVRTC textures only inside the ATF file, making your assets smaller.

The figure below illustrate the idea:

ATF (for iOS)

As you can imagine, the same applies to ETC1 if you are targeting Android:

ATF (for Android)

If you know about ETC1, you may wonder how we handle transparency then? We use a dual ETC1 approach with two textures, one for the alpha channel and one for the colors.

And finally on desktop only, where only the DXT texture can be provided:

ATF (for desktop)

The difference between DXT1 and DXT5 resides in alpha support. DXT1 does not support transparency, DXT5 does. Automatically the ATF tools will detect if your images have transparency and select the proper DXT version for you. Also note that ATF is not alpha pre-multiplied.

Now, if you want to store uncompressed textures inside an ATF file, you can also do that:

ATF uncompressed

Why would you do that you may ask? Well, you may want to use uncompressed textures but still want to leverage cubemap, automatic mipmap support or even texture streaming.

Ok, now apart from the fact that hardware requires those textures to be compressed, what is the value for your content?

Yes, what does it bring you?

  • Faster rendering
  • Lower texture memory requirements (extremely important on devices like the iPad1 where memory is very limited)
  • Faster texture uploads into texture memory
  • Automatic generation of all required mip-maps (note that you can disable this if needed).
  • Additionally, the use of compress textures allows the application to utilize higher resolution textures with the same memory footprint.
Now the question is, how do you create such ATF files? It is very easy, we provide a few command line tools for that. Let's have a look at how it works.

How to use the tools

The main tool you need to know about is png2atf, which as you can guess, takes a png and gives you an ATF file:

//package leaf.png with all 3 formats (DXT5, PVRTC and ETC1x2)
C:\png2atf.exe  -c  -i  leaf.png  -o  leaf.atf
[In 213KB][Out 213KB][Ratio 99.9703%][LZMA:0KB JPEG-XR:213KB]

//package specific range of mipmaps
C:\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
C:\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
C:\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
C:\png2atf.exe  -c p  -i  leaf.png  -o  leaf_pvrtc.atf
[In 42KB][Out 42KB][Ratio 100.089%][LZMA:0KB JPEG-XR:42KB]

As mentioned earlier, what if you wanted to store uncompressed a uncompressed texture inside your ATF? For this, just don't use the -c argument:

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

Another cool feature is that ATF can also be used with streaming, to generate 3 sub-files you can do this:

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

For info, texture support streaming shipped in Flash Player 11.3/AIR 3.3. Make sure to create the texture with streaming on, by using the streamingLevel arguments of the Texture.createTexture() API.

If you have used the texturetool from Apple to generate your PVR textures, this is the same approach. Another tool called pvr2atf, which is a command line utility converts PVR texture files to ATF files. The tool works similarly to png2atf except that you have to provide input files in the PVR texture format.

To convert a PVR file to an RGB or RGBA ATF file run the command as such:

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

Also, you can use ATF for a cubemap texture:

//to create a ATF for cubemap texture,
//prepare png file for each side of the cube as:
// -X: cube0.png
//+X: cube1.png
// -Y: cube2.png
//+Y: cube3.png
// -Z: cube4.png
//+Z: cube5.png
C:\png2atf.exe  -c   -m  -i  cube0.png  -o  cube.atf

ATFViewer is a GUI tool which previews and inspects ATF files. The primary purpose is to audit DXT1, ETC1 and PVRTC compression artifacts. You can open and view ATF files by either using the ‘Open...’ menu item or by dragging a file from Explorer into the window. The Snippet preview area shows you an example of how to load a particular ATF file in raw ActionScript 3 Stage3D code.

Below is an example of a test file from Starling, you can preview the texture for each format and also have a little code snippet at the bottom which tells you how to use it in ActionScript 3 with Stage3D:

ATF Viewer

Note that when opening an ATF texture containing only specific compression, the ATFViewer will show this, below we opened an ATF file containing only the DXT textures, you can see that ETC1 and PVRTC in the texture types list are greyed out:

ATF DXT only

Let's have a look now at how we can use compressed textures with the Stage3D APIs.

Using compressed textures with Stage3D

To use compressed textures with Stage3D, you need to use the Texture.uploadCompressedTextureFromByteArray API with one of the two related Context3DTextureFormat constants (Context3DTextureFormat.COMPRESSED_ALPHA and Context3DTextureFormat.COMPRESSED):

class 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);

In the context of a cubemap texture, you would write:

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

Also, depending on the format of the texture, “dxt1” or “dxt5” is needed in the texture sampler of your fragment shader:

  • Nothing needed for Context3DTextureFormat.BGRA, same as before
  • “dxt1” for Context3DTextureFormat.COMPRESSED (whatever the texture format used, DXT, PVRTC, or ETC1)
  • “dxt5” for Context3DTextureFormat.COMPRESSED_ALPHA (whatever the texture format used, DXT, PVRTC, or ETC1)
You can also check the specific Starling commit for ATF support to see how it got integrated.

Integration with Starling

Great news, Starling already supports ATF textures through the Texture.uploadAtfData API. Find here all the details about ATF and Starling, but it is as simple as this:

[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);

Yes, as simple as this ;)


I want to highlight that even if ATF will be very useful for 2D content (like with Starling), ATF has been mainly designed for 3D textures purposes. So what does it mean?
The compression applied to the textures is lossy and may impact too much the quality of your assets. Things like RGBA8888 and RGBA4444 for PVR are not supported and could be an issue.
But we need your feedback and testing to see how we can improve ATF and add support for more compression types. So let us know!


One thing to keep in mind is that to cover the entire set of capabilities for ATF textures, you need:

  • If you are using Starling, you need at least Starling 1.2. Just pull the latest version from Github.
  • If you are using Stage3D directly, you need to use the latest AGALMiniAssembler
  • You need at least the AIR SDK 3.4. Download Flash Builder 4.7 which comes out of the box with the AIR 3.4 SDK.
  • You need to target at least Flash Player 11.4/AIR 3.4
  • You need to add the following compiler argument: ”-swf-version=17”


Download the ATF tools here (as part of the Game Developer Tools). Which contains:

  • The ATF tools binaries (Linux, Mac, Windows).
  • ATF specification
  • ATF User Guide with some more details.


Comments (46)

  1. Philippe wrote:

    I’m curious, does (could) ADT automatically strip the useless formats depending on the target?

    Friday, October 19, 2012 at 9:28 pm #
  2. Henke37 wrote:

    You might want to adjust your screen/theme/skin/whatever settings, because it is practically impossible to tell that the options are disabled from the screenshot.

    Friday, October 19, 2012 at 9:29 pm #
  3. Elliot Geno wrote:

    Can this be used for non Stage3D content. For instance, I think I remember seeing that the compression for this file format sounded superb.

    Is the compression better than the JPEG compression from Flash Pro? It would be awesome to have access to smaller file sizes in Flash Pro.

    I am thinking Flash Pro’s compression tools will need overhauled anyway. These new Retina displays require huge images but smaller file sizes are within reach outside of Flash!

    Friday, October 19, 2012 at 9:33 pm #
  4. Thanks for the Linux support! I’m also curious about ADT stripping out the unused formats automatically.

    Friday, October 19, 2012 at 9:47 pm #
  5. Sebastien Flory wrote:

    If I use the atf as a container for non compressed texture, is it still uploading the texture asynchronously?


    Friday, October 19, 2012 at 10:09 pm #
  6. subb wrote:

    I’m not done reading, but :

    “Because GPUs don’t support such a file format natively, your texture is actually stored in CPU memory, when it could actually be stored on the GPU memory!”

    That can’t be true. Sure, the PNG texture is in CPU memory, but an uncompressed, raw version is uploaded to the GPU, right?

    Friday, October 19, 2012 at 10:16 pm #
  7. Martin wrote:

    Are there any tools planned for dynamic ATF byteArray creation? It would be really cool if we could use this for dynamically created assets :)

    Friday, October 19, 2012 at 10:47 pm #
  8. Gil wrote:

    Hi Thibault!
    We are releasing a great open-source library soon… (Details in the near future). And the ATF sounds like huge improvement that we can use.

    Where can we find the ATF file specifications? we need to create it in run-time…

    Gil Amran

    Friday, October 19, 2012 at 11:51 pm #
  9. Thibault Imbert wrote:

    Hi subb,

    Sorry for the confusion, I fixed the sentence.

    When using PVRTC, ETC, DXT, the texture is uploaded compressed and is being uncompressed by the GPU and stored there.

    But, we apply JPEG-XR compression on top of PVRTC, ETC, and DXT. And the JPEG-XR decompression happens on the CPU side.

    Hope this brings clarity.


    Friday, October 19, 2012 at 11:53 pm #
  10. Thibault Imbert wrote:

    Hi Gil,

    The ATF spec is in the package! :)


    Saturday, October 20, 2012 at 12:03 am #
  11. mark wrote:

    That url doesn’t work! 404!

    Saturday, October 20, 2012 at 1:00 am #
  12. mark wrote:

    works now, :)

    Saturday, October 20, 2012 at 1:33 am #
  13. Just implemented it in my own 2D engine and got it working almost immediately. Good timing, we were just having memory issues on iPad1 and iPod Touch! Thanks Thibault!

    Saturday, October 20, 2012 at 1:56 am #
  14. max wrote:

    Cool! I want Adobe AIR on Windows 8… Tyred of Microsoft tools.

    Saturday, October 20, 2012 at 7:42 am #
  15. Volgogradetzzz wrote:

    Hi. You mentioned about new AgalMiniAssembler. I’m using MacroAssembler and wonder – is it supports by adobe?

    Saturday, October 20, 2012 at 8:05 am #
  16. Oldes wrote:

    Hi Thibault, so finally it’s out! Just one detail, in the archive is missing ATFViewer for Windows. It would be fine, if one would not see screenshot from it in the user guide document. Is it by accident?

    Saturday, October 20, 2012 at 9:08 am #
  17. earl223 wrote:

    Can’t seem to get it to work… i get a “Texture format mismatch” error right after the Texture/uploadCompressedTextureFromByteArray() call.

    Saturday, October 20, 2012 at 11:45 am #
  18. JP Doiron wrote:

    Thanks Thibault.

    Saturday, October 20, 2012 at 2:59 pm #
  19. hi guys, great job.
    I have got a problem, using only one level -n 0,0 and after loading atf it shows nothing… but wihtout -n 0,0 it shows right.
    one more thing I want to do that because when it generates mip map levels texture quality is bad, so any ideas how can I fix that, maybe smoothing or something?


    Saturday, October 20, 2012 at 8:07 pm #
  20. hi Thibault, in UserGuide pdf there is a screenshot of ATFViewer for windows :) can you provide that too ?


    Saturday, October 20, 2012 at 9:15 pm #
  21. I guess -e parameter is not working…

    Sunday, October 21, 2012 at 1:23 pm #
  22. darebak wrote:

    Does atf textures support texture streaming? For me it looks like that they doesn’t.

    Sunday, October 21, 2012 at 8:34 pm #
  23. Thibault Imbert wrote:

    Hi Darebak,

    Yes they do. Can you show me the code you are using?


    Sunday, October 21, 2012 at 11:15 pm #
  24. Albin wrote:

    Hi Thibault, the tool keeps complaining “Dimensions not a power of 2!”, is there any other tool that can convert the dimensions of png file first? Thanks.

    Monday, October 22, 2012 at 10:06 am #
  25. Netphreak wrote:

    Is there any use in compressing bitmapdata before uploading to gpu memory?

    I’m thinking of dynamic / often updating bitmap textures.

    Is there any performance improovement using this technique? esp. on mobile devices with limited bandwidth? – or is the time spent compressing to great?

    Monday, October 22, 2012 at 1:12 pm #
  26. darebak wrote:

    Hi Thibault,
    right now i’m using this approach to stream non atf textures. Let’s say i want to stream texture with 6 mipmap levels. So i create the texture texture = context.createTexture(width, height, Context3DTextureFormat.BGRA, false, 5) and upload the highest level texture.uploadFromBitmapData(bitmapData, 5). Then over time upload rest of the leves. According to your article when i want to use atf textures i should use texture.uploadCompressedTextureFromByteArray(byteArray, 0), that’s fine however i’m missing the mipmap level parameter. How can i specify which mipmap level i want to upload?

    Tuesday, October 23, 2012 at 9:29 am #
  27. JB wrote:

    Pretty please, ATF Viewer for Windows.

    Tuesday, October 23, 2012 at 11:11 am #
  28. Valentin wrote:

    option “-n” is not working(png2atf.exe), checked with atfinfo.exe.

    Tuesday, October 23, 2012 at 11:46 am #
  29. I have converted this image – which is a 191Kb file, using the following command: png2atf -c -d -i left.png -o left.atf and I got a 2Mb file.

    Tuesday, October 23, 2012 at 12:50 pm #
  30. @Albin:
    you can use imagemagick on the command line to square your pngs
    convert -resize 512×512! source.png png24:dest.png

    @Wilson Silva and others:
    try the -r argument to use compression for block-based encodings and get WAY smaller file sizes. You can combine this with -q (default 30).

    the enclosed documentation is for v0.2 of the tools, not v0.5
    also the ATFViewer for Windows is missing

    Tuesday, October 23, 2012 at 2:12 pm #
  31. @Wilson Silva:
    also the -d in your command line is probably incorrect. If you want the dxt1/5 compression only, you command line should be:
    png2atf -c d -i left.png -o left.atf (683Kb)
    or as advised:
    png2atf -c d -r -i left.png -o left.atf

    Tuesday, October 23, 2012 at 2:19 pm #
  32. Thibault Imbert wrote:

    Hi guys,

    I just added ATFViewer.exe in the package.



    Wednesday, October 24, 2012 at 1:30 am #
  33. Nikolay wrote:

    Hi Thibault,

    i just made a little experiment with atf vs. png textures and hit a problem. With png texture everything works fine but with atf nothing is rendered neither in debug player nor in release player. When i run the same swf in standalone player atf works too. What could cause this problem?

    Wednesday, October 24, 2012 at 11:51 am #
  34. Macro wrote:

    I found that use “- n 0, 0″ parameter compiled atf files, ATFData class can’t correct analytic it, data[9] get a strange numerical, leading to can’t display properly

    Thursday, October 25, 2012 at 4:17 am #
  35. Ludo Avot wrote:

    Hi Thibault, thanks a lot for this great tool !

    I’m working with Starling on iPad and I noticed that embedding only PVRTC with options -c p -r -e doesn’t work. I have to embbed everything (-c -r -e) in order to see my graphics on the iPad. Do you know why ?

    By the way, if you are looking for batch conversion on windows I did this BAT file : It’s a first version you can modify it for your need.
    Put it with your png assets and the png2aft.exe and the atfinfo.exe files and run it.

    Friday, October 26, 2012 at 7:51 pm #
  36. Cem Uzunlar wrote:

    Hi Macro,

    You can use the command line tools from here:
    It allows use to specify mipmap levels including the no mipmap case. It outputs pvr files which you can then convert to atf with the pvr2atf.
    But keep in mind that 2048×2048 textures need to have at least the 1024×1024 mip map level. This is a Stage3D limitation for old graphics card compatibility.

    Friday, October 26, 2012 at 9:17 pm #
  37. darebak wrote:

    was anybody able to make the streaming work? I have tried this but it doesnt work at all.
    1. I have created texture asset like this:
    png2atf.exe -n 1,1 -c d -i leaf.png -o 1_leaf.atf
    2. Then i load the asset and create the texture like this:
    texture = context.createTexture(textureWidth , textureHeight, Context3DTextureFormat.COMPRESSED_ALPHA, false, 1);
    3. Then after i try to upload mimap level 1 with:
    texture.uploadFromByteArray(_compressedByteArray, 0, 1);

    and i always get Exception fault: RangeError: Error #3669: Bad input size.

    Monday, October 29, 2012 at 1:19 am #
  38. Larry wrote:

    Any chance of being able to save ATF file directly from Photoshop in the future?

    Thursday, November 1, 2012 at 3:23 pm #
  39. max wrote:

    Do you plan to publish the algorithm? I need an as3 implementation to compress textures on the fly.

    Friday, November 2, 2012 at 10:47 am #
  40. Bmoss wrote:

    Hi, I was investigated ATF, to use with my project. We have to use a lot of images like layers up to FullHD resolution.

    ATF is nice, but we have problem with quality.

    Here is investigation result in pdf with links on examples:

    Is there way to avoid fragments in future or now?


    Tuesday, November 20, 2012 at 3:12 pm #
  41. ericsoco wrote:

    Just wanted to say I’m seeing about a 150% performance increase using .atf over using .png, both in an Android emulator and on a Nexus 7.

    My test is animating 1000 Starling Image particles, each of which has a texture with alpha.

    Very nice, thanks for this!

    Sunday, December 9, 2012 at 7:39 am #
  42. Berend wrote:

    Hi Thibault,

    Thank you for the ATF tools! The performance is really great.

    Since I am only targetting iOS and Android, is it also possible to exclude DXT while using the -c parameter?

    Thursday, January 10, 2013 at 8:39 pm #
  43. Marius wrote:

    I have a 2D game using starling with png sprites.
    The collision tests inside the game are done with BitmapData.hitTest().

    How to convert ATF which is a ByteArray to BitmapData ?

    Thursday, February 7, 2013 at 12:23 am #
  44. phendrax wrote:


    the png2atf binary for linux 64 bit ends with a segmentation fault

    anyone else having this issue?

    Monday, February 11, 2013 at 5:51 pm #
  45. Peter wrote:

    If I use the cubemap option (-m) I get only black assets for Android and iOS (PVRTC, ETC1) formats. Is this a bug or is this feature only available for desktop (DXT)?

    Monday, March 4, 2013 at 4:36 pm #
  46. Hi Thibault.
    I’d like to get the binaries for Linux.
    But when getting the gaming SDK I only get the Mac OSX binaries which our linux server can’t execute.
    Would be great to have those accessible directly.

    Friday, May 16, 2014 at 2:54 pm #

Trackbacks/Pingbacks (7)

  1. Introducing the ATF | Flash Notes on Friday, October 19, 2012 at 10:20 pm

    [...] что вы хотели знать об ATF текстурах читайте в статье Introducing the ATF. Поделиться в соц. сетях Автор:VirtualMaestro Дата: [...]

  2. Stage3D developer tips « 岩屋(乐在其中) on Thursday, November 1, 2012 at 8:47 am

    [...] Stage3D compressed textures – Introducing the ATF SDK [...]

  3. Compressed Stage3D Textures With ATF « on Monday, November 5, 2012 at 12:01 pm

    [...] has recently released tools to allow us to use compressed textures with the Stage3D API via their ATF tools. What are [...]

  4. Compressed Stage3D Textures With ATF « on Monday, November 5, 2012 at 12:01 pm

    [...] has recently released tools to allow us to use compressed textures with the Stage3D API via their ATF tools. What are [...]

  5. [...] newly-released ATF tools have introduced an all-new image file format: ATF, the Adobe Texture Format. It’s not every [...]

  6. 使用ATF压缩Stage3D材质贴图 « Biz&IT Team on Tuesday, November 13, 2012 at 6:13 pm

    [...] 获取更多信息,请浏览ByteArray.org的文章,可以下载ATF tools并体验压缩材质。 |1|left November 14th, 2012 | Category: flashplayer [...]

  7. [...] job one this game, I seriously love the graphics. The game is powered by Starling and the team used ATF textures and project Monocle for performance optimizations and some ActionScript Native Extensions for [...]