A Storyboard application can be exported in several different ways. The output of the export process is what is considered a Storyboard Deployment Bundle. Depending on the bundle packaging these can be ran by sbengine, installed on an iOS/Android based mobile platform, executed on Windows as a normal application, or used by the user to compile into their RTOS application.
In the past deployment exports were done through a few different export wizards, but as of Storyboard 5.0 these have been consolidated into a single export configuration system. This export system allows the user to create, save, and share their application export parameters. These configurations can be customized through the dialog.
To export a Storyboard Deployment Bundle, right-click the Storyboard application file (*.gde) and select , and choose the deployment type.
An export can also be launched by clicking on the button in the toolbar. This button will launch the first export configuration found for the current application, or create one if none exist.
The dialog will appear the first time an application is exported for deployment. This dialog allows you to customize how the application is exported and can be accessed at any time by clicking on the button in the toolbar.
The export dialog is separated into sections that take you through the required elements of an export.
- Application Model To Export
-
The first export parameter block is the selection of which application model file
(*.gde)files to export. Selecting more than one will cause these files to be merged when exporting the deployment bundle. - Configuration Location
-
The second export parameter block determines where the configuration for the export will be stored. If the storage location is "Workspace" then the configuration is only accessible to that workspace. If the storage location is marked as "Project", then the configuration is accessible to anyone who has access to the project.
- Export Packaging
-
The third export parameter block determines how the exported model should be packaged. These packages and their options are described below.
- Export Transfer
-
The final export parameter block is where the packaged content should be saved or transferred. Currently, transfer methods include copy the package to the local filesystem or transferring it to a target over the network using
scp. The transfer methods and their options are described below.
Once the user has finished customizing their export configuration they can click the Apply button to save the configuration and the export can be launched by click on the Run button. The application will then be exported according to the configuration.
All of the resources used by the application (images, fonts, scripts, translation files etc) must be available at runtime and included in the bundle packaging. The exporter will automatically select common resources but the packaged content can be customized using the "Resource Configuration" tab of the export wizard.
The options that are available for resources on export are controlled through the packaging method that is chosen on the "Storyboard Export Parameters" pane. For all of the packagers, with the exception of the CHeader export packager, the only options available for the resources are:
-
The model file can be exported as condensed.
-
Script files can be exported as pre-compiled or raw.
-
Individual resources can be excluded from the export.
The "Add Resource" button will allow for a resource that is not listed to be added to the list of resources that are to be exported with the project. The "Add Font" button will allow for a font that is not currently listed to be added to the list of fonts that are to be exported with the project.
The "Application Footprint Preview" shows the memory and storage requirements required for the resources that are listed for export.
For the CHeader export packager, there are additional options that can be specified for the resources that are being exported by the project. For each of the resources, an export prefix and an export postfix can be supplied to wrap around the declaration of the variables for the data for the resources. By default the variable declaration looks like this in the header file:
const unsigned char res_1[] = { <resource_data> };
If a macro needs to wrap the declaration to export the data in a particular region on the device or store it with a particular alignment, then the export prefix and the export postfix can be used together to wrap the declaration. For example, if the macro is SDK_ALIGN(<variable>, 64) then the export prefix would be set to "SDK_ALIGN(" and the export postfix would be ",64)". This would declare the variable as:
SDK_ALGIN(const unsigned char res_1[], 64) = {<resource_data>};
If the macro applies attributes or pragmas to the variable declaration then the export prefix and export postfix can be used independently to place the macro at the beginning for pragmas or at the end of the declaration for attributes. For example, if the macro BSP_PLACE_IN_SECTION(".qspi_flash") uses attributes to place the data in the ".qspi_flash" section defined in the linker file for the project, then export prefix would be set to BSP_PLACE_IN_SECTION(".qspi_flash") and that would result in the variable being declared as such:
const unsigned char res_1[] BSP_PLACE_IN_SECTION(".qspi_flash") = {<resource_data>};
The export prefix and export postfix can be set globally for each of the resource types by clicking on the resource type entry in the tree view. The export prefix and the export postfix can be set individually on a specific resource by selecting that resource in the tree.
Additionally, when the CHeaderPackager is used, a string map can be generated. This is a static string map and strings that are in the static string map will not consume heap memory from RAM. To export a static string map, select the model from the list of resources and check the "Generate a static string map" option. Note that Designer does it's best to guess which strings will be used. For a more accurate representation see the metrics plugin event option to dump the string pool when a specific event is received.
In addition to the export prefix and export postfix, there are additional settings that can be applied to image resources and font resources when the CHeader export packager is used.
Global Image Export Options
For images the format that the images are exported in can be selected, the image data start alignment and the image stride alignment can be set. The image start alignment will pad the image header for the direct draw images (not applicable for the native setting) so that the image data start address is aligned to the supplied byte alignment. The image stride alignment can be used to align the stride of the images when they are exported as a direct draw (not applicable for the native setting) to the value specified.
The format that the images are exported as can also be set. The formats that can be chosen are:
-
Native Format - This option exports the image in its native compressed format. This will require the image to be decompressed into heap memory in order to be drawn.
-
Direct RGB8888 - This option exports the image as uncompressed data and the image will be drawn directly from its storage location on the device. The increases storage requirements but reduces the amount of heap required to draw the image. This format is not usable with the VGLite render manager as alpha will not show up properly.
-
Direct RLE RGB8888 - This option exports the image as a run-length encoded stream of data. This reduces the amount of storage required to store the image data, as well as reduces the amount of heap required by the image but will impact the performance of drawing the image as each time the image is drawn it will need to be decoded. This format is not usable with the VGLite render manager as alpha will not show up properly.
-
Direct Premultiplied Alpha RGB8888 - This option exports the image as uncompressed data and will modify the RGB values to have the alpha applied to them ahead of time. This increases the storage requirements for the image but reduces the amount of heap required to draw the image. Currently only usable by the VGLite render manager.
-
Direct RGB565 - This option converts the image to the RGB565 format and allows for it to be drawn directly from the storage location on the device. This reduces the amount of storage and heap required for the image but also reduces the color fidelity of the image which can result in a banding effect on gradient colors.
-
Direct RGB565 Dithered - This option is the same as the Direct RGB565 option, but attempts to reduce any color banding that may occur in the image by applying a color correction throughout the image.
-
Direct Indexed - This export option stores the image as an indexed image and allows for it to be drawn directly from the device storage location. This reduces the amount of storage required for the image and reduces the heap required for the image, but reduces the colors that can be used in the image to only those that are in the index. This option is currently only available on select runtimes. Contact support for more information.
-
Direct RLE Indexed - This export option is the same as the Direct Indexed option but run-length encodes the index values in the image. This reduces the image storage requirements even further than those required for the Direct Indexed but will come with a performance penalty as the image will need to be decoded on every draw of the image. This option is currently only available on select runtimes. Contact support for more information.
The export format can be overridden from the global value for each individual image. Select the individual image from the tree and then select the export format for that image. If the Direct RGB565 or the Direct RGB565 Dithered option is selected as the global option, then images that contain alpha in them will have their export format option changed to Direct RLE RGB8888 or Direct RGB8888, whichever is smaller, to preserve the alpha. If you wish to override this, then any image that has alpha in it, that is to be exported as Direct RGB565 or Direct RGB565 Dithered will need to have the export format set individually on each image.
Global Font Export Options
For fonts, the export format governs what options are available for exporting fonts. There are two formats that can be selected, the TTF font format and the Bitmap font format. The TTF font format will reduce storage requirements but will require more memory to render glyphs from the fonts. This option is good when the application has a lot of dynamic text to be rendered. The bitmap font format requires more storage but reduces the amount of memory required to render fonts. This option is useful when the application has a lot of known static text.
The TTF format is used when using the FreeType font manager with the engine. When using this format there are no other additional options for the fonts that can be selected.
If the Bitmap format is selected then there are two additional options that can be applied globally for the fonts. The first is the export format for the glyphs. This determines the number of bits used to represent the alpha values for the glyphs. The values that can be chosen are 8, 4, 2, 1. Reducing the number of bits will reduce the size required to store the bitmap fonts. The second is the map width for the fonts. When the bitmap font manager is used with the engine, the glyphs for the font are prerendered into an alpha map. This option allows the user to specify the width of that map. There is a check box to allow making the map width the same size as the widest glyph, which effectively makes the map a strip of glyphs.
For individual font sizes, when using the bitmap font format, there are additional options around controlling which glyphs are actually exported to the header file.
The glyph range can be sent to all the glyphs in the font, all the glyphs that are found in the currently selected model, or a range that has been specified. The "Select glyphs to export" button will open the following dialog which will allow for the selection of glyphs to export to the header file.
Also, for individual font sizes, the map size and the export format for the glyphs can be set to something different than the global values.
This will export the application as a GAPP file. The application resources will be transferred along with the GAPP file. This is the default package when exporting a new application.
Export the application as a compressed package. The exported .sbp file will contain the application resources that were selected.
Export the application as a Android Native Application. The exported .apk file will contain the application resources that were selected.
The following are parameters available for the Native Android Application export
- Application Parameters
-
These parameters allow the user to change the application name, the APK file name, the application UID, and the application version information. Other parameters allow the user to change the application orientation, scaling, and whether the status bar is shown.
- Application Name
-
The name that will appear on your device's UI for the app. This name doesn't have to be unique
- Android Package File Name
-
This is the name of the apk file that is exported. This name has no effect once your application is installed.
- Android Unique Application Identifier
-
This ID uniquely identifies your app on the device and in Google Play Store. It looks like a Java package name (ie. com.example.myapp).
- Runtime Parameters
-
This is where the user specifies the Storyboard Runtime to export in the APK. The user can also specify runtime options here.
- Manifest Parameters
-
Here the user can set their shared object list and add additional permissions to the Android manifest file.
- Icon Parameters
-
Here the user can set the icons for the application.
Export the application as a iOS Application. The exported .app file will contain the application resources that were selected. This option is only available on MacOS development platforms and requires that the iOS mobile development environment be configured prior to export. This configuration is discussed in the chapter Exporting to iOS Devices.
The following are parameters available for the Native iOS Application export
- Application Parameters
-
These parameters allow the user to change the application name, the company identifier, the signing identity and provisioning profile. Other parameters allow the user to change the application orientation, scaling, whether the status bar is shown.
- Runtime Parameters
-
This is where the user specifies the Storyboard Runtime to export in the app. The user can also specify runtime options here.
- Icon Parameters
-
Here the user can set the icons and launch screens for the application. There are different images for different types of iOS devices, i.e. iPhone, iPhone retina, iPad, iPad retina.
Export the application as a standalone Windows application. The exported .exe file will contain the application resources that were selected.
Export the application as a set of C/C++ header files. This will export one or more header files that can be used in conjunction with a Storyboard Engine that was built for an MCU, which generally requires a direct compilation of the Storyboard application into the system image. There are a number of parameters available for this export for the resources which are explained in the resource section of this section. For which options should be selected for a particular platform, consult the Storyboard Engine integration guide for that MCU platform
The following are parameters available for the C/C++ Resource Header export:
Model Header
This is the file that will contain the exported gapp file data and variable definition.
Images Header
This is the file that will contain all the image data and variable definitions for the images.
Fonts Header
This is the file that will contain all the font data and variable definitions for the fonts.
Scripts Header
This is the file that will contain all the script data and variable definitions for the scripts.
Other Header
This is the file that will contain all of the data and variable definitions for any other files that have been added to the resource list.
C Callbacks Header
This will contain a map of C callback names to symbol names.
If images, fonts, scripts, and other header files are all set to the same header file, then the variable definitions will all be mapped into a structure name sb_model_resources. If individual files are picked for the resources, the variables will be prefixed with the resource type, for example, "images_" and the structure will be named after the specific resource type, for example, sb_model_image_resources.
Copy the deployment bundle to a directory on the filesystem. The user can choose to export to the project directory or select another directory on the filesystem to copy to. This is the default transfer method when exporting a new application.
Copy the deployment bundle to a target via scp. The user needs to enter the target address (either hostname, IP address or mDNS service name eg: 'mydevboard.local' if supported), the username and password, and the target directory they want to copy to. Selecting the Post Transfer Script option will allow the user to execute a script on their target post launch. This could be used to launch the application they exported.
After running a export the scp parameters will be saved as a global workspace preset that could be used with future exports. Currently only 10 presets are saved at a time.
It is also possible to perform headless exports of the Storyboard Design files to the Storyboard Embedded Engine files from a command line or scripting environment.
All of the Storyboard executables will be located in the PATH_TO_INSTALL/Storyboard_Designer directories, though on each desktop platform they are named slightly differently
Windows:
"..../Crank Storyboard.exe" -application com.crank.gdt.ui.gappexport -data <PathToWorkspace>
model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
output=<PathToGAPPFile>
Mac:
..../Storyboard.app/Contents/MacOS/Storyboard -application
com.crank.gdt.ui.gappexport -data <PathToWorkspace>
model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
output=<PathToGAPPFile>
Linux:
..../Storyboard -application com.crank.gdt.ui.gappexport -data <PathToWorkspace>
model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
output=<PathToGAPPFile>
Note: Storyboard requires a display, so to run in a true headless environment a Virtual frame buffer needs to be set up.
Xvfb :1 -ac -screen 0 1024x768x8 export DISPLAY=:1
..../storyboard -application com.crank.gdt.ui.gappexport -data <PathToWorkspace>
model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
output=<PathToGAPPFile>
Where the model is the path to the Storyboard Designer model file. In the situation where multiple GDE model files are being joined together, it is a comma-separated list of model files where the first model file will be used for the start screen and the remaining models will be used for additional content. The output parameter specifies the filesystem path where the Storyboard Engine file will be created and the directory containing that file will be used for the additional resource directories (scripts, images and fonts). The data option can be used to specify the path to the workspace that contains the Storyboard project.
If the GDE file that is being selected for export does not reside in the workspace that is going to be used by the command-line exporter, then the export configuration must be stored in the project. This is an option that is available when modifying the export configuration. The following picture illustrates the selection that needs to be made:
Note that the "Configuration Location" option is set to "Project". If the project resides in the same workspace that the command line exporter will be using, the configuration can be stored in either the workspace or the project. Also, the data option can be used to set the workspace to use to look up the projects.
By default, the exported gapp file will be compacted and not in a readable format. If a more readable format is desired, then the readable parameter can be passed along the command line such as:
..../Storyboard -application com.crank.gdt.ui.gappexport -data <PathToWorkspace>
readable
model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
output=<PathToGAPPFile>
It is also possible to perform a headless export using a pre-configured export configuration. After configuring the export in Designer a user can export this from the command line or scripting environment.
All of the Storyboard executables will be located in the PATH_TO_INSTALL/Storyboard_Designer/storyboard directories, though on each desktop platform they are named slightly differently
Windows:
..../Storyboard.exe -application com.crank.gdt.ui.configexport
model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
configuration=<ConfigurationName>
Mac:
..../Storyboard.app/Contents/MacOS/Storyboard -application
com.crank.gdt.ui.configexport
model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
configuration=<ConfigurationName>
Linux:
..../Storyboard -application com.crank.gdt.ui.configexport
model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
configuration=<ConfigurationName>
Note: Storyboard requires a display, so to run in a true headless environment a Virtual frame buffer needs to be setup.
Xvfb :1 -ac -screen 0 1024x768x8 export DISPLAY=:1
..../storyboard -application com.crank.gdt.ui.configexport
model=<PathToGDEFile[,PathToAdditionalGDEFile,...]>
configuration=<ConfigurationName>
Where the model is the full path to the Storyboard Designer model file. This model file will be used to search for a export configuration. The configuration parameter specifies the configuration name. If this is provided then only the configuration with that name will be used in the export.
-data Is used to specify the workspace to be used when performing the export. This workspace should not be opened by other instances of Storyboard. This is helpful when running the configexport option in order for Storyboard to find your export configurations in your project. It is specified as follows:
..../Storyboard.exe -application com.crank.gdt.ui.configexport -data <PathToWorkspace> model=<PathToGDEFile[,PathToAdditionalGDEFile,...]> configuration=<ConfigurationName>
-consoleLog Is used to enable additional logging to the console.
-noExit Is used to prevent the application from closing automatically after performing the export. This is sometimes useful to keep the log console open post-mortem.