Programming
Fundamentals
Setting Up Development Environment
UnigineScript
High-Level Systems
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes

Projections with AppProjection Plugin

AppProjection allows to create multi-projector setups. Edge blending, non-linear image mapping and color correction for each projection are supported. Due to that, AppProjection can project images onto large curved screen displays covering 360 degrees, if necessary. Moreover, each projection can be fully customized to use required view frustums.

Projection setup

Projection setup

AppProjection

Customizable projection with AppProjection
Notice
Do not use a system mouse cursor when AppProjection is loaded. Go to the Tools panel → Common and uncheck System mouse to enable an application cursor.

See Also

Launching AppProjection

To launch the application and render projections:

  1. Specify an engine plugin library (lib/AppProjection_*) together with the rest of required start-up arguments (such as rendering API, window size, etc.). For example:
    Shell commands
    bin\main_x86d.exe -extern_plugin AppProjection
    You can use 32-bit, 64-bit, debug or release versions of the library. (The engine automatically loads the appropriate version of the library depending on the specified main application.)
    Notice
    It is not possible to use AppProjection with:
  2. To change the number of displays in a row, specify -width CLI option. For example:
    Shell commands
    bin\main_x86d.exe -extern_plugin AppProjection -width 2
    By default, up to 5 projections are supported to be output from one rendering node.

AppProjection with two projections

AppProjection with two projections

Setting Up Projections

To set up projections, open the main menu by pressing Esc, go to Wall tab and click Projection button. Here, it is possible to:

For the last three options, choose a display to be corrected first.

Interface

Interface

Grid Renders a grid over displays to facilitate setting up its curvature. It has the following modes:
  • None
  • Vertical stripes
  • Horizontal stripes
  • Vertical and Horizontal grid
Grid
Grid
Vertical stripes
Vertical stripes
Horizontal stripes
Horizontal stripes
Step Changes the grid step for finer adjustment.
Grid
Step = 16
Vertical stripes
Step = 256
Angle Rotates all projections by:
  • 90 degrees
  • 180 degrees
  • 270 degrees
Display Allows for choosing one display in the drop-down list to set up its curvature, edge blending and color correction options.
Points It is possible to set up projection curvature in the visual editor or by specifying numerical values in Points.
  • Drag yellow handles to distort and fit projection into required configuration.

    Editing curvature
    Editing curvature

    Curved viewport
    Curved viewport
  • To fine-tune curved edges, set up values in Points by X and Y axes:
    • Top-Left, Top-Right, Bottom-Left and Bottom-Right correspond to corners of the projection.
    • Point X and Point Y control the position of corners.
    • Horiz X, Horiz Y, Vert X and Vert Y correspond to positions of handles.

    Coordinates for points and handles
    Coordinates for points and handles
Border Controls soft edge blending for each side of the projection (left, right, top or bottom one). Set non-zero Power to start setting it up.
  • Offset shifts cut out the viewport. The cut part is rendered in black.
    • 0 means the whole viewport is shown.
    • 1 means half of the viewport is cut.
    Low Offset
    Offset = 0.1
    High Offset
    Offset = 1
  • Size controls the size of the blended area:
    • 0 means there is no blending.
    • 1 means half of the screen is blended.
  • Power controls how fast the screen is blended across the area specified by Size.
    • 0 means there is no blending.
    • The higher the value, the large the black area is.
    Low Power
    Power = 1
    High Power
    Power = 5
Color Allows you to correct the color intensity, as well as adjust the color balance.
  • Scale is a per-channel color multiplier. It allows to control intensity of:
    • Red
    • Green
    • Blue
    • RGB at once

    Red channel scale
    Scale for the red channel = 2
  • Bias allows to adjust the color balance per channel (as well as RBG at once):
    • Positive values (up to 1) are added to the color values on the screen.
    • Negative values (starting from -1) are subtracted from color values on the screen.

    Red channel bias
    Bias for the red channel = -0.1
Linearity Controls non-linear stretching for each side of the projection (left, right, top or bottom one).
  • Power controls the stretching ratio for each side:
    • 1 means no stretching.
    • If the value is higher than 1, the projection is stretched from the edge to the center. The distance between vertical (or horizontal - for top and bottom) stripes of the grid is bigger at the edges and decreases near the image center.
    • If the value is lower than 1, the projection is stretched from the center to the edge. The distance between vertical or (or horizontal - for top and bottom) stripes of the grid is bigger near the image center and decreases at the edges.
    Low Offset
    Power = 1
    High Offset
    Power (left) = 0.2
  • Weight is used to interpolate between stripes of the original and stretched grid.
    • 1 means no interpolation.

Multiple Projections' Viewing Settings

If more than two projections are created with AppProjection, the following viewing settings can be tweaked in the Main menu -> Wall.

FOV The field of view for all projections. (Camera tab -> Field of view option is not applicable in this case).

Small Field of view
Fov = 60

Large Field of view
Fov = 80
Angle Allows to adjust the viewing angle between projections. That is, when surfaces to project the images onto are turned at some angle to each other, this angle can be entered as Angle value and the projection will be automatically recalculated to show the right image.

For example, if two surfaces are turned to each other at 40 degrees:

Angle
Angle = 40 degrees
Bezel  X Compensates for horizontal bezel of monitors. Positive values decrease the viewport space; negative ones increase it (for overlapping).

Saving and Loading Presets

After projection configuration is set up, it can be saved into an XML preset file (*.projection) to be loaded at any time:

  • Save button to save a preset file
  • Load button to load a preset file

Customizing AppProjection

AppProjection can be customized to support custom viewing frustums (symmetric or asymmetric ones) for each projection.

AppProjection Viewports

AppProjection have one primary viewport, while all others are rendered as auxiliary ones. By default, the primary display is the Unigine engine viewport used for one-monitor configuration. It uses matrices of the Player used by the engine to view the scene. Other displays are arbitrary cameras with any perspective and facing whatever direction needed. Each display has its own model-view and projection matrices. Both the primary projection and auxiliary ones can be enabled or disabled, if necessary.

  • The primary viewport can be set to any projection (for supported configurations it is already set).
  • Each viewport has its own model-view and projection matrices.
  • By default, only a primary one has an interface (render system GUI, editor widgets, wireframe, or the profiler). However, separate GUIs can be drawn on all projections.
  • All viewports have their own viewport and reflection mask to selectively render nodes and reflections from them.

Default Configurations

For default configurations, the primary viewport is set to the following projection:

  • For 2 projections, the 1st viewport.
  • For 3 projections, the 2nd viewport.
  • For 4 projections, the 2nd viewport.
  • For 5 projections, the 3rd viewport.

How to Customize Projections

Rendering of AppProjection viewports is controlled by wall.h script (found in <UnigineSDK>/data/core/scripts/system/ folder). There are two possible setups depending on how the primary projection is rendered. It can be drawn by:

  • The default engine renderer (the same as when a usual one-monitor application is rendered).
  • The AppProjection renderer itself (which is safer if you are going to use asymmetric frustum for the center projection and modify its model-view matrix).
Notice
Only one of two renderers should be enabled at the same time.

The following example demonstrates how to tweak cameras configuration and choose the renderer for the main projection.

1. Using default engine renderer

The first variant is to render the main (primary) projection by the default engine renderer.

  1. In case the created configuration is not already supported, set the primary projection via engine.projection.setPrimary():
    Source code (UnigineScript)
    // Set the first projection as a primary one
    	engine.projection.setPrimary(0,1);
  2. Enable all non-primary projections via engine.projection.setEnabled(). The main one should be left disabled, as it is drawn by the default engine renderer.
    Source code (UnigineScript)
    // Enable the 2nd projection in a row
    	// The second argument of the function sets 'enabled' flag
    	engine.projection.setEnabled(1,1);
  3. Set projection and model-view matrices for an auxiliary projection via engine.projection.setProjection() and engine.projection.setModelview().
    Source code (UnigineScript)
    // Settings for the 2nd projection
    	engine.projection.setProjection(1,projection_1);
    	engine.projection.setModelview(1,modelview_1);

2. Using AppProjection renderer

Another variant is to render the main projection by the AppProjection renderer. This variant can be used, for example, if you want to set up symmetric frustums for all projections.

  1. Set the projection to be used as a primary one and enable its rendering by AppProjection.
    Source code (UnigineScript)
    // Set the first projection as a primary one
    	// The second argument of the function sets 'enabled' flag
    	engine.projection.setPrimary(0,1);
  2. Disable rendering into the default Unigine viewport via engine.render.setEnabled():
    Source code (UnigineScript)
    engine.render.setEnabled(0);
  3. Enable all AppProjection projections including the primary one. As a result, all viewports will be rendered by AppProjection renderer itself:
    Source code (UnigineScript)
    // Enable all projections
    	engine.projection.setEnabled(0,1);
    	engine.projection.setEnabled(1,1);
  4. Set model-view and projection matrices for all projections.
    Source code (UnigineScript)
    // Settings for the 1st projection
    	engine.projection.setProjection(0,projection_0);
    	engine.projection.setModelview(0,modelview_0);
    
    	// Settings for the 2nd projection
    	engine.projection.setProjection(1,projection_1);
    	engine.projection.setModelview(1,modelview_1);
Last update: 2017-07-03