3.3.3. Developing for MultiPipe

This section is intended for advanced users creating their own Open Inventor custom nodes. We recommend that you first review the key concepts described in chapter 12-Multithreading

Making an application safe for multi-pipe is not an easy task. Nevertheless, several steps in application development are possible to ensure quick and safe results. MultiPipe rendering mainly requires that the rendering action (SoGLRenderAction) be thread and (OpenGL) context safe while multiple render threads are traversing the scene graph concurrently. The following steps should preferably be done in the order they are presented since they allow incrementally checking some key points.

[Important]

The following steps only apply to a tiled compositing configuration. Nevertheless, new nodes designed for depth compositing rendering can be developed by following these steps at least to check concurrent thread traversals.

ScaleViz MultiPipe requires context safe traversal because the rendering is done independently by each GPU. When doing MultiPipe rendering, contexts are not shared between pipes. As a consequence, the first step is to ensure that all context dependent objects support a rendering context switch without unintentional breaking of caches.

For example: By default a SoSeparator SoSeparator SoSeparator node is able to manage two render caches independent of the number of rendering contexts. Prior to Open Inventor 8.0, the problem was that when rendering for 4 contexts, the cache was constantly broken: cache 1 was replaced by cache 3, cache 2 was replaced by cache 4, etc… so at the end, no cache. This problem has been solved, and 2 different caches can now be maintained for each rendering context. In the same manner, developers must take care about caching problems when creating new nodes.

Several environment variables are currently available to help during development and debug steps:

SCALEVIZ_MP_RENDERMODE can be set to:

  • ST_FULL_VIEW: used for debug and/or dev step, each defined pipe does its rendering sequentially (multi-context, but not multi-thread and not multi-gpu). Each pipe rendering shows the whole scene.

  • ST_SPLIT_VIEW: used for debug and/or dev step, each defined pipe does its rendering sequentially (multi-context, but not multi-thread and not multi-gpu). The resulting rendering is the composed view.

  • MT: default rendering. The rendering is done with multiple threads: one thread per pipe. The resulting rendering is the composed view. (Multi-context, multi-thread and multi-gpu (if available) )

Test step:

Run the “Multi-Context” check step on a single GPU machine and define the SCALEVIZ_MP_RENDERMODE environment variable to ST_FULL_VIEW or ST_SPLIT_VIEW.

- The rendering is done sequentially in the main thread.

- Defined pipes are simulated; a new OpenGL context is created for each pipe.

Note: Another simple way to check your nodes are properly supporting multi-context rendering is to create a Scene Graph and apply it to two different viewers that do not share contexts.

Remember that MultiPipe mode is doing the rendering using several GPUs independently and in parallel on a subpart of the whole rendering viewport. Thus, the rendering code of every node must be thread-safe to allow several threads to traverse at the same time.

Test step:

Run “Multi-Thread” check step on a single GPU machine and define the SCALEVIZ_MP_RENDERMODE environment variable to MT.

- The rendering is done in parallel.

- Each pipe is simulated (using the single GPU). A new OpenGL context is created for each pipe.

This step should not fail because of unsafe source code if the previous steps succeeded. In this check, the only part that is changing is the context creation. A context is created for each GPU.

Thus, if this step is failing, check your system configuration, and re-check step1 and step 2.

Test step:

Run “Multi-GPU” check step on a multiple GPU machine.

- The rendering is done in parallel.

- A new OpenGL context is created for each rendering pipe, i.e. for each GPU.

Multipipe rendering mode can be optionally activated and deactivated through the ScaleViz connection dialog. It is important to check that the multipipe disconnection option succeeds in order to ensure that all context dependent objects and thread allocated objects are properly cleaned up.

Note: the SCALEVIZ_AUTORUN environment variable is still available to provide automatic Multipipe application launching at application startup.

  1. We strongly recommend that you do not change the scenegraph structure or node properties during the rendering traversal process.

    Note: The only valid way to modify a node during traversal is to disable notification on the node and to remove all kind of sensors listening for changes on the node. This cannot be ensured in most of the cases.

  2. In many cases, thinking about solving context switch problems linked to Multipipe rendering involves solving the multi-thread traversal problem. Addressing this problem is facilitated by use of the SbThreadStorage template.

  3. Some environment variables can be defined to help in problem detection such as unexpected notification in threads, defects in object thread storage initialization, etc…Set OIV_MP_WARNING to 1 to enable notification detection (currently only managed for SoGLRenderAction SoGLRenderAction SoGLRenderAction , SoGetBoundingBoxAction SoGetBoundingBoxAction SoGetBoundingBoxAction and SoWriteAction SoWriteAction SoWriteAction ) and initTLSClass() check.

    Set SCALEVIZ_MP_DEBUG to 1 to show ScaleViz Multipipe information:

    • For a tiled compositing based configuration, enabling this variable cause SaleViz to draw the rendering viewport box and pipe ids on the screen.

    • For a depth compositing based configuration, the current compositing mode is displayed.

      • Using the ScaleViz depth composition mode, set SCALEVIZ_OIRU_DIAPLAY to 1. The viewer rendering will be divided in as many sub-region as the number of depth composer defined. Each sub-region is displaying the rendering done by the associated GPU. In this case the final frame is not composed.

      • If using NVidia CompleX library with QuadroPlex, setting SCALEVIZ_MP_ALLOW_FB and SCALEVIZ_MP_NVCOMPLEX_SHOW_FB to 1 will make ScaleViz to open as many new windows as defined depthComposer nodes in configuration. Each window displays the rendering done by the associated GPU. The final frame is composed as the viewer frame.

    These environment varaibles have very significant impact on performance. Use it for debugging purpose only.

  4. Common ScaleViz log info is also available by adding MP to the list of allowed filters (SCALEVIZ_LOG_FILTER). This reports information related to GPU initialization, context creation, and thread starting/ending.