On resource constrained systems, you can reduce your memory footprint by using C instead of Lua. Typically, the systems that require this type of configuration are running with a virtual filesystem (VFS) and are required to use the Storyboard Embedded Resource Header (C/C++) functionality of Storyboard. A gra.ccallback
action is used in place of gra.lua
action. In order to support faster development cycles, it is possible to use the C callback plugin in dynamic environments as well. The C callback plugin needs to be pointed to the (dll/so) with the option -occallback,path=[path to lib]. In the non VFS case, if the C callback action cannot find the requested function, it will fallback to Lua, to try and find a function with a matching name, this is to allow developers to use Lua to implement functionality quickly, then migrate the functionality into C once the desired behavior has been achieved.
On Windows the C callback dll must be compiled with the /MD
option to ensure that memory can be safely passed from Storyboard Engine to your dll and back. Use __declspec(dllexport)
to ensure that sb_ccallbacks can be accessed from the dll. Usually a macro is used for this in order to support building for other targets, as seen in the example below.
Here's an example of how we could take the ClusterIO
sample application and replace the Lua functionality with C. The action that is triggered by the cluster_update event should be changed from a gra.lua
to a gra.ccallback
action, it should call the same function as before, CBUpdateEvent. This library has a dependency on libgre
.
ClusterIO_ccallbacks.h
#include <stddef.h> #include <gre/gre.h> void cbClusterUpdate(gr_action_context_t *action_context); DLLExport const sb_ccallback_t sb_ccallbacks[] = { { "CBUpdateEvent", &cbClusterUpdate }, { NULL, NULL }, };
ClusterIO_ccallbacks.c
#include <stdio.h> #include <string.h> #include "ClusterIO_ccallbacks.h" #include <ClusterIO_events.h> #if defined(GRE_FEATURE_VFS_RESOURCES) #include <gre/sdk/sbresource_vfs.h> #endif void cbClusterUpdate(gr_action_context_t *action_context) { gr_application_t *app; cluster_update_event_t *cluster_data; gr_data_union_t data; void *event_data; int nbytes; app = gr_context_get_application(action_context); if(app == NULL) { return; } event_data = gr_context_get_event_data(action_context, &nbytes); if (nbytes != sizeof(cluster_update_event_t)) { return; } cluster_data = (cluster_update_event_t *)event_data; memset(&data, 0, sizeof(data)); data.i16 = cluster_data->speed; gr_application_set_data( app, "speedometer_content.speed.text", GR_DATA_FORMAT_2s1, &data ); data.f32 = ((float)cluster_data->speed * (214.0f / 200.0f)) - 107; gr_application_set_data( app, "speedometer.pointer_speedometer.rot", GR_DATA_FORMAT_4f1, &data ); data.f32 = ((float)cluster_data->rpm / 10000) * 49; gr_application_set_data( app, "tach_exterior.pointer_tach_exterior.rot", GR_DATA_FORMAT_4f1, &data ); }
You can specify labels to be exported to your C callback header file as defines. In the properties view, under Advanced, you will find the section called
, where the label can be specified. This field exists for Screens, Layer Instances, Groups, Tables and Controls.In the above example, the following would be exported into the .h file.
The C Callback Export Wizard can be opened by right-clicking a .gde file in the Navigator View, Storyboard Export > Storyboard C Callback Action Code Export (C/C++).
The C Callback export wizard allows you to select the .gde file, and choose the output path for the c/c++ and header files.
The exported .h file will contain all the C callback export labels given to model objects in your project as defines. The exported .c file will contain function stubs for all the C callback functions used in your application. Keep in mind that this export will overwrite anything you may already have in your file, so you should not point the exporter to your working copy.
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:
" ..../Crank Storyboard.exe" -application com.crank.gdt.ui.ccallback.application.ccallbackexport model=<PathToGDEFile> c=<PathToCFile> h=<PathToHFile>
Mac:
..../Storyboard.app/Contents/MacOS/Storyboard -application com.crank.gdt.ui.ccallback.application.ccallbackexport model=<PathToGDEFile> c=<PathToCFile> h=<PathToHFile>
Linux:
..../Storyboard -application com.crank.gdt.ui.ccallback.application.ccallbackexport model=<PathToGDEFile> c=<PathToCFile> h=<PathToHFile>
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.ccallback.application.ccallbackexport model=<PathToGDEFile> c=<PathToCFile> h=<PathToHFile>
Where the model
is the 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.