Unigine::Viewport Class

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

The main use cases of the Viewport class are as follows:

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, CustomSystemProxy interface, RenderTarget interface (a frame buffers abstraction), etc.

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

     Source code (C++)

     // mono rendering
     
     ViewportPtr viewport;
     TexturePtr texture;
     CameraPtr camera;
     
     int AppWorldLogic::init()
     {
     
     	viewport = Viewport::create();
     
     	texture = Texture::create();
     	// create 512 x 512 render target
     	texture->create2D(512, 512, Texture::FORMAT_RGBA8, Texture::FORMAT_USAGE_RENDER);
     	camera = Camera::create();
     	
     
     	return 1;
     }
     
     int AppWorldLogic::update()
     {
     
     	// set modelview & projection matrices to camera instance
     	// ...
     
     	// rendering
     	RenderTargetPtr render_target = Render::getTemporaryRenderTarget();
     	render_target->bindColorTexture(0, texture);
     	render_target->enable();
     	{
     		viewport->render(camera);
     	}
     	render_target->disable();
     	render_target->unbindAll();
     	Render::releaseTemporaryRenderTarget(render_target);
     
     	return 1;
     }

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

     Source code (C++)

     // stereo rendering
     
     ViewportPtr viewport;
     TexturePtr left_texture;
     TexturePtr right_texture;
     CameraPtr left_eye;
     CameraPtr right_eye;
     
     int AppWorldLogic::init()
     {
     	viewport = Viewport::create();
     
     	left_texture = Texture::create();
     	right_texture = Texture::create();
     
     	// create two 512 x 512 render target for each eye
     	left_texture->create2D(512, 512, Texture::FORMAT_RGBA8, Texture::FORMAT_USAGE_RENDER);
     	right_texture->create2D(512, 512, Texture::FORMAT_RGBA8, Texture::FORMAT_USAGE_RENDER);
     
     	left_eye = Camera::create();
     	right_eye = Camera::create();
     
     	return 1;
     }
     int AppWorldLogic::update()
     {
     	// set modelview & projection matrices to camera instance
     	// ...
     
     	// rendering
     	RenderTargetPtr render_target = Render::getTemporaryRenderTarget();
     	render_target->bindColorTexture(0, left_texture);
     	render_target->bindColorTexture(1, right_texture);
     	render_target->enable();
     	{
     		// use "post_stereo_separate" material in order to render to both textures
     		viewport->renderStereo(left_eye, right_eye, "Unigine::post_stereo_separate");
     	}
     	render_target->disable();
     	render_target->unbindAll();
     	Render::releaseTemporaryRenderTarget(render_target);
     
     	return 1;
     }

   • To render the image to the CustomSystemProxy interface, check the 3rd Party samples: source -> samples -> 3rdparty -> ViewportQt.

     Notice

     ViewportQt sample is available only for the Engineering and Sim editions of UNIGINE SDKs.

2. Render a scene to a texture (data stays in the GPU memory).

   • To render the scene to a Texture interface, use the following methods:

     • renderTexture2D(camera,texture)
     • renderTexture2D(camera,texture,width,height,hdr)
     • renderTextureCube(camera,texture,local_space)
     • renderTextureCube(camera,texture,size,hdr,local_space)
     Source code (C++)

     ViewportPtr viewport;
     TexturePtr texture;
     CameraPtr camera;
     
     int AppWorldLogic::init()
     {
     	// initialization
     	viewport = Viewport::create();
     
     	texture = Texture::create();
     
     	// create 512 x 512 render target
     	texture->create2D(512, 512, Texture::FORMAT_RGBA8, Texture::FORMAT_USAGE_RENDER);
     
     	camera = Camera::create();
     
     	return 1;
     }
     
     int AppWorldLogic::update()
     {
     	// set modelview & projection matrices to camera instance
     	// ...
     
     	// rendering
     	// 
     	// saving current render state and clearing it
     	RenderState::saveState();
     	RenderState::clearStates();
     	{
     		viewport->renderTexture2D(camera, texture);
     	}
     	RenderState::restoreState();
     
     	return 1;
     }

3. Render a node to a texture (data stays in the GPU memory).

   • To render a node (or nodes) to a Texture interface, use the following methods:
     • renderNodeTexture2D(camera,node,texture)
     • renderNodeTexture2D(camera,node,texture,width,height,hdr)
     • renderNodesTexture2D(camera,nodes,texture)
     • renderNodesTexture2D(camera,nodes,texture,width,height,hdr)

You can subscribe to events before and after any rendering pass using the getEvent***(): thus, getting access to the intermediate state of rendering buffers and matrices. Some of them are read-only, but most of them can be modified ad hoc. The event handler can get a Renderer pointer.

Thanks to this feature you can get direct access to G-Buffer, SSAO, lights or any other effect. One more example: you can create a custom post-process and apply it before TAA, thus, getting correct antialiased image as a result. You can even create your own custom light sources, decals, etc. The feature can also be useful for custom sensors view.

Viewport class has different rendering modes: RENDER_DEPTH (depth only), RENDER_DEPTH_GBUFFER (depth + G-buffer), RENDER_DEPTH_GBUFFER_FINAL (depth + G-buffer + final image). This can give you extra performance boost if you need only depth info, for example.

• See the following C++/C# samples:

  • source/samples/Api/Render/GBufferWrite
  • source/samples/Api/Render/GBufferRead
  • Render to Texture sample in CPP Samples suite
  • Weapon Clipping sample in C# Component Samples suite

• See the following C++/C# usage example:

  • Creating Mirrors Using Viewports (Rendering to Texture) or a Standard Material