C

Render Plugins

Qt 3D Studio provides a mechanism for compositing an external OpenGL ES application plugin as a texture at runtime. This document describes how this is done.

Requirements

In general, the initialization and rendering portions of the plugin must be modified to be driven by the runtime.

First, the plugin application needs to be converted into a dynamic library. The extension of the dynamic library should be .dll for Windows, and .so for Linux. (See further instructions in the Usage section below.)

Second, the functions in the header file (UICPluginDLL.h) need to be implemented by the plugin.

The following list is a description of these functions and what they need to do. The order the functions are listed here also represents the expected calling sequence of these functions.

long GetPluginType( )

This must return EDLLTYPE\_RENDERABLE\_PLUGIN.

void Initialize( const char* inArgs )

This function should do any initialization (data setup, geometry and texture uploads, etc.) required by the plugin. It will be called when the dynamic library is loaded during runtime startup.

void Uninitialize( )

This function should do any uninitialization (free memory, close files, etc) required by the plugin. It will be called when the viewer is exited.

void GetDesiredTextureSize( long* outWidth, out* outHeight, ETEXTUREFORMAT *outTextureFormat )

The plugin should set outWidth and outHeight to its desired rendering size, and set the texture format to one of:

  • ETEXTUREFORMAT\_ANY
  • ETEXTUREFORMAT\_RGB565
  • ETEXTUREFORMAT\_BGR565
  • ETEXTUREFORMAT\_RGB888
  • ETEXTUREFORMAT\_BGR888

void SetAllocatedRenderInfo( long inFBO, long inRBO, long inTex, ETEXTUREFORMAT inTextureFormat )

The runtime uses this function to send the framebuffer, renderbuffer and texture handles used for rendering. The plugin should store these and activate them when rendering. Note that the data within these handles are shared resources, and may be modified between calls to Render( ).

[Optional] void SetEGLInfo( void* inEGLdisplay, void* inEGLCurrentContext, void* inEGLSurface, void* inEGLConfig )

The runtime uses this function to send information about the current EGL environment. The plugin should store these parameters and use them in EGLCreateContext and EGLMakeCurrent.

Implementing this function is necessary when using EGLMakeCurrent for state management.

void Render( long inHostWidth, long inHostHeight, long inDrawTime )

The runtime calls this whenever it requires a frame from the plugin. The plugin should render its results into the texture handle provided by SetAllocatedRenderInfo. The parameters, inHostWidth and inHostHeight represent the current dimensions of the host rectangle, and may be useful for clipping/scaling optimizations. The parameter inDrawTime represents the current frame time in milliseconds.

State Management

The plugin should manage its OpenGLES state properly so that it does not affect the runtime. There are two approaches that can be adopted.

  • In the first approach, the plugin creates its own EGLContext to contain its state. It should switch to this context during Render() and switch back to the runtime's context before returning from Render().

Switching contexts is slow but might be favorable if the plugin spends a lot of time rendering or doing complex state changes.

  • The second approach is to share the OpenGL state between the runtime and the plugin. The plugin is responsible for restoring state changes it makes during Render( ). However, the shader program, framebuffer and viewport settings will be restored by the runtime automatically, as these are most likely to have changed. This approach is faster than switching contexts and is probably suitable for simpler applications that do not make many state changes or when maximum speed is desired.

Usage

The procedure for using plugins is very similar to that used for Sub Presentations.

After converting the plugin into a dynamic library, the .uia file should be modified to specify the dynamic library as a <renderplugin> asset. The src="..." attribute should point to the dynamic library. For example:

<application xmlns="http://nvidia.com/uicomposer">
  <assets>
    ...
    <renderplugin id="plugin:mapviewer" src="scripts/mylib.so" args="whee"  />
  </assets>
  ...
</<application>

Then, in Qt 3D Studio application for the presentation to display this plugin, either:

  • choose a Layer to display the plugin by setting the Sub-Presentation property to the string plugin:mapviewer (the id attribute of the asset), or
  • choose an image to display the composited texture by setting the Sub-Presentation property on the image similarly.

Finally, ensure that the dynamic library and the support files (if any) that are required are copied to your project folder.

Available under certain Qt licenses.
Find out more.