Documentation

SpeedTree Runtime SDK

Version: 10

SpeedTree Runtime SDK

Version: 10

Callback system

The Runtime SDK has a centralized callback system.
Read time 2 minutesLast updated 2 hours ago

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 Runtime SDK calls this function when it wants to communicate a non-error message to the client application.
SpeedTree::Callbacks::Error()
The Runtime SDK calls this function when an error message needs to be communicated to the client.
SpeedTree::Callbacks::HeapAlloc()
All Runtime SDK-internal heap allocations are routed through this function.
SpeedTree::Callbacks::HeapFree()
All Runtime 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 callbackvoid MyMessageCallback(const char* pMsg) { printf("SpeedTree Runtime SDK Message: [%s]\n", pMsg); }// error callbackvoid MyErrorCallback(const char* pError) { fprintf(stderr, "SpeedTree Runtime SDK Error: [%s]\n", pError); }// heap allocation callbackvoid* MyHeapAllocCallback(size_t siSizeInBytes, size_t siAlignment) { return malloc(siSizeInBytes); }// heap free callbackvoid MyHeapFreeCallback(void* pBlock) { if (pBlock) free(pBlock); }// file size callback prototypesize_t MyFileSizeCallback(const char* pFilename);// load binary file callback prototype (returns true on success)bool MyLoadFileCallback(const char* pFilename, void* pBuffer);// example usevoid 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");}