The Starling Manual

Before we go on, it might be interesting to know how much memory is required by a texture, anyway.

A PNG image stores 4 channels for every pixel: red, green, blue, and alpha, each with 8 bit (that makes 256 values per channel). It’s easy to calculate how much space a 512 × 512 pixel texture takes up:

When you’ve got a JPG image, it’s similar; you just spare the alpha channel.

Quite a lot for such a small texture, right? Beware that the built-in file compression of PNG and JPG does not help: the image has to be decompressed before Stage3D can handle it. In other words: the file size does not matter; the memory consumption is always calculated with the above formula.

Nevertheless: if your textures easily fit into graphics memory that way — go ahead and use them! Those formats are very easy to work with and will be fine in many situations, especially if your application is targeting desktop hardware.

However, there might come a moment in the development phase where your memory consumption is higher than what is available on the device. This is the right time to look at the ATF format.

Above, we learned that the file size of a conventional texture has nothing to do with how much graphics memory it uses; a massively compressed JPG will take up just as much space as the same image in pure BMP format.

This is not true for compressed textures: they can be processed directly on the GPU. This means that, depending on the compression settings, you can load up to ten times as many textures. Quite impressive, right?

Unfortunately, each GPU vendor thought he could do better than the others, and so there are several different formats for compressed textures. In other words: depending on where your game is running, it will need a different kind of texture. How should you know beforehand which file to include?

This is where ATF comes to the rescue. It is a format that Adobe created especially for Stage3D; actually, it is a container file that can include up to four different versions of a texture.

I wrote before that ATF is a container format. That means that it can include any combination of the above formats.

When you include all formats (which is the default), the texture can be loaded on any Stage3D-supporting device, no matter if your application is running on iOS, Android, or on the Desktop. You don’t have to care about the internals!

However, if you know that your game will only be deployed to, say, iOS devices, you can omit all formats except PVRTC. Or if you’re only targeting high end mobile devices (with at least OpenGL ES 3), include only ETC2; that works on both Android and iOS. That way, you can optimize the download size of your game.

Adobe provides a set of command line tools to convert to and from ATF and to preview the generated files. They are part of the AIR SDK (look for the atftools folder).

Probably the most important tool is png2atf. Here is a basic usage example; it will compress the texture with the standard settings in all available formats.

If you tried that out right away, you probably received the following error message, though:

That’s a limitation I have not mentioned yet: ATF textures are required to always have side-lengths that are powers of two. While this is a little annoying, it’s actually rarely a problem, since you will almost always use them for atlas textures.

When the call succeeds, you can review the output in the ATFViewer.

In the list on the left, you can choose which internal format you want to view. Furthermore, you see that, per default, all mipmap variants have been created.

You will probably also notice that the image quality has suffered a bit from the compression. This is because all those compression formats are lossy: the smaller memory footprint comes at the prize of a reduced quality. How much the quality suffers is depending on the type of image: while organic, photo-like textures work well, comic-like images with hard edges can suffer quite heavily.

The tool provides a lot of different options, of course. E.g. you can let it package only the PVRTC format, perfect for iOS:

Or you can tell it to omit mipmaps in order to save memory:

Another useful utility is called atfinfo. It displays details about the data that’s stored in a specific ATF file, like the included texture formats, the number of mipmaps, etc.

Using a compressed texture in Starling is just as simple as any other texture. Pass the byte array with the file contents to the factory method Texture.fromAtfData().

That’s it! This texture can be used like any other texture in Starling. It’s also a perfectly suitable candidate for your atlas texture.

However, the code above will upload the texture synchronously, i.e. AS3 execution will pause until that’s done. To load the texture asynchronously instead, pass a callback to the method:

Parameters two and three control the scale factor and if mipmaps should be used, respectively. The fourth one, if passed a callback, will trigger asynchronous loading: Starling will be able to continue rendering undisturbed while that happens. As soon as the callback has been executed (but not any sooner!), the texture will be usable.

Of course, you can also embed the ATF file directly in the AS3 source.

Note, however, that asynchronous upload is not available in this case.

You can find out more about this topic in the following sources:

When Starling recognizes that the current render context has been lost, it initiates the following procedures:

Restoring buffers and programs is not problematic; Starling has all data that’s required and it doesn’t take much time. Textures, however, are a headache. To illustrate that, let’s look at the worst case example: a texture created from an embedded bitmap.

The moment you call Texture.fromBitmap, the bitmap is uploaded to GPU memory, which means it’s now part of the context. If we could rely on the context staying alive forever, we’d be done now.

However, we cannot rely on that: the texture data could be lost anytime. That’s why Starling will keep a copy of the original bitmap. When the worst happens, it will use it to recreate the texture. All of that happens behind the scenes.

Lo and behold! That means that the texture is in memory three times.

Given the tight memory constraints we’re facing on mobile, this is a catastrophe. You don’t want this to happen!

It becomes a little better if you change your code slightly:

That way, Starling can recreate the texture directly from the embedded class (calling new Hero()), which means that the texture is in memory only two times. For embedded assets, that’s your best bet.

Ideally, though, we want to have the texture in memory only once. For this to happen, you must not embed the asset; instead, you need to load it from an URL that points to a local or remote file. That way, only the URL needs to be stored; the actual data can then be reloaded from the original location.

There are two ways to make this happen:

My recommendation is to use the AssetManager whenever possible. It will handle a context loss without wasting any memory; you don’t have to add any special restoration logic whatsoever.

Nevertheless, it’s good to know what’s happening behind the scenes. Who knows — you might run into a situation where a manual restoration is your only choice.

You might wonder how Texture.fromEmbeddedAsset() works internally. Let’s look at a possible implementation of that method:

You can see that the magic is happening in the root.onRestore callback. Wait a minute: what’s root?

You might not know it, but when you’ve got a Texture instance, that’s actually often not a concrete texture at all. In reality, it might be just a pointer to a part of another texture (a SubTexture). Even the fromBitmap call could return such a texture! (Explaining the reasoning behind that would be beyond the scope of this chapter, though.)

In any case, texture.root will always return the ConcreteTexture object, and that’s where the onRestore callback is found. This callback will be executed directly after a context loss, and it gives you the chance of recreating your texture.

In our case, that callback simply instantiates the bitmap once again and uploads it to the root texture. Voilà, the texture is restored!

The devil lies in the details, though. You have to construct your onRestore-callback very carefully to be sure not to store another bitmap copy without knowing it. Here’s one innocent looking example that’s actually totally useless:

Can you spot the error?

The problem is that the method creates a Bitmap object and uses it in the callback. That callback is actually a so-called closure; that’s an inline function that will be stored together with some of the variables that accompany it. In other words, you’ve got a function object that stays in memory, ready to be called when the context is lost. And the bitmap instance is stored inside it, even though you never explicitly said so. (Well, in fact you did, by using bitmap inside the callback.)

In the original code, the bitmap is not referenced, but created inside the callback. Thus, there is no bitmap instance to be stored with the closure. Only the assetClass object is referenced in the callback — and that is in memory, anyway.

That technique works in all kinds of scenarios:

Another area where a context loss is especially nasty: render textures. Just like other textures, they will lose all their contents — but there’s no easy way to restore them. After all, their content is the result of any number of dynamic draw operations.

If the RenderTexture is just used for eye candy (say, footprints in the snow), you might be able to just live with it getting cleared. If its content is crucial, on the other hand, you need a solution for this problem.

There’s no way around it: you will need to manually redraw the texture’s complete contents. Again, the onRestore callback could come to the rescue:

I hear you: it’s probably more than just one object, but a bunch of draw calls executed over a longer period. For example, a drawing app with a RenderTexture-canvas, containing dozens of brush strokes.

In such a case, you need to store sufficient information about all draw commands to be able to reproduce them.

If we stick with the drawing app scenario, you might want to add support for an undo/redo system, anyway. Such a system is typically implemented by storing a list of objects that encapsulate individual commands. You can re-use that system in case of a context loss to restore all draw operations.

Now, before you start implementing this system, there is one more gotcha you need to be aware of. When the root.onRestore callback is executed, it’s very likely that not all of your textures are already available. After all, they need to be restored, too, and that might take a while!

If you loaded your textures with the AssetManager, however, it has got you covered. In that case, you can listen to its TEXTURES_RESTORED event instead. Also, make sure to use drawBundled for optimal performance.

When you don’t need an object any longer, don’t forget to call dispose on it. Different to conventional Flash objects, the garbage collector will not clean up any Stage3D resources! You are responsible for that memory yourself.

ActionScript developers have always been used to embedding their bitmaps directly into the SWF file, using Embed metadata. This is great for the web, because it allows you to combine all your game’s data into one file.

We already saw in the Context Loss section that this approach has some serious downsides in Starling (or Stage3D in general). It comes down to this: the texture will be in memory at least two times: once in conventional memory, once in graphics memory.

Note that this sample uses Texture.fromEmbeddedAsset to load the texture. For reasons discussed in Context Loss, the alternative (Texture.fromBitmap) uses even more memory.

The only way to guarantee that the texture is really only stored in graphics memory is by loading it from an URL. If you use the AssetManager for this task, that’s not even a lot of work.

Starling’s Texture class is actually just a wrapper for two Stage3D classes:

The former (Texture) has a strange and little-known side effect: it will always allocate memory for mipmaps, whether you need them or not. That means that you will waste about one third of texture memory!

Thus, it’s preferred to use the alternative (RectangleTexture). Starling will use this texture type whenever possible.

However, it can only do that if you run at least in BASELINE profile, and if you disable mipmaps. The first requirement can be fulfilled by picking the best available Context3D profile. That happens automatically if you use Starling’s default constructor.

The last parameter (auto) will tell Starling to use the best available profile. This means that if the device supports RectangleTextures, Starling will use them.

As for mipmaps: they will only be created if you explicitly ask for them. Some of the Texture.from…​ factory methods contain such a parameter, and the AssetManager features a useMipMaps property. Per default, they are always disabled.

We already talked about ATF Textures previously, but it makes sense to mention them again in this section. Remember, the GPU cannot make use of JPG or PNG compression; those files will always be decompressed and uploaded to graphics memory in their uncompressed form.

Not so with ATF textures: they can be rendered directly from their compressed form, which saves a lot of memory. So if you skipped the ATF section, I recommend you take another look!

The downside of ATF textures is the reduced image quality, of course. But while it’s not feasible for all types of games, you can try out the following trick:

You’ll still save a quite a bit of memory, and the compression artifacts will become less apparent.

If ATF textures don’t work for you, chances are that your application uses a comic-style with a limited color palette. I’ve got good news for you: for these kinds of textures, there’s a different solution!

You can use this format in Starling via the format argument of the Texture.from…​ methods, or via the AssetManager’s textureFormat property. This will save you 50% of memory!

Naturally, this comes at the price of a reduced image quality. Especially if you’re making use of gradients, 16 bit textures might become rather ugly. However, there’s a solution for this: dithering!

To make it more apparent, the gradient in this sample was reduced to just 16 colors (4 bits). Even with this low number of colors, dithering manages to deliver an acceptable image quality.

Most image processing programs will use dithering automatically when you reduce the color depth. TexturePacker has you covered, as well.

The AssetManager can be configured to select a suitable color depth on a per-file basis.

Mipmaps are downsampled versions of your textures, intended to increase rendering speed and reduce aliasing effects.

Since version 2.0, Starling doesn’t create any mipmaps by default. That turned out to be the preferable default, because without mipmaps:

On the other hand, activating them will yield a slightly faster rendering speed when the object is scaled down significantly, and you avoid aliasing effects (i.e. the effect contrary to blurring). To enable mipmaps, use the corresponding parameter in the Texture.from…​ methods.

As already discussed, TextFields support two different kinds of fonts: TrueType fonts and Bitmap Fonts.

While TrueType fonts are very easy to use, they have a few downsides.

Bitmap Fonts, on the other hand, are

That makes them the preferred way of displaying text in Starling. My recommendation is to use them whenever possible!

It should be your top priority to pack your texture atlases as tightly as possible. Tools like TexturePacker have several options that will help with that:

Make use of this! Packing more textures into one atlas not only reduces your overall memory consumption, but also the number of draw calls (more on that in the next chapter).

Adobe Scout is a lightweight but comprehensive profiling tool for ActionScript and Stage3D. Any Flash or AIR application, regardless of whether it runs on mobile devices or in browsers, can be quickly profiled with no change to the code — and Adobe Scout quickly and efficiently detects problems that could affect performance.

With Scout, you can not only find performance bottlenecks in your ActionScript code, but you’ll also find a detailed roundup of your memory consumption over time, both for conventional and graphics memory. This is priceless!

Here is a great tutorial from Thibault Imbert that explains in detail how to work with Adobe Scout: Getting started with Adobe Scout.

The statistics display (available via starling.showStats) includes information about both conventional memory and graphics memory. It pays off to keep an eye on these values during development.

Granted, the conventional memory value is often misleading — you never know when the garbage collector will run. The graphics memory value, on the other hand, is extremely accurate. When you create a texture, the value will rise; when you dispose a texture, it will decrease — immediately.

Actually, just about five minutes after I added this feature to Starling, I had already found the first memory leak — in the demo app. I used the following approach:

Needless to say: Scout offers far more details on memory usage. But the simple fact that the statistics display is always available makes it possible to find things that would otherwise be easily overlooked.

Even though we’re picking a simple goal, it should be a useful one, right? So let’s create a ColorOffsetFilter.

You probably know that you can tint any vertex of a mesh by assigning it a color. On rendering, the color will be multiplied with the texture color, which provides a very simple (and fast) way to modify the color of a texture.

The math behind that is extremely simple: on the GPU, each color channel (red, green, blue) is represented by a value between zero and one. Pure red, for example, would be:

On rendering, this color is then multiplied with the color of each pixel of the texture (also called "texel"). The default value for an image color is pure white, which is a 1 on all channels. Thus, the texel color appears unchanged (a multiplication with 1 is a no-op). When you assign a different color instead, the multiplication will yield a new color, e.g.

And here’s the problem: this will only ever make an object darker, never brighter. That’s because we can only multiply with values between 0 and 1; zero meaning the result will be black, and one meaning it remains unchanged.

That’s what we want to fix with this filter! We’re going to include an offset to the formula. (In classic Flash, you would do that with a ColorTransform.)

We already have the multiplier, since that’s handled in the base Mesh class; our filter just needs to add the offset.

So let’s finally start, shall we?!

All filters extend the class starling.filters.FragmentFilter, and this one is no exception. Now hold tight: I’m going to give you the complete ColorOffsetFilter class now; this is not a stub, but the final code. We won’t modify it any more.

That’s surprisingly compact, right? Well, I have to admit it: this is just half of the story, because we’re going to have to write another class, too, which does the actual color processing. Still, it’s worthwhile to analyze what we see above.

The class extends FragmentFilter, of course, and it overrides one method: createEffect. You probably haven’t run into the starling.rendering.Effect class before, because it’s really only needed for low-level rendering. From the API documentation:

The FragmentFilter class makes use of this class, or actually its subclass called FilterEffect. For this simple filter, we just have to provide a custom effect, which we’re doing by overriding createEffect(). The properties do nothing else than configuring our effect. On rendering, the base class will automatically use the effect to render the filter. That’s it!

More complicated filters might need to override the process method as well; that’s e.g. necessary to create multi-pass filters. For our sample filter, though, that’s not necessary.

Finally, note the calls to setRequiresRedraw: they make sure the effect is re-rendered whenever the settings change. Otherwise, Starling wouldn’t know that it has to redraw the object.

Time to do some actual work, right? Well, our FilterEffect subclass is the actual workhorse of this filter. Which doesn’t mean that it’s very complicated, so just bear with me.

Let’s start with a stub:

Note that we’re storing the offsets in a Vector, because that will make it easy to upload them to the GPU. The offset properties read from and write to that vector. Simple enough.

It gets more interesting when we look at the two overridden methods.

Our filter is ready, actually (download the complete code here)! Time to give it a test ride.

Blimey! Yes, the red value is definitely higher, but why is it now extending beyond the area of the bird!? We didn’t change the alpha value, after all!

Don’t panic. You just created your first filter, and it didn’t blow up on you, right? That must be worth something. It’s to be expected that there’s some fine-tuning to do.

It turns out that we forgot to consider "premultiplied alpha" (PMA). All conventional textures are stored with their RGB channels premultiplied with the alpha value. So, a red with 50% alpha, like this:

would actually be stored like this:

And we didn’t take that into account. What he have to do is multiply the offset values with the alpha value of the current pixel before adding it to the output. Here’s one way to do that:

As you can see, we can access the xyzw properties of the registers to access individual color channels (they correspond with our rgba channels).

The goal is just the same as the one we were shooting for with the ColorOffsetFilter; we want to allow adding an offset to the color value of every rendered pixel. Only this time, we’re doing it with style! We’ll call it …​ ColorOffsetStyle.

Before we continue, it’s crucial that you understand the difference between a filter and a style.

The base class for all styles is starling.styles.MeshStyle. This class provides all the infrastructure we need. Let’s look at a stub first:

That’s our starting point. You’ll see that there’s already going on a little more than in our initial filter class from the last example. So let’s have a look at the individual parts of that code.

We’re done with the style class now — time to move on to the effect, which is where the actual rendering takes place. This time, we’re going to extend the MeshEffect class. Remember, effects simplify writing of low-level rendering code. I’m actually talking about a group of classes with the following inheritance:

The base class (Effect) does only the absolute minimum: it draws white triangles. The FilterEffect adds support for textures, and the MeshEffect for color and alpha.

So let’s look at the setup of our ColorOffsetEffect, with a few stubs we’re filling in later.

If you compare that with the analog filter effect from the previous tutorial, you’ll see that all the offset properties were removed; instead, we’re now overriding vertexFormat, which ensures that we are using the same format as the corresponding style, ready to have our offset values stored with each vertex.

There you have it: we’re almost finished with our style! Let’s give it a test-ride. In a truly bold move, I’ll use it on two objects right away, so that we’ll see if batching works correctly.

Hooray, this actually works! Be sure to look at the draw count at the top left, which is an honest and constant "1".

There’s a tiny little bit more to do, though; our shaders above were created assuming that there’s always a texture to read data from. However, the style might also be assigned to a mesh that doesn’t use any texture, so we have to write some specific code for that case (which is so simple I’m not going to elaborate on it right now).

The complete class, including this last-minute fix, can be found here: ColorOffsetStyle.as.

That’s it with our style! I hope you’re as thrilled as I am that we succeeded on our task. What you see above is the key to extending Starling in ways that are limited only by your imagination. The MeshStyle class even has a few more tricks up its sleeve, so be sure to read through the complete class documentation.

I’m looking forward to seeing what you come up with!

We had plenty of birds in this manual already, so let’s go for a predator this time! My cat qualifies for the job. I’ve got her portrait as a black vector outline, which is perfect for this use-case.

Unfortunately, Starling can’t display vector images; we need Seven as a bitmap texture (PNG format). That works great as long as we want to display the cat in roughly the original size (scale == 1). However, when we enlarge the image, it quickly becomes blurry.

This is exactly what we can avoid by converting this image into a distance field texture. Starling actually contains a handy little tool that takes care of this conversion process. It’s called the "Field Agent" and can be found in the util directory of the Starling repository.

I started with a high-resolution PNG version of the cat and passed that to the field agent.

This will create a distance field texture with 25% of the original size. The field agent works best if you pass it a high resolution texture and let it scale that down. The distance field encodes the details of the shape, so it can be much smaller than the input texture.

The original, sharp outline of the cat has been replaced with a blurry gradient. That’s what a distance field is about: in each pixel, it encodes the distance to the closest edge in the original shape.

The amount of blurriness is called spread. The field agent uses a default of eight pixels, but you can customize that. A higher spread allows better scaling and makes it easier to add special effects (more on those later), but its possible range depends on the input image. If the input contains very thin lines, there’s simply not enough room for a high spread.

To display this texture in Starling, we simply load the texture and assign it to an image. Assigning the DistanceFieldStyle will make Starling switch to distance field rendering.

With this style applied, the texture stays perfectly crisp even with high scale values. You only see small artifacts around very fine-grained areas (like Seven’s haircut).

Depending on the "spread" you used when creating the texture, you might need to update the softness parameter to get the sharpness / smoothness you’d like to have. That’s the first parameter of the style’s constructor.

The characteristics of distance field rendering make it perfect for text. Good news: Starling’s standard bitmap font class works really well with the distance field style. By now, there are even great tools for creating suitable font textures.

Remember, a bitmap font consists of an atlas-texture that contains all the glyphs and an XML file describing the attributes of each glyph. You can’t simply use field agent to convert the texture in a post-processing step (at least not easily), since each glyph requires some padding around it to make up for the spread. Therefore, it’s best to use a bitmap font tool that supports distance field textures natively.

Some of the GUI-tools I described in the Bitmap Fonts chapter can be configured to create distance field output. However, to be blunt, none of them does that job particularly well. If you are not afraid of some command line magic, I recommend another one instead.