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.
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
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
outHeight to its desired rendering size, and set the texture format to one of:
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
[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
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,
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.
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
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.
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
idattribute 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.