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.

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
                           ); 
}                 

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.

c_callback_export_label.png

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

Comments

0 comments

Article is closed for comments.