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