Introduction

The main feature of the framework is the DecalSheet system (located in the camo.core.decal package); made up of Sheet and Decal classes. The DecalSheet concept was inspired by the decals you would get with model airplanes. Each model kit would contain sheets of graphics and on each sheet you could peal off a decal and place it on the model. Camo’s version of the DecalSheet allow you to load in external images, cut out decals, and skin you application with the Decals. The following diagram will help when explaining the relationship between the three classes:

Details

DecalSheets

The DecalSheet is the manager for the decal system. It handles the xml that defines a list of sheet images and coordinates for cutting out each Decal. Once this data is set, the DecalSheet goes out and gets all the images it needs for the Sheet images.

The DecalSheet makes use of a special load manager called the BitmapLoadManager (camo.core.managers). This class automatically goes out an loads anything flagged to be preloaded. Once the images are loaded, the DecalSheet is ready to be used. If a page is not flagged to be preloaded but is requested, it will be added to the load queue. Decals can still be requested before the page images are fully loaded. The DecalSheet will use a Decal’s width and hight to generate a proxy graphic (a temporary black placeholder graphic) that will be replaced once the corresponding Sheet has been loaded.

Sheet

Loaded images get stored inside of a Dictionary within the DecalSheet as individual Sheets. Each Sheet’s key come from its id defined in the XML. At any time you can get a Sheet by calling getSheet. The Sheet extends the AbstractCamoBitmap and inherits the sample method. When you request a sample, you must pass it a Rectangle that defines the x, y, width, and height of the area to cut out. BitmapData is return and in the case of a DecalSheet, that BitmapData is then placed into the constructor of a new Decal. Lets take a look at some sample xml for setting up a DecalSheet:

<decalsheet>
	<sheets baseURL="images"/>
		<sheet id="skin" preload="true" w="550" h="126">skin.gif</sheet>
	</sheets>
	<decals>
		<decal id="play_up" sheet="skin" x="97" y="1" w="47" h="52"/>
		<decal id="play_over" sheet="skin" x="145" y="1" w="47" h="52"/>
		<decal id="bg" sheet="skin" x="417" y = "1" w="26" h="52" 
scale9Grid="1,1,24,50"/>
	</decals>
</decalsheet>   

Sample DecalSheet XML

The above DecalSheet XML is broken up into two main nodes, one for Sheets and the other for Decals. Each Sheet node contains an id (unique reference name), preload (true or false), w (width) and h (height) attributes along with the path to file. On Startup, the DecalSheet requests a list of all the sheet nodes flagged to be preloaded and begins loading each src image. The baseURL attribute, located in the sheets node, is added to the url of each page’s src when making the load request. You can leave this empty and point each src directly to an absolute url if your images are not located in the same directory. The decals node defines how each decal should be cut out. A decal node has an id (unique name for lookups), page (name of page where decal will be cut out from¹ ), x, y, w, and h. There is also a special attribute called scale9Grid that can be used for defining resize scaling instructions.

To use this XML, simply pass it into a DecalSheetConfig’s constructor which in turn gets passing into a DecalSheet’s constructor. DecalSheets store the DecalSheetConfig instance (accessible through the config getter) that parses and manages the DecalSheet xml. Lets take a look at how Sheets and Decal extend the AbstractCamoBitmap.

AbstractCamoBitmap

Every class that extends the AbstractCamoBitmap has access to the sample method. The only parameter it accepts is a Rectangle that defines the area to copy BitmapData from. The DecalSheetConfig manages converting decal node attributes into usable data by creating a DecalConfig (camo.core.configs).

The inheritance tree for AbstractCamoBitmap, Sheet, CamoBitmap and Decal.

DecalConfig

In Camo, Config classes (camo.core.configs) help parse, store, organize and manipulate complex data like xml and objects. All config classes extend the AbstractConfig which provides two functions: dump (tracing out the properties of a class to the console or output window for debugging) and clone (used to create a copy of the instance’s properties and values). This notion of taking an Object or XML, putting it inside of a config class, and having a main class typed to the config is an important concept used throughout the framework

Decal

So now you have seen how we get xml data into a DecalSheet, lets talk about how to retrieve Decal instances. When you call getDecal, you pass in the id of a Decal so the DecalSheet’s template can create its corresponding DecalConfig. You can check if a decal exists by calling the DecalSheet’s hasDecal method. Once a Decal is requested, the DecalSheet takes the DecalConfig, looks up its page id, and creates a new Decal instance. The diagram below illustrates the process:

This shows how a Decal is sampled from a Sheet by using the coordinates of a DecalConfig.

A Decal is a special type of CamoBitmap that contains a reference to the Sheet it was cut out from. This connection allows the Decal to receive updates from its parent Sheet. Since the Sheet extends the Bitmap class, you can change its BitmapData at any time. Decals listen for CHANGE events from their parent Sheet and once an event is received, it resamples the Sheet and updates the Decal’s BitmapData². Imagine being able to reskin an entire application by changing the BitmapData in a single Decal Sheet Page? All the Sheet’s children will atomically refresh. Here is a diagram to illustrate how this works:

Changing the BitmapData of a Sheet will fire a COMPLETE event telling all children Decals to update.

With Flash Camouflage’s DecalSheet system, you can reduce your applications memory footprint by consolidating smaller images into larger sheets. Any graphic you would embed in a class or place in a FLA’s library can be stored in a single DecalSheet and be spread over multiple Sheets depending on your needs³. Since Sheets can be set up to only load when requested, you can load in application graphics exactly when you need them; cutting down the initial startup and load time.

^{1 The framework handles looking up sheets by name so it should refer to the sheet’s id defined in the xml. Sheet id names should be unique to avoid conflicts.}

^{2 The Decal’s detach method will remove the connection to its parent Sheet.}

^{3 When it comes to designing your decal sheets, you should consider grouping images that do not have transparency into single jpg or gif image. Images with transparency should be grouped together as pngs. Since pngs are larger, it helps to break these sheets up as small as possible in the order of importance. This will help cut down on load times and optimize the streaming in of your Sheets.}