Library
Overview
The Stream Cache Server library provides all the necessary functionality to build a custom Stream Cache Server application. This functionality encompasses the following features:
Designating CAD model source directories to stream from.
Determining if rendering should be allowed on the client, the server, or both.
Controlling the logging output of the Stream Cache Server.
Hosting a WebSocket to communicate with the HOOPS Web Viewer.
Streaming CAD model data to the HOOPS Web Viewer.
This functionality is also provided by the ts3d_sc_server.exe application that ships with HOOPS Communicator. This is our newer Stream Cache Server that works with our NodeJS based server system.
These applications may be sufficient for most streaming needs, but if custom behavior is required, then the Stream Cache Server library can be utilized as an alternative.
Building your application
To build an application with the Stream Cache Server library, you’ll need to include the header file (sc_server.h) and link the application against the dynamic library (sc_server.dll). Note that the library does depend on other dynamic libraries from within the same directory.
Note
For more information on the location of these files in your HOOPS Communicator package, consult our Package Description page.
Using the library
The typical steps for creating an application that uses the Stream Cache Server library are:
Create an instance of the configuration object
SC::Server::StreamCacheServer::Config
and set all configuration settings as needed for your environment.Create an instance of
SC::Server::StreamCacheServer
.Call the
SC::Server::StreamCacheServer.Init
function of the Stream Cache Server object, passing it the Config object from step 2.Loop until an exit condition has been determined. Each cycle of the loop should call the
SC::Server::StreamCacheServer.Tick
function on the Stream Cache Server object.Exit the loop. Call the
SC::Server::StreamCacheServer.Stop
function on the Stream Cache Server object.Destroy the Stream Cache Server object
Note that while the Stream Cache Server internally uses multiple threads, the Stream Cache Server class is not thread-safe, and therefore all steps as described above must be performed from the same thread.
Working example
The following example shows a minimal but fully working version of a Stream Cache Server using the Stream Cache Server library. This example follows the steps outlined in the previous section.
The example sets the SC::Server::StreamCacheServer::Config.onDisconnect
callback via the configuration settings to a lambda function that triggers the SC::Server::StreamCacheServer.Tick
loop to exit. The function specified by SC::Server::StreamCacheServer::Config.onDisconnect
will be called when the connected HOOPS Web Viewer is closed or encounters an inactivity timeout.
#include <sc_server.h>
#include <iostream>
int
test_stream_cache_server(const char* your_license_key)
{
// Create the Config object and set important values
SC::Server::StreamCacheServer::Config config;
config.port = 9999;
config.modelSearchDirs = "/my-model-dir;/my-other-model-dir";
config.license = "<valid-hoops-license-string>";
// Setup the exit handler. The disconnect handler is called when the HWV
// closes or times out.
bool runTickLoop = true;
config.onDisconnect = [&](const std::string& message) { runTickLoop = false; };
// Create and initialize the server
SC::Server::StreamCacheServer server;
std::string error;
auto initOk = server.Init(config, error);
if (!initOk) {
std::cerr << "Failed to initialize server: " << error << std::endl;
return 1;
}
// Let the server perform it's streaming tasks until it indicates it's
// done via the earlier 'onDisconnect' callback
while (runTickLoop) {
server.Tick();
}
// Let the server do any cleanup
server.Stop();
return 0;
}
Configuration callbacks
The SC::Server::StreamCacheServer::Config
includes members that hold callback functions for logging and other useful notifications. These members are optional and can be left unset. To utilize a callback, assign the configuration setting field to either a C++ lambda function or a std::function wrapper that matches the type signature of that function, as follows:
// Function signature used for the libwebsockets logging callback
using LwsLogCallback = std::function<void(int level, const char* message)>;
// Function signature used for Stream Cache logging callbacks
using MessageCallback = std::function<void(const std::string& message)>;
// Function signature used for Stream Cache data callbacks
using DataCallback = std::function<void(uint32_t rx, uint32_t tx)>;
// Function signature used for Stream Cache notification callbacks
using NotifyCallback = std::function<void()>;
This is an example that uses the SC::Server::StreamCacheServer::MessageCallback
type with a C++ lambda to print any errors reported by the Stream Cache to stdout.
config.onError = [](const std::string& message) {
std::cout << message << std::endl;
};
Configuration settings reference
The following list details all configuration settings available in the SC::Server::StreamCacheServer::Config
object. The server configuration is fixed upon calling the init() function, thus changing configuration values after initialization is not supported.
port - The networking port used for WebSocket communications with the HOOPS Web Viewer. This value must be in the range 1 <= port <= 32767. Default: 0
enabledRenderingLocations - Determines if the client and/or server rendering is allowed. It’s valid to set either mode or both. The web-viewer will request the type of rendering when it first connects, and will only be successful if the matching type has been enabled with this setting. Default: RenderingLocationClient
license - A valid HOOPS Communicator license must be specified. Default: empty string
memoryDevice - An optional Stream Cache memory device which is used for sandboxing file I/O within application memory. See sc_store.h for the MemoryDevice type declarations. If this is set to a valid memory device, the paths defined by SC::Server::StreamCacheServer::Config.workspaceDir
and SC::Server::StreamCacheServer::Config.modelSearchDirs
must point to directories within this device. If it is nullptr, then those directories will be interpreted within the standard filesystem.Default: nullptr
workspaceDir - An optional path to a directory that will be used for temporary storage. If this setting is the empty string, the current working directory will be used. Default: empty string
modelSearchDirs - A list of directory paths to be used when searching for a model file. This is a single string with each directory path concatenated and using a single semi-colon character to separate each path. Default: empty string
modelFile - An optional relative file path that, when set to a non-empty string, will override any model requested by the web-viewer client. This should be a model file name that exists within the specified SC::Server::StreamCacheServer::Config.modelSearchDirs setting. ie. “bnc”. Default: empty string
sessionToken - An optional token that must be shared with the web-viewer client. The string is simply compared for equality against the session token provided by the client, thus there is no format specification. Default: empty string
sslCertificateFile - A file path to an SSL certificate, which is needed to support the ‘wss’ protocol. If this is the empty string, SSL is not used. Default: empty string
sslPrivateKeyFile - A file path to an SSL private key, which is needed to support the ‘wss’ protocol. If this is the empty string, SSL is not used. Default: empty string
ssrGpuIndex - Optional 0-based index for specifying which GPU to be used. If set to std::numeric_limits<uint32_t>::max(), then the server will use the default GPU.Default: std::numeric_limits::max()
ssrEgl - When this option is enabled, EGL will be used to create the GL context if performing ssr rendering. Enabling this option removes the need for an X server to be running for hardware accelerated Server Side rendering. This option is reccomended on headless server environments and is currently only supported on Linux.
exitOnLoadFinish - Indicates that the stream cache should exit after a model has been loaded and streamed to the HOOPS Web Viewer. Default: false
tickTimeout - Indicates the amount of time that the SC::Server::StreamCacheServer.Tick
function will sleep for after performing a work cycle. The value here will set the internal default used by the tick() function when it is called with no arguments. This value can be overridden for any given tick() call by providing an explicit value to the timeout function parameter. A negative value will result in the tick() call not sleeping in any way after the work cycle. Default: 1 millisecond
kickOnNewConnection - When true, this indicates that this Stream Cache session should allow a new web-viewer connection to take priority over the existing connection. If this happens, the existing connection will be closed, and the new connection can proceed. When this is false, the existing connection will be unaffected and the new connection will be denied. Default: false
verboseLogging - If true, increased diagnostic messages will be sent to the onDebug callback. Default: false
lwsLogLevel - This will set the enabled log-levels for the internal libwebsocket library. It should be a bitwise-or of LwsLogCategory
values. Default: LwsLogCategoryNone
onLwsMessage - Optional function that will receive the libwebsocket log messages that were enabled by the lowLogLevel setting. Default: empty
onError - Optional function that will receive error-category log messages. Default: empty
onWarning - Optional function that will receive warning-category log messages. Default: empty
onInfo - Optional function that will receive info-category log messages. Default: empty
onDebug - Optional function that will receive debug-category log messages. Default: empty
onTrace - Optional function that will receive trace-category log messages. Default: empty
onDisconnect - Optional function that will be called when a client disconnects. The message indicates why the client disconnected. Conditions that can cause this include 1) the HOOPS Web Viewer browser window is closed or 2) the HOOPS Web Viewer encounters a timeout out due to inactivity. Default: empty
onData - Optional function that will be called periodically with incremental data transmit and receive statistics. Default: empty
onInitialUse - Optional function that will be called upon the initial HOOPS Web Viewer connection. Default: empty