Extension plug-ins provide details about settings available through Viz Engine and Viz Script. Extension plug-ins are similar to normal plug-ins, but they are loaded during Viz Engine startup and are alive until shutdown (where regular plug-ins are bound to the scene lifetime). It is possible to provide data or services for scripts and plug-ins or control Viz Engine.

This section contains information on the following topics:

Lifecycle

The extension plug-ins have a different lifecycle then normal plug-ins. They are loaded on startup and life until Viz Engine shuts down. This allows extension plug-ins to provide all kind of services which are not necessarily bound to a scene.

images/download/attachments/158761059/image2021-1-28_13-9-24.png

Communication

There are many ways to communicate with an Extension. One of the most common ways is to use SHM. The extension can provide data by reading/writing the key/values of Viz Engine SHM.

Another method introduced with these Extensions is the Message API which is described below. SHM API and Message API are provided by Viz Engine, but there are many other methods like using a socket connection.

Message API

The Message API is similar to a REST API. A service/extension can provide multiple endpoints and clients can request data by sending requests to such endpoints. Like the REST API, such endpoints are described by a path. Extension endpoints are prefixed with /Extensions/<extension-name>. For example, the extension named Greetings could have an endpoint greet which could be requested with /Extensions/Greetings/greet.

A message request can be sent from plug-ins or extensions and consists of the endpoint and a message body (which can be empty). Viz Engine then dispatches those messages to the corresponding extensions. The extension then responds with a message which is dispatched by Viz Engine back to the plug-in/script.

The whole communication is asynchronous. Requests can be sent from any thread. PLUGIN_REQUEST/PLUGIN_RESPONSE callbacks are always called on the main thread. This way of communicating also allows extensions to not immediately respond to requests. Furthermore, it is possible to send a response without receiving requests. This is useful to provide some kind of notification mechanism.

Sample Extension

The simple extension plug-in with Message support to greet. This plug-in responds to any Message received with "Hello <request-message>".

#include <PluginLib/evPlugin_PLUGINEXTERN.h>
#include <PluginLib/evPlugin_Extensions.h>
#include <Pluginlib/evPlugin_PLUGINFUNC.h>
#include <Pluginlib/evPlugin_DynInterface.h>
#include <Pluginlib/api_functions.h>
 
struct PLUGIN_DATA
{
};
 
VIZPLUGIN_API int
PLUGIN_INIT_EX()
{
    // Register plugin
    evRegisterPlugin("SampleExtension");
    evRegisterPluginFolder("Extension");
    evRegisterPluginType(EV_EXTENSION);
 
    evRegisterPluginUACfolders();
 
    evRegisterTotalSize(sizeof(PLUGIN_DATA));
 
    return 0;
}
 
VIZPLUGIN_API void
PLUGIN_INIT_FUNCTION(void* pvDataPtr)
{
    new (pvDataPtr)(PLUGIN_DATA)();
}
 
VIZPLUGIN_API void
PLUGIN_CLEANUP_FUNCTION(void* pvDataPtr)
{
    auto pluginPtr = reinterpret_cast<PLUGIN_DATA*>(pvDataPtr);
    pluginPtr->~PLUGIN_DATA();
}
 
VIZPLUGIN_API
void PLUGIN_REQUEST(void* pvDataPtr, int senderId, const char* location, const char* msg)
{
    auto pluginPtr = reinterpret_cast<PLUGIN_DATA*>(pvDataPtr);
	std::string response = std::string("Hello ") + msg;
    _api__respond(senderId, location, response.c_str());
}

Sample Plug-in

A Viz Engine plug-in that communicates with the Sample Extension above. On initialization, a message request is sent to the extension and the response set to the plug-in parameter Output, which can be viewed in Viz Artist.

The output is "Hello Plugin".

struct PLUGIN_DATA
{
    char* output;
};
 
VIZPLUGIN_API void PLUGIN_INIT()
{
    evRegisterPlugin( "SamplePlugin" );
    evRegisterPluginFolder( "Sample" );
    evRegisterPluginType( EV_FUNCTION_CONTAINER );
    evRegisterPluginUACfolders();
 
    evRegisterParameterText("Output", "", 400, 600);
    evRegisterTotalSize(sizeof(PLUGIN_DATA));
}
 
VIZPLUGIN_API void PLUGIN_INIT_FUNCTION(void *dataptr)
{
    // cast dataptr to our parameter structure
    auto data = (struct PLUGIN_DATA*)dataptr;
    new (data) PLUGIN_DATA;
 
    auto pluginObjectId = _api__get_plugin_objectid();
    _api__request(pluginObjectId, "/Extensions/SampleExtension", "Plugin");
}
 
VIZPLUGIN_API void PLUGIN_RESPONSE(void* pvDataPtr, const char* location, const char* msg)
{
    struct PLUGIN_DATA* data = (struct PLUGIN_DATA*)pvDataPtr;
    std::strcpy(data->output, msg);
    evSendGuiRefresh();
}

Sample Script

Similar to the Sample plug-in, this script sends a message request to the extension.

The output is:

"/Extensions/SampleExtension"

"Hello Script"

Request("/Extensions/SampleExtension", "Script")
 
sub OnResponse(location as string, message as string)
	Println(location)
	Println(message)
end sub

Feedback and Suggestions

We encourage suggestions and feedback about our products and documentation. To give feedback and/or suggestions, please contact your local Vizrt customer support team at www.vizrt.com.

Viz Plug-ins User Guide

Extension Plug-ins