What are C Callbacks?

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.

C Callbacks on Windows

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.

Example C Callback

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.


#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 },


#include <stdio.h> 
#include <string.h> 
#include "ClusterIO_ccallbacks.h"  
#include <ClusterIO_events.h>  

#include <gre/sdk/sbresource_vfs.h> 

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) {      

    event_data = gr_context_get_event_data(action_context, &nbytes);  

    if (nbytes != sizeof(cluster_update_event_t)) {   
    cluster_data = (cluster_update_event_t *)event_data;
    memset(&data, 0, sizeof(data));

    data.i16 = cluster_data->speed;  

    data.f32 = ((float)cluster_data->speed * (214.0f / 200.0f)) - 107;

    data.f32 = ((float)cluster_data->rpm / 10000) * 49;  

C Callback Export Labels

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 C Callback Export, 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.

Exporting C Callbacks

C Callback Export Wizard

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.

C Callback Command Line Export

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


" ..../Crank Storyboard.exe" 
-application com.crank.gdt.ui.ccallback.application.ccallbackexport
model=<PathToGDEFile> c=<PathToCFile> h=<PathToHFile>


-application com.crank.gdt.ui.ccallback.application.ccallbackexport 
c=<PathToCFile> h=<PathToHFile>


-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     
-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.

Was this article helpful?
0 out of 0 found this helpful