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.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request



Article is closed for comments.