-
Notifications
You must be signed in to change notification settings - Fork 1.5k
ImageAsset Guide
All assets are known engine types that allow instances to be created at runtime. The "ImageAsset", like all assets, is derived from a base type of "AssetBase". That means it includes all the fields from that type as well as adding its own fields specific to itself.
The ImageAsset provides a way to refer to a single image file and produce logical frames that represent areas within the image itself. It can represent a single frame or an unlimited number of frames. Each frame is referenced using a zero-based index.
For an ImageAsset to be valid, it must contain at least a single frame i.e. frame #0.
The ImageAsset type exposes the following fields in addition to those it inherits:
- ImageFile
- CellCountX
- CellCountY
- CellWidth
- CellHeight
- CellStrideX
- CellStrideY
- CellOffsetX
- CellOffsetY
- CellRowOrder
- FilterMode
- Force16bit
- ExplicitMode
In the list above, only "ImageFile" is mandatory, all others are completely optional.
Here's an example of the most basic form of an ImageAsset where only the mandatory "ImageFile" field is specified:
<ImageAsset
AssetName="Gems"
ImageFile="Gems.png"
/>This would produce an asset known as "Gems" and produce a single texture from the image "Gems.png" which it expects to be located alongside where the XML ImageAsset file is. There is no need to make the asset name match the image name but it can make keeping the relevant files together on disk easier with an alphabetic file sort.
The following is a complete description of each of these fields.
This is the only mandatory field for the type. It should refer to an image file that the engine can load. It is not essential to add the file extension here as the engine will attempt different extensions for you that it knows it can load (it'll try what you originally specified, then add a ".png" then a ".jpg").
If the image file could not be found or loaded then the asset is still generated however internally it is flagged as invalid.
You can refer to sub-folders here but using a format like:
<ImageAsset
AssetName="Gems"
ImageFile="artwork/Gems.png"
/>Do not use the "." to indicate the current folder as this is already implicitly assumed. You can however use ".." to indicate a parent folder but it is highly discouraged to store artwork in parent folders.
When a valid image file is found, this is used when the asset is eventually required. The image file is loaded and uploaded as a single texture. To do this, the image size must be supported by your graphics card as each graphics cards has a size limit for textures.
For the image to be uploaded as a texture however it must be a power-of-two in size but Torque 2D will internally re-size it if this is not the case so that it can be uploaded. Torque 2D will not modifie the image on the disk, it does this in-memory prior to uploading as a texture so the change is completely volatile. It also has to do this whenever the asset is loaded from disk and so whilst the process is very fast, it does waste a little time but more importantly is wasted memory on the graphics card. It also only adds extra space to the right and bottom of the image, it does not rescale or change the image in any way so this change is completely transparent but is done purely for the benefit of the graphics card.
If you turn-on the "metrics" on your SceneWindow i.e. something like 'SandboxScene.setDebugOn("metrics")' and look at the category "Textures", you'll see several entries that show you metrics like how many textures are resident on the graphics card, their total estimated size in bytes, how much main memory is used with images loaded into (ImageAsset releases its bitmaps so no need to worry about that) and finally how much waste their is on textures resident on the graphics card. Texture waste is the "space" that was created to resize the original image into a texture that was is a power-of-two in size. If your image was already a power-of-two in size then it will produce no waste so that's the optimal case.
Torque 2D does not perform any packing of textures like legacy Torque 2D. This was a major cause of performance and memory issues in that produce, especially on lower-end devices. All those problems have been removed. Texture packing and ensuring that the images loaded are now in the hands of artists and other content pipeline products.
If you don't specify any "Cell" fields or don't use the "Explicit" mode described below then the ImageAsset will assume that the whole image is a single frame. This makes defining "full frame" images used for things like backgrounds extremely easy.
However, it's a very common practice to divide the image into a regular grid of "cells". All the "Cell" fields allow you to configure this grid of cells.
The "CellCountX" and "CellCountY" control how many of these cells there are in the horizontal and vertical axis respectively. These two fields multiplied together state how many frames are expected e.g a "CellCountX" of "5" and "CellCountY" of "10" would together produce fifty frames.
Controlling how many frames in the horizontal and vertical directions is the start however it's also vital that you configure the width and height of each cell. This is what "CellWidth" and "CellHeight" do.
So for example, if you have the following:
<ImageAsset
AssetName="Gems"
ImageFile="Gems.png"
CellCountX="8"
CellCountY="8"
CellWidth="64"
CellHeight="64" />.. then it would be defining an asset named "Gems" with 8 x 8 frames (64) where each frame is a square 64x64 pixels.
You can see this asset in the codebase:
It's important to remember that whilst the overall image size needs to be a power-of-two for upload to your graphics card as a texture, cell width or cell height can be anything from a single pixel to as wide or tall as the image. Also, this example shows a 64x64 pixel cell size but the width and height don't have to be the same, you could have 1x50, 3x927, 321x33 etc.
The fields "CellCountX", "CellCountY", "CellWidth" and "CellHeight" are used in combination and none should be omitted if any of the others are used i.e. they must all be used together. If you only want a single frame then don't specify any of them and a single full-image frame is assumed in that case.
Typical cells are assumed to be next to each other i.e. the cell grid has no "spaces" in-between the cells. If this isn't the case then you can control how the ImageAsset steps or "strides" from cell to cell in both the horizontal and vertical.
By default, if you don't specify "CellStrideX" or "CellStrideY", the ImageAsset automatically sets them to be the "CellWidth" and "CellHeight" respectively.
This means that you can set them to be whatever you like. For instance, if each next cell in the horizontal has a single pixel space (gutter) in-between them then you want to set the "CellStrideX" to be the "CellWidth" plus one. The same would go for any configuration in the vertical using "CellStrideY".
Here's an example of that: