The Storyboard Resource Export Configuration editor provides the ability to create configurations for how resources should be exported from Designer. This allows for fine grained control over how and when resources should be exported from the design environment.
The Resource Export Configuration editor allows for the creation, deletion, and resetting of a configuration. The following toolbar controls these operations.
The combo box allows for the selection of a configration.
The add button will invoke a dialog that allows for the creation of a new configuration. The following dialog is invoked
A name needs to be entered for the new configuration. The name must be unique. You can select a base configuration to base the new configuration off of. This will make a copy of the options that have been applied to the resources in the base configuration and apply them in the new configuration. When finished click on the "OK" button to create the new configuration or the "Cancel" button to abort the creation of the new configuration.
The delete button will remove the currently selected configuration. Note that the default configuration cannot be deleted.
The revert button will reset all of the options on the resources to their default values.
The resource tree allows for the selection of individual resources so that options can be changed on individual resources.
The filter allows for the searching of resources based on name.
The tree is grouped by each of the different resource types, images, fonts, scripts, and other. There is a right-click menu that can be invoked that will allow for the creation, deletaion, and reverting of the current configuration. It also allows for the generation of image maps if the image map option is selected. References to currently selected resource can also be searched for in the model.
The "Add Resource" button at the button of the tree allows for the addition of resources that are not in the images, fonts or scripts directories. The "Add Font" button allows for the addition of a font that is shipped by Designer. If the storage type for the configuration is "VFS" and the font export format is "Bitmap" the a size can also be selected for the font.
Resource options are set at a global level and at an individual level. All resources will use the global setting for an option if the option is not changed at the individual level. This allows for a quick set of options for the general case of how a resource should be exported and also allows for more granular control over individual resources that need to be exported in a different way.
For example, most images in an application may have alpha. So in a VFS configuration, most images should probably be exported in the "DIRECT RGB8888" format. However, for a big background image that has no alpha, it may make sense to export the image as the "DIRECT RGB565" format to save on space.
If images are being exported as "DIRECT RGB565" and an image contains alpha, the image export format is converted to "DIRECT RGB8888" and the resource marked as having a different configuration than the default.
There are two options that are applied to the configuration, the name and the storage type. The name must be unique and the "Default" configuration cannot be renamed. All of the global options are mirrors of the individual options that can be set on an individual resource. There are global options and individual resources for images, fonts, and scripts.
The options for Storage Type are:
This exports resources to a filesystem. This selection disables the need for a majority of the options on the resources as they are loaded and interpreted from the filesystem based on the type of resource. The exception to this rule is script files as they can be exported as compiled scripts to a filesystem.
- Virtual Filesystem
This exports resources in a virtual filesystem format. This selection is only available for use with the C Header exporter. This enables a majority of the options as the C Header export is used with systems that have constrained resources.
When the VFS format is selected there are options to specify a Global Export Prefix and a Global Export Postfix. The prefix string is placed in front of each resource declaration that is exported, and the postfix string is placed after each resource declaration that is exported. Either one or the other, or both can be used. By using both together it is possible to encapsulate a resource declaration in a macro which can be used to declare that the resources are aligned when compiled into an application.
When the VFS format is selected as the storage type, the following options are enabled for the configuration:
Font Export Format
Image Export Format
Image Start Alignment
Image Stride Alignment
Image Map Width
Script Export Format
Font Export Format
Font export format is a global option as the mixing of bitmap and TrueType font configurations is not currently supported. The choices for the font export format are:
This exports all fonts as a TTF file. This file requires the TrueType font manager to be used. Each TTF file that is needed is loaded into memory and the glyphs that are used are stored in a cache in the heap.
This exports each individual glyph in a font file as an alpha map. The size of each individual pixel in the alpha map can be controlled through the Font Bitmap Depth option.
When Font Export Format is set to Bitmap, the Font Bitmap Depth and Font Glyph Map Width options are enabled.
The font bitmap depth option is something that can be controlled on each individual font size resource as larger sizes may take up more space. The choices for font bitmap depth are:
- 1 Bit
This exports the bitmap font as an alpha map that has 1 bit per pixel in the alpha map. This bit determines whether a pixel should be on or off.
- 2 Bits
This exports the bitmap font as an alpha map that has 2 bits per pixel in the alpha map. These 2 bits represent the alpha value that should be used for that pixel
- 4 Bits
This exports the bitmap font as an alpha map that has 4 bits per pixel in the alpha map. These 4 bits represent the alpha value that should be used for that pixel
- 8 Bits
This exports the bitmap font as an alpha map that has 8 bits per pixel in the alpha map. These 8 bits represent the alpha value that should be used for that pixel
The Font Glyph Map Width option can be set on each individual font size and controls how wide a glyph map width can be. It is useful if a system has alignment restrictions when rendering buffers. The Max Glyph Width checkbox sets the glyph map width to the width of the largest glyph in the font. This creates a single strip of glyphs in the glyph map.
Image Export Format
The Image Export Format option allows the following image export formats:
- Native Format
This exports the image in its native format, such as a PNG or JPEG. This requires the image to be decoded at runtime which requires a heap.
- Direct RGB8888
This exports the image as an uncompressed image that has 32 bits per pixel. This image can then be drawn directly from storage without the need for heap.
- Direct RLE RGB8888
This exports the image as a run-length encoded image that has 32 bits per pixel. This image can then be drawn directly from storage without the need for heap, but requires the pixels to be expanded as it is being drawn, which may incur a performance hit. In most cases, this takes up less space.
- Direct Premultiplied Alpha RGBA8888
Currently only supported by the VGLite render manager. This pre-mutiplies the alpha before storing the image as a direct draw image.
- Direct RGB565
This exports the image as an uncompressed image that has 16 bits per pixel. This image can then be drawn directly from storage without the need for heap. The image takes up less space than the DIRECT RGB8888 but it does not support alpha. Also, gradients may show banding due to a reduction in color fidelity.
- Direct RGB565 Dithered
This exports the image as an uncompressed image that has 16 bits per pixel that have been dithered. This image can then be drawn directly from storage without the need for heap. The image takes up less space than the DIRECT RGB8888 but it does not support alpha. Gradients should not have banding due to the dithering.
- Direct Indexed
This exports the image as an uncompressed image that is palette-based. This image can then be drawn directly from storage without the need for heap. The image takes up less space than the DIRECT RGB8888. Colors may look different because they are matched to colors in the palette.
- Direct RLE Indexed
This exports the image as a run-length encoded image that is palette-based. This image can then be drawn directly from storage without the need for heap, but requires the pixels to be expanded as it is being drawn, which may incur a performance hit. In most cases, this takes up less space.
Image Start Alignment
The Image Start Alignment option specifies the alignment used for the image data in any of the direct rendering image format options.
Image Stride Alignment
The Image Stride Alignment option aligns the stride of any direct draw images to the specified value.
Image Map Width
The Image Map Width option can be set individually on image maps. This sets the width that the image map uses. The height of the image map is set to whatever is required to fit all images in the image map.
Script Export Format
The Script Export Format option controls how Lua scripts are exported. The options are:
This exports the script file as plain text. It will need to be compiled by the Lua engine when it is loaded.
This precompiles the Lua file when it is exported so that the Lua engine does not need to do it at runtime.
Additionally, each resource has an Include in Export option. If this option is unchecked, the resource is omitted from the export.
Selecting an individual resource from the tree allows the options for that individual resource to be overridden from the global settings. Also, the resource can be excluded from the export. For fonts, there is an option to Select Glyphs to Export for the selected font size.
When a font is exported using the Bitmap format instead of a TTF format, you can use thebutton in the Resource export options to bring up a window that allows you to pick specific sets of glyphs from a font to export. This saves space in memory by including only the glyphs you know will be used.
Along with the direct glyph selection dialog, the Existing Glyph Range drop-down allows you to select every glyph in the font, and select ranges that you’ve already defined at a different font size.
The Glyph Selection window displays all the glyphs that are included in the font and provides you with controls to select from them. Glyphs included in the model itself are highlighted with a darker blue (Storyboard Light theme) or a lighter green (Storyboard Dark theme).
You can click and drag over ranges of glyphs as they are displayed in the window to select/deselect them. Thebutton allows you to deselect all the glyphs that aren’t included in the model and the button selects every glyph in the font.
You can enter a string of text into the Add Glyphs From String text box to make sure they’re included in the export. Specific ranges of glyphs can also be added using the Add A Range control, which gives a few predefined ranges and allows you to enter your own ranges, using Unicode values or the characters themselves.
This preview provides feedback on how much memory or storage an resource export configuration will take up when it is used. For more information, see the Metrics view topic.