UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
FAQ
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
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
CIGI Client Plugin
Rendering-Related Classes

Projections with AppProjection Plugin

AppProjection allows you to create multi-projector setups. Edge blending, non-linear image mapping and color correction for each projection are supported. Therefore, 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.

Notice
This plugin cannot be used in a Qt-based application.

Projection setup

Projection setup

AppProjection

Customizable projection with AppProjection

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 8 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 system menu by pressing Esc, go to Plugins tab and click Projection button.

The Projection Configurator window will open. Here, it is possible to:

For the last three options, you should first choose a Projection to be adjusted at the top-right corner.

Warping#

The Warp tab allows you to set up geometry correction for your projections. Areas where geometry correction is required include:

  • Advanced off-axis correction where projector placement is awkward and needs an advanced mapping over the keystone function in a projector
  • Non-planar screens such a curved screens and hemispherical domes
  • Projecting one image from one projector onto more than one surface
  • Unusual projection applications onto custom designed screens

Interface

Interface

You can switch between the control points using arrow keys and move them with the Ctrl key pressed. Adjustable screen size parameters enable you to control each point of your projection with a pixel accuracy. You can also increase and decrease Multiplier to be used when moving points with arrow keys via A and Z keys respectively.

Notice
Points are always moved in screen space coordinates regardless of image orientation (whether it is flipped or not), this means if you press left arrow, the point always goes left.

You can also use the following view control options:

  • Middle Mouse Button for panning (dragging the view vertically or horizontally)
  • Mouse Scroll for zooming in and out
  • button to fit the view to the window

The following options are available:

Projection Allows you to choose a projection in the drop-down list to set up its parameters: warping, edge blending and color correction.
Screen Size Allows you to choose screen size in pixels (width x height). These parameters determine the size of the pixel for control point displacement with arrow keys on the keyboard.
Multiplier Indicates the displacement amount to be used when moving points with arrow keys. The resulting displacement amount equals to pixel size, calculated for the Screen Size specified, multiplied by this value. Use A to increase value, or Z - to decrease it.
Resolution Warping is performed by defining a grid. A 2 x 2 grid is used by default. You can set the number of control points for the grid along horizontal and vertical axes.
Points Visual editor enables you to set up warping for the selected projection using control points and yellow handles. These handles are displayed for each selected control point depending on its type.
Notice
The maximum grid size is 32 x 32.
  • Drag control points and their yellow handles to warp the projection and adjust it for the required configuration.

    You can see an example of a warped grid and a corresponding projection image below.

    Warped grid
    Warped grid

    Warped image
    Warped image
  • You can fine-tune projection warping by adjusting the parameters of each control point by selecting it and changing parameters via the following panel next to grid resolution settings

    The following parameters are available

    • Point - horizontal and vertical indices of the selected control point.
    • Position - coordinates of the selected control point along X and Y axes. Coordinates for points and handles
      Coordinates for control points
    • Type - warping type for the selected control point:
      • - automatic linear interpolation (no control handles available)
      • - symmetric control handles for smooth curves
      • - asymmetric control handles (you can control each handle independently)
      • - automatic smooth curve (no control handles available)

Canvas Here you can configure the canvas for the selected projection: set rotation angle and enable vertical and horizontal flipping.

Render

The Debug option allows you to temporarily set individual colors for different projections. This helps to visualize overlapping regions for different projections and facilitates the setup process.

The Show Grid option enables visualization of warping grid on the screen which significantly facilitates the process of debugging configuration of a multi-projector setup.

Color and Brightness Correction#

The Color tab allows you to correct color intensity, as well as to adjust color balance for the selected projection.

Brightness Per-channel color multiplier to control the intensity of:
  • Red
  • Green
  • Blue
  • RGB at once
Red channel scale
Scale for the red channel = 2
Contrast allows you to adjust the color balance per channel (as well as for all channels 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
Brightness (corners) allows you to adjust brightness compensation for each of projection's corners individually.
Notice
Brightness values and Mask parameters for corners can be reset to defaults by clicking the corresponding parameter name.

Edge Blenging and Masking#

The Blend & Mask tab allows you to configure blending along the edges and according to masks, you can also use masks to cut out certain areas for the selected projection.

Mask This group allows you to set up masks to be used for blending regions or to cut out certain areas (e.g. top and bottom areas for a curved screen projection).

The list of masks for the current projection is displayed on the left. You can add new masks and remove existing ones using the corresponding buttons.

Visual editor enables you to create and modify masks.

  • To add new points to the mask selected in the list, you should click Creation Mode button. Then you can add new points by clicking within the grid area, new points will be placed at the mouse cursor. To insert a new point into an existing mask, select the point next to which a new point is to be added, and click to insert a new one. You can drag an existing point to move it. To remove a point, simply right-click it.

  • You can also adjust your masks precisely by specifying the coordinates of each point. Select a point on the grid (its color will turn to white) and enter the coordinates in the corresponding Position fields below.

    You can change the type of the selected control point using the following icons:

    • - automatic linear interpolation (no control handles available)
    • - symmetric control handles for smooth curves
    • - asymmetric control handles (you can control each handle independently)
    • - automatic smooth curve (no control handles available)

As you select a mask in the list, its parameters are displayed on the panel next to it:

  • Enabled - enables or disables displaying the selected mask. Can be used for convenience when configuring overlapping regions, when there are a lot of masks.
  • Name - mask name.
  • Color - color to be used for the selected mask. This option can be used to distinguish between masks when configuring overlapping regions and perform color correction.
  • Smooth - smoothing of mask edges. Determines the number of additional points to be inserted between the control points.
  • Border Size controls the width of the blended area along the edges of the mask polygon (analogous to Size parameter for the border):
    • 0 - there is no blending.
    • 1 - a half of the screen is blended.
  • Outer Alpha - opacity of the mask border area along the edges:
    • 0 - the mask is fully transparent.
    • 1 - the mask is fully opaque.
  • Inner Alpha - opacity of the mask polygon:
    • 0 - the mask is fully transparent.
    • 1 - the mask is fully opaque.
  • Power controls how fast the screen is blended across the area specified by Size (analogous to Power parameter for the border).
    • 0 - there is no blending.
    • The higher the value, the larger the black area is.
Border Controls soft edge blending for each side of the projection (left, right, top or bottom one). Set a non-zero Power value to start setting it up.
  • Gamma - gamma correction value.
  • Offset - viewport clipping offset. The clipped part is rendered in black.
    • 0 - the whole viewport is shown.
    • 1 - a half of the viewport is cut out.
    Low Offset
    Offset = 0.1
    High Offset
    Offset = 1
  • Size controls the size of the blended area:
    • 0 - there is no blending.
    • 1 - a half of the screen is blended.
  • Power controls how fast the screen is blended across the area specified by Size.
    • 0 - there is no blending.
    • The higher the value, the larger the black area is.
    Low Power
    Power = 1
    High Power
    Power = 5
Notice
Border values can be reset by clicking the corresponding column or line name.

Multiple Projections' Viewing Settings#

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

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 adjusting 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 the projection configuration is set up, it can be saved to an preset file (*.proj) to be loaded at any time (e.g. to set up another projection):

  • Save button to save a preset file
  • Load button to load a preset file
Notice
  • A *.proj file that you save contains settings only for the currently selected projection.
  • Settings loaded from a *.proj file are applied to the currently selected projection.

Customizing AppProjection#

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

AppProjection Viewports#

AppProjection has one primary viewport, while all other viewports 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 a graphical user 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: 2019-05-16