Programming
Fundamentals
Setting Up Development Environment
Usage Examples
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

Unigine::Viewport Class

Header:#include <UnigineViewport.h>

A Viewport class is used to render a scene with the specified settings.

There are two main use cases of the Viewport class:

  1. Integrate the engine to a 3rd party renderer (or vice versa) and render the image anywhere (via the render() method): to the external library, App interface, TextureRender interface (a frame buffers abstraction), etc.

    • To render the image to the TextureRender interface, do the following:

      Source code (C++)
      // mono rendering
      // initialization
      ViewportPtr viewport = Viewport::create();
      
      TextureRenderPtr texturerender = TextureRender::create();
      TexturePtr texture = Texture::create();
      texture->create2D(512,512,Texture::FORMAT_RGBA8,Texture::USAGE_RENDER); // create 512 x 512 render target
      
      CameraPtr camera = Camera::create();
      // set modelview & projection matrices to camera instance
      
      // rendering
      texturerender->enable();
      	texturerender->setColorTexture(0,texture);
      	viewport->render(camera);
      texturerender->disable();

      To render the image to the TextureRender interface in the stereo mode, do the following:

      Source code (C++)
      // stereo rendering
      // initialization
      ViewportPtr viewport = Viewport::create();
      
      TextureRenderPtr texturerender = TextureRender::create();
      TexturePtr left_texture = Texture::create();
      TexturePtr right_texture = Texture::create();
      
      // create two 512 x 512 render target for each eye
      left_texture->create2D(512,512,Texture::FORMAT_RGBA8,Texture::USAGE_RENDER);
      right_texture->create2D(512,512,Texture::FORMAT_RGBA8,Texture::USAGE_RENDER);
      
      CameraPtr left_eye = Camera::create();
      CameraPtr right_eye = Camera::create();
      // set modelview & projection matrices for each eyes
      
      // rendering
      texturerender->enable();
      	texturerender->setColorTexture(0,left_texture);
      	texturerender->setColorTexture(0,right_texture);
      	viewport->renderStereo(left_eye,right_eye,"post_stereo_separate"); // use "post_stereo_separate" material in order to render to both textures
      texturerender->disable();
    • To render the image to the App interface, check the App samples (source -> plugins -> App -> App*
      Notice
      App* samples are available only for the Professional and Sim Unigine SDKs.
  2. Render a scene to the image (data will be transfered from GPU memory to CPU memory) or texture (data stays in the GPU memory).
  3. Render a node to the image (data will be transfered from GPU memory to CPU memory) or texture (data stays in the GPU memory).
Notice

To set any viewport as a main, use the setViewport() method of the Render classddd.

A single viewport should be used with a single camera, otherwise it may cause visual artefacts. To avoid artefacts, when using several cameras with a single viewport, all post effects must be disabled using the setSkipFlags() method with the SKIP_POSTEFFECTS flag.

Viewport Class

Members


static ViewportPtr create()

Creates a new viewport with default settings.

void setAspectCorrection(int correction)

Sets the aspect correction for current viewport. 1 enables correction, 0 disables.

Arguments

  • int correction - 1 to enable aspect correction, 0 to disable.

int getAspectCorrection()

Return the value indicating if the aspect correction enabled for current viewport.

Return value

1 if the aspect correction enabled, otherwise 0.

int addCallback(int callback, Unigine::CallbackBase * func)

Adds a callback for the specified stage of the rendering sequence. Callback functions can be used to get access to buffers and matrices at intermediate stages of the rendering sequence. Some of them are read-only, but most of them can be modified ad hoc.

Arguments

  • int callback - Stage of the rendering sequence for which a callback is to be added. One of the CALLBACK_* variables.
    Notice
    The _BEGIN prefix corresponds to the beginning of the rendering pass, _END - to its completion.
  • Unigine::CallbackBase * func - Callback pointer.

void clearCallbacks(int callback)

Clears all added callbacks for the specified stage of the rendering sequence. Callback functions can be used to get access to buffers and matrices at intermediate stages of the rendering sequence. Some of them are read-only, but most of them can be modified ad hoc.

Arguments

  • int callback - Stage of the rendering sequence for which the callbacks are to be cleared. One of the CALLBACK_* variables.
    Notice
    The _BEGIN prefix corresponds to the beginning of the rendering pass, _END - to its completion.

void removeCallback(int callback, int num)

Removes a callback with a given number from the list of callbacks for the specified stage of the rendering sequence. Callback functions can be used to get access to buffers and matrices at intermediate stages of the rendering sequence. Some of them are read-only, but most of them can be modified ad hoc.

Arguments

  • int callback - Stage of the rendering sequence for which the callback is to be removed. One of the CALLBACK_* variables.
    Notice
    The _BEGIN prefix corresponds to the beginning of the rendering pass, _END - to its completion.
  • int num - Callback number.

void setFirstFrame(int frame)

Sets a value indicating if the first frame should be enabled over the current frame.

Arguments

  • int frame - 1 to set the first frame flag; otherwise, 0.

int getFirstFrame()

Returns a value indicating if the first frame is enabled over the current frame.

Return value

1 if the first frame flag is set; otherwise, 0.

int getID()

Returns the viewport ID.

Return value

Viewport ID.

void setMode(int mode)

Sets the rendering mode for the current viewport. It can be one of the stereo or panoramic modes or the default mode.

Arguments

  • int mode - A rendering mode.

int getMode()

Returns the rendering mode set for the current viewport. It can be one of the stereo or panoramic modes or the default mode.

Return value

The current rendering mode.

void setNodeEnvironmentTextureName(const char * name)

Sets a name for the environment texture.

Arguments

  • const char * name - A texture name.

void setNodeLightUsage(int usage)

Sets the type of lighting for the render node.

Arguments

int getNodeLightUsage()

Returns the type of lighting of the render node.

Return value

The lighting type. Can be one of the following:

int isPanorama180()

Returns a value indicating if a 180-degree panoramic rendering is enabled.

Return value

1 if a 180-degree panoramic rendering is enabled; otherwise, 0.

int isPanorama360()

Returns a value indicating if a 360-degree panoramic rendering is enabled.

Return value

1 if a 360-degree panoramic rendering is enabled; otherwise, 0.

void setRenderMode(int mode)

Sets the specified render mode. The mode determines the set buffers to be rendered.

Arguments

int getRenderMode()

Returns the current render mode. The mode determines the set buffers to be rendered.

Return value

Current render mode. Can be one of the following:

void setSkipFlags(int flags)

Sets the skip flag for the current viewport.

Arguments

int getSkipFlags()

Returns the skip flag set for the current viewport.

Return value

A skip flag.

int isStereo()

Returns a value indicating if the stereo rendering is enabled for the current viewport (one of the stereo modes is set).

Return value

1 if the stereo rendering is enabled; otherwise, 0.

void setStereoDistance(float distance)

Sets the focal distance for stereo rendering (distance in the world space to the point where two views line up, i.e. to the zero parallax plane).

Arguments

  • float distance - A focal distance in units.

float getStereoDistance()

Returns the focal distance for stereo rendering (distance in the world space to the point where two views line up, i.e. to the zero parallax plane).

Return value

A focal distance in units.

void setStereoOffset(float offset)

Updates the virtual camera offset (an offset after the perspective projection).

Arguments

  • float offset - A virtual camera offset in units.

float getStereoOffset()

Returns the virtual camera offset (an offset after the perspective projection).

Return value

A virtual camera offset in units.

void setStereoRadius(float radius)

Updates the radius for stereo (the half of the separation distance between the cameras (i.e. between eyes)).

Arguments

  • float radius - A stereo radius in units. If a negative value is provided, 0 will be used instead.

float getStereoRadius()

Returns the current radius for stereo (the half of the separation distance between the cameras (i.e. between eyes)).

Return value

Stereo radius in units.

void appendSkipFlags(int flags)

Appends specified skip flags to the list of currently used ones.

Arguments

int checkSkipFlags(int flags)

Returns a value indicating if the specified skip flags are set for the current viewport.

Arguments

Return value

1 if the skip flags are set; otherwise, 0.

void removeSkipFlags(int flags)

Removes specified skip flags from the list of currently used ones.

Arguments

void render(const Ptr<Camera> & camera)

Renders an image from the specified camera. This method is used to integrate the engine to a 3rd party renderer.

To render an image from the camera to the TextureRender interface, do the following:

Source code (C++)
camera = Camera::create();

texturerender->enable();
	viewport->render(camera);
texturerender->disable();

Arguments

  • const Ptr<Camera> & camera - Camera an image from which should be rendered.

void renderImage2D(const Ptr<Camera> & camera, const Ptr<Image> & image)

Renders an image from the camera into the given 2D image.

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Ptr<Image> & image - A 2D image.

void renderImage2D(const Ptr<Camera> & camera, const Ptr<Image> & image, int width, int height, int hdr = 0)

Renders an image from the camera into the 2D image of the specified size.

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Ptr<Image> & image - A 2D image.
  • int width - Width of the 2D image.
  • int height - Height of the 2D image.
  • int hdr - HDR flag.

void renderImageCube(const Ptr<Camera> & camera, const Ptr<Image> & image, int size, int hdr = 0, int local_space = 0)

Renders the image from the camera into the cube map of the specified size.

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Ptr<Image> & image - Cube map.
  • int size - Cube map edge size.
  • int hdr - HDR flag.
  • int local_space - A flag indicating if the camera angle should be used for the cube map rendering.

void renderImageCube(const Ptr<Camera> & camera, const Ptr<Image> & image)

Renders the image from the camera into the cube map.

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Ptr<Image> & image - Cube map.

void renderNode(const Ptr<Camera> & camera, const Ptr<Node> & node)

Renders the given node with all children into the current rendering target.

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Ptr<Node> & node - Node to be rendered.

void renderNodeImage2D(const Ptr<Camera> & camera, const Ptr<Node> & node, const Ptr<Image> & image, int width, int height, int hdr)

Renders the given node with all children into the 2D image of the specified size.

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Ptr<Node> & node - Pointer to the node to be rendered.
  • const Ptr<Image> & image - Pointer to the 2D image.
  • int width - Image width.
  • int height - Image height.
  • int hdr - HDR flag.

void renderNodeImage2D(const Ptr<Camera> & camera, const Ptr<Node> & node, const Ptr<Image> & image)

Renders the given node with all children into the 2D image of the specified size.

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Ptr<Node> & node - Pointer to the node to be rendered.
  • const Ptr<Image> & image - Pointer to the 2D image.

void renderNodeTexture2D(const Ptr<Camera> & camera, const Ptr<Node> & node, const Ptr<Texture> & texture)

Renders the given node with all children into the 2D image of the specified size.

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Ptr<Node> & node - Pointer to the node to be rendered.
  • const Ptr<Texture> & texture - Pointer to the texture.

void renderNodes(const Ptr<Camera> & camera, const Vector< Ptr<Node> > & nodes)

Renders given nodes with all children into the current rendering target.

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Vector< Ptr<Node> > & nodes - List of the nodes to be rendered.

void renderNodesImage2D(const Ptr<Camera> & camera, const Vector< Ptr<Node> > & nodes, const Ptr<Image> & image)

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Vector< Ptr<Node> > & nodes - List of the nodes to be rendered.
  • const Ptr<Image> & image - 2D image smart pointer.

void renderNodesImage2D(const Ptr<Camera> & camera, const Vector< Ptr<Node> > & nodes, const Ptr<Image> & image, int width, int height, int hdr)

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Vector< Ptr<Node> > & nodes - List of the nodes to be rendered.
  • const Ptr<Image> & image - 2D image smart pointer.
  • int width - Image width.
  • int height - Image height.
  • int hdr - HDR flag.

void renderNodesTexture2D(const Ptr<Camera> & camera, const Vector< Ptr<Node> > & nodes, const Ptr<Texture> & texture)

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Vector< Ptr<Node> > & nodes - List of the nodes to be rendered.
  • const Ptr<Texture> & texture - Texture smart pointer.

void renderStereo(const Ptr<Camera> & camera_left, const Ptr<Camera> & camera_right, const char * stereo_material)

Renders a stereo image in the current viewport.

Arguments

  • const Ptr<Camera> & camera_left - Camera that renders an image for the left eye.
  • const Ptr<Camera> & camera_right - Camera that renders an image for the right eye.
  • const char * stereo_material - Stereo materials.

void renderTexture2D(const Ptr<Camera> & camera, const Ptr<Texture> & texture)

Renders an image from the camera into the texture.

Arguments

  • const Ptr<Camera> & camera - Camera, an image from which should be rendered.
  • const Ptr<Texture> & texture - Pointer to the texture.

int MODE_DEFAULT

Description

Enables the default stereo mode - no stereo and panoramic rendering in the current viewport is available. This mode is set by default for a new viewport.

int MODE_PANORAMA_180_CURVED

Description

Enables rendering of the viewport as a 180-degree panorama with curved edges.

int MODE_PANORAMA_180_FISHEYE

Description

Enables rendering of the viewport as a 180-degree spherical panorama (fisheye).

int MODE_PANORAMA_180_LINEAR

Description

Enables rendering of the viewport as a 180-degree linear panorama without distortion at the edges.

int MODE_PANORAMA_360_CURVED

Description

Enables rendering of the viewport as a 360-degree panorama with curved edges.

int MODE_PANORAMA_360_FISHEYE

Description

Enables rendering of the viewport as a 360-degree spherical panorama (fisheye).

int MODE_PANORAMA_360_LINEAR

Description

Enables rendering of the viewport as a 360-degree linear panorama without distortion at the edges.

int MODE_STEREO_ANAGLYPH

Description

Enables the anaglyph stereo mode that is viewed with red-cyan anaglyph glasses.

int MODE_STEREO_HORIZONTAL

Description

Enables the horizontal stereo mode that is supported on mobile devices.

int MODE_STEREO_INTERLACED

Description

Enables the interlaced stereo mode that is used with interlaced stereo monitors and polarized 3D glasses.

int MODE_STEREO_REPLICATE

Description

Enables the separate images stereo mode. This mode serves to output two separate images for each of the eye. It can be used with any VR/AR output devices that support separate images output, e.g. for 3D video glasses or helmets (HMD).

int MODE_STEREO_SEPARATE

Description

Enables the replicate images stereo mode.

int MODE_STEREO_VERTICAL

Description

Enables the vertical stereo mode that is supported on mobile devices.

int SKIP_DYNAMIC_REFLECTIONS

Description

Skip rendering of dynamic reflections in the viewport.

int SKIP_FORMAT_RG11B10

Description

Skip rendering of RG11B10 formats in the viewport.

int SKIP_POSTEFFECTS

Description

Skip rendering of post effects in the viewport.

int SKIP_SHADOWS

Description

Skip shadows rendering in the viewport.

int SKIP_SRGB

Description

Skip rendering of the srgb color space.

int SKIP_VELOCITY_BUFFER

Description

Skip rendering to the velocity buffer for the viewport.

int SKIP_VISUALIZER

Description

Skip rendering of the visualizer in the viewport. This flag is set by default for a new viewport.

int USAGE_AUX_LIGHT

Description

Use lighting from the auxiliary virtual scene containing one LightWorld (with 45, 45 and 45 degrees slope angles), scattering is not used.

int USAGE_NODE_LIGHT

Description

Use the node lighting.

int USAGE_WORLD_LIGHT

Description

Use lighting from the LightWorld set in the current loaded world.

int NUM_CALLBACKS

int CALLBACK_ALL

int CALLBACK_BEGIN

int CALLBACK_END

int CALLBACK_BEGIN_ADAPTIVE_EXPOSURE

Description

Callback before the adaptive exposure stage.

int CALLBACK_END_ADAPTIVE_EXPOSURE

Description

Callback after the adaptive exposure stage.

int CALLBACK_BEGIN_AUXILIARY_BUFFER

Description

Callback before filling the auxiliary buffer.

int CALLBACK_END_AUXILIARY_BUFFER

Description

Callback after filling the auxiliary buffer.

int CALLBACK_BEGIN_CAMERA_EFFECTS

Description

Callback before the camera effects stage.

int CALLBACK_END_CAMERA_EFFECTS

Description

Callback after the camera effects stage.

int CALLBACK_BEGIN_CLOUDS

Description

Callback before the clouds rendering stage.

int CALLBACK_END_CLOUDS

Description

Callback after the clouds rendering stage.

int CALLBACK_BEGIN_COMPOSITE_DEFERRED

Description

Callback before the clouds deferred composite stage.

int CALLBACK_END_COMPOSITE_DEFERRED

Description

Callback after the clouds deferred composite stage.

int CALLBACK_BEGIN_DEBUG_MATERIALS

Description

Callback before the debug materials stage.

int CALLBACK_END_DEBUG_MATERIALS

Description

Callback after the debug materials stage.

int CALLBACK_BEGIN_OPACITY_DECALS

Description

Callback before the opacity decals rendering stage.

int CALLBACK_END_OPACITY_DECALS

Description

Callback after the opacity decals rendering stage.

int CALLBACK_BEGIN_OPACITY_ENVIRONMENT_PROBES

Description

Callback before the opacity environment probes rendering stage.

int CALLBACK_END_OPACITY_ENVIRONMENT_PROBES

Description

Callback after the opacity environment probes rendering stage.

int CALLBACK_BEGIN_OPACITY_GBUFFER

Description

Callback before filling the Gbuffer.

int CALLBACK_END_OPACITY_GBUFFER

Description

Callback after filling the Gbuffer.

int CALLBACK_BEGIN_OPACITY_LIGHTS

Description

Callback before the opacity lightgs rendering stage.

int CALLBACK_END_OPACITY_LIGHTS

Description

Callback after the opacity lightgs rendering stage.

int CALLBACK_BEGIN_POST_MATERIALS

Description

Callback before the post materials rendering stage.

int CALLBACK_END_POST_MATERIALS

Description

Callback after the post materials rendering stage.

int CALLBACK_BEGIN_REFRACTION_BUFFER

Description

Callback before filling the refraction buffer.

int CALLBACK_END_REFRACTION_BUFFER

Description

Callback after filling the refraction buffer.

int CALLBACK_BEGIN_SRGB_CORRECTION

Description

Callback before the sRGB correction stage.

int CALLBACK_END_SRGB_CORRECTION

Description

Callback after the sRGB correction stage.

int CALLBACK_BEGIN_SSAO

Description

Callback before the SSAO rendering stage.

int CALLBACK_END_SSAO

Description

Callback after the SSAO rendering stage.

int CALLBACK_BEGIN_SSGI

Description

Callback before the SSGI rendering stage.

int CALLBACK_END_SSGI

Description

Callback after the SSGI rendering stage.

int CALLBACK_BEGIN_SSR

Description

Callback before the SSR rendering stage.

int CALLBACK_END_SSR

Description

Callback after the SSR rendering stage.

int CALLBACK_BEGIN_SSRTGI

Description

Callback before the SSRTGI rendering stage.

int CALLBACK_END_SSRTGI

Description

Callback after the SSRTGI rendering stage.

int CALLBACK_BEGIN_TRANSPARENT_BLUR_BUFFER

Description

Callback before filling the transparent blur buffer.

int CALLBACK_END_TRANSPARENT_BLUR_BUFFER

Description

Callback after filling the transparent blur buffer.

int CALLBACK_BEGIN_TAA

Description

Callback before the Temporal Anti-Aliasing (TAA) pass.

int CALLBACK_END_TAA

Description

Callback after the Temporal Anti-Aliasing (TAA) pass.

int CALLBACK_BEGIN_TRANSPARENT

Description

Callback before the transparent objects rendering stage.

int CALLBACK_END_TRANSPARENT

Description

Callback after the transparent objects rendering stage.

int CALLBACK_BEGIN_VISUALIZER

Description

Callback before the visualizer rendering stage.

int CALLBACK_END_VISUALIZER

Description

Callback after the visualizer rendering stage.

int CALLBACK_BEGIN_WATER

Description

Callback before the water rendering stage.

int CALLBACK_END_WATER

Description

Callback after the water rendering stage.

int CALLBACK_BEGIN_WATER_DECALS

Description

Callback before the water decals rendering stage.

int CALLBACK_END_WATER_DECALS

Description

Callback after the water decals rendering stage.

int RENDER_DEPTH

Description

Render only depth.

int RENDER_DEPTH_GBUFFER

Description

Render only depth and Gbuffer.

int RENDER_DEPTH_GBUFFER_FINAL

Description

Render depth, Gbuffer and final image.
Last update: 2017-07-03