meta data for this page
  •  

Callback system

New to version 8.5.0 is a centralized callback system. In prior versions, each system had a different callback interface. In this new approach, the callback registration system is housed in Include/SpeedTree/Core/Callbacks.h. There are nine callbacks that can be registered, though each drops back to a default definition if not set (the callbacks are located in Source/Core/Source/Callbacks.cpp):

Callback function Description
SpeedTree::Callbacks::Message() The SDK calls this function when it wants to communicate a non-error message to the client application.
SpeedTree::Callbacks::Error() The SDK calls this function when an error message needs to be communicated to the client.
SpeedTree::Callbacks::HeapAlloc() All SDK-internal heap allocations are routed through this function.
SpeedTree::Callbacks::HeapFree() All SDK-internal heap free calls are routed here.
SpeedTree::Callbacks::GetFileSize() Given a string filename, this function will return the size of that file in bytes.
SpeedTree::Callbacks::LoadBinaryFile() Given a string filename and a buffer, this function will read a binary file and fill the provided buffer with its contents.
SpeedTree::Callbacks::UserRenderPipeline() During graphics initialization, this function helps determine which shaders and render states should be applied based on various parameters. This is described in more detail in User Render Configuration.
SpeedTree::Callbacks::DirectMemAlloc() Used by some non-desktop platforms for GPU memory allocation.
SpeedTree::Callbacks::DirectMemFree() Used by some non-desktop platforms for GPU memory freeing.

Note that due to DLL interface constraints, these functions cannot be set directly but are set through access functions. An example of setting a callback appears in the listing below. 

#include <cstdio>
#include "Core/Callbacks.h"
 
// example callback functions to show expected function parameters
 
// message callback
void MyMessageCallback(const char* pMsg) { printf("SpeedTree SDK Message: [%s]\n", pMsg); }
 
// error callback
void MyErrorCallback(const char* pError) { fprintf(stderr, "SpeedTree SDK Error: [%s]\n", pError); }
 
// heap allocation callback
void* MyHeapAllocCallback(size_t siSizeInBytes, size_t siAlignment) { return malloc(siSizeInBytes); }
 
// heap free callback
void MyHeapFreeCallback(void* pBlock) { if (pBlock) free(pBlock); }
 
// file size callback prototype
size_t MyFileSizeCallback(const char* pFilename);
 
// load binary file callback prototype (returns true on success)
bool MyLoadFileCallback(const char* pFilename, void* pBuffer);
 
 
// example use
void main(void)
{
    // assign example callbacks
    SpeedTree::Callbacks::Message() = MyMessageCallback;
    SpeedTree::Callbacks::Error() = MyErrorCallback;
    SpeedTree::Callbacks::HeapAlloc() = MyHeapAllocCallback;
    SpeedTree::Callbacks::HeapFree() = MyHeapFreeCallback;
    SpeedTree::Callbacks::GetFileSize() = MyFileSizeCallback;
    SpeedTree::Callbacks::LoadBinaryFile() = MyLoadFileCallback;
 
    // to test one, we can manually invoke an error callback with
    SpeedTree::CCore::Error("an error... we've just experienced an error");
}