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:

This functionality is also provided by two applications that ship with the HOOPS Communicator:

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.

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:

  1. Create an instance of the configuration object SC::Server::StreamCacheServer::Config and set all configuration settings as needed for your environment.
  2. Create an instance of SC::Server::StreamCacheServer.
  3. Call the SC::Server::StreamCacheServer.Init function of the Stream Cache Server object, passing it the Config object from step 2.
  4. 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.
  5. Exit the loop. Call the SC::Server::StreamCacheServer.Stop function on the Stream Cache Server object.
  6. 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
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
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 table 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.

Setting Description
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<uint32_t>::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