This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Materials and Shaders
Rebuilding the Engine 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
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Unigine::LightPlanarProbe Class

Header: #include <UnigineLights.h>
Inherits from: Light

This class is used to create and manage Planar Reflection Probes the implement planar reflections functionality (used to create mirrors etc.). The probe grabs the reflection, and requires a surface to project the reflection onto. There is a set of parameters enabling you to tweak the look of your reflections and optimize rendering load (by limiting visibility distance, reflections rendering distance, etc.).

Usage Example#

In the example below a Planar Reflection Probe is created along with a plane primitive. The surface of the primitive serves for projecting the reflection grabbed by the probe (the reflection is projected only within the area of intersection of the probe and the surface). Some parameters of the material assigned to the reflecting surface are also tweaked in order to provide the desired effect and match roughness range (which enables rendering of reflections depending on surface roughness).

Create a new class named PlanarReflector and copy .h and .cpp files into respective files of a class. Then assign a property generated for your component to any desired node of the Object type, to see its albedo texture replaced by a new created image.

PlanarReflector.h
#pragma once
#include <UnigineComponentSystem.h>
#include <UnigineObjects.h>
#include <UnigineLights.h>

class PlanarReflector :
	public Unigine::ComponentBase
{
public:
	COMPONENT_DEFINE(PlanarReflector, Unigine::ComponentBase);
	COMPONENT_INIT(init);

private:
	// declaring a reflecting plane and a planar reflection probe
	Unigine::ObjectMeshDynamicPtr plane;
	Unigine::LightPlanarProbePtr planar_probe;
	void init();
};
PlanarReflector.cpp
#include "PlanarReflector.h"
#include <UniginePrimitives.h>
#include <UnigineObjects.h>
#include <UnigineLights.h>
REGISTER_COMPONENT(PlanarReflector);

using namespace Unigine;

void PlanarReflector::init()
{
	// creating a reflecting plane, onto which the reflection is to be projected by the probe
	plane = Primitives::createPlane(20, 20, 1);

	// creating a planar reflection probe of the same size
	planar_probe = LightPlanarProbe::create();
	planar_probe->setProjectionSize(Math::vec3(20, 20, 1));
	plane->rotate(-90.0f, 0.0f, 0.0f);
	plane->translate(0.0f, 5.0f, -5.0f);

	// putting the planar probe so that it covers the reflecting surface
	planar_probe->setTransform(plane->getTransform());

	// inheriting a new material from the one assigned
	// to the surface by default in order to tweak it
	// and set metalness and roughness values (metallic and polished)
	MaterialPtr plane_mat = plane->getMaterialInherit(0);
	plane_mat->setParameterFloat("metalness", 1.0f);
	plane_mat->setParameterFloat("roughness", 0.0f);

	// set the distance from the camera, up to which 
	// the planar reflection will be visible
	planar_probe->setVisibleDistance(5.0f);
}

LightPlanarProbe Class

Enums

REFLECTION_RESOLUTION#

NameDescription
REFLECTION_RESOLUTION_MODE_HEIGHT = 0Reflection texture size equals to the viewport height resolution.
REFLECTION_RESOLUTION_MODE_HALF_HEIGHT = 1Reflection texture size equals to half of the viewport height resolution.
REFLECTION_RESOLUTION_MODE_QUART_HEIGHT = 2Reflection texture size equals to the quarter of the viewport height resolution.
REFLECTION_RESOLUTION_MODE_128 = 3Reflection texture size equals to 128x128 pixels.
REFLECTION_RESOLUTION_MODE_256 = 4Reflection texture size equals to 256x256 pixels.
REFLECTION_RESOLUTION_MODE_512 = 5Reflection texture size equals to 512x512 pixels.
REFLECTION_RESOLUTION_MODE_1024 = 6Reflection texture size equals to 1024x1024 pixels.
REFLECTION_RESOLUTION_MODE_2048 = 7Reflection texture size equals to 2048x2048 pixels.
REFLECTION_RESOLUTION_MODE_4096 = 8Reflection texture size equals to 4096x4096 pixels.

Members


LightPlanarProbe ( ) #

Constructor. Creates a new planar probe.

static int type ( ) #

Returns the object node type.

void setProjectionSize ( const Math::vec3 & size ) #

Sets the size for the planar probe. Defines the box-shaped influence volume around the probe, in units, in which reflective surfaces (having the appropriate roughness values) shall use the results captured by the probe.

Arguments

  • const Math::vec3 & size - The size along X, Y and Z axes. The default value is (2.0f, 2.0f, 0.1f).

Math::vec3 getProjectionSize ( ) const#

Returns the current size of the planar probe. Defines the box-shaped influence volume around the probe, in units, in which reflective surfaces (having the appropriate roughness values) shall use the results captured by the probe.

Return value

The size along X, Y and Z axes. The default value is (2.0f, 2.0f, 0.1f).

void setAttenuationDistance ( const Math::vec3 & distance ) #

Sets the attenuation distance that specifies how far the projection can reach any surfaces from the Probe position. It also specifies the attenuation area around the Probe at which the projection starts to fade out at the specified rate.

Arguments

  • const Math::vec3 & distance - Attenuation distance. The default value is (0.1f, 0.1f, 0.1f).

Math::vec3 getAttenuationDistance ( ) const#

Returns the attenuation distance that specifies how far the projection can reach any surfaces from the Probe position. It also specifies the attenuation area around the Probe at which the projection starts to fade out at the specified rate.

Return value

Attenuation distance. The default value is (0.1f, 0.1f, 0.1f).

void setRoughnessSamples ( int samples ) #

Sets the number of samples used to adjust quality of the blurring effect for the reflection on rough surfaces.

Arguments

  • int samples - Number of roughness samples. The default value is 0.

int getRoughnessSamples ( ) const#

Returns the number of samples used to adjust quality of the blurring effect for the reflection on rough surfaces.

Return value

Number of roughness samples. The default value is 0.

void setReflectionResolution ( LightPlanarProbe::REFLECTION_RESOLUTION resolution ) #

Sets the resolution of the reflection texture for the projection.

Arguments

LightPlanarProbe::REFLECTION_RESOLUTION getReflectionResolution ( ) const#

Returns the resolution of the reflection texture for the projection.

Return value

Reflection resolution. The default value is REFLECTION_RESOLUTION_MODE_HEIGHT.

void setTwoSided ( bool sided ) #

Sets the value indicating if two-sided reflection is enabled.

Arguments

  • bool sided - true to enable two-sided reflection; false - to disable it. The default value is false.

bool isTwoSided ( ) const#

Returns the value indicating if two sided reflection is enabled.

Return value

true if two sided reflection is enabled; false disabled. The default value is false.

void setStereoPerEyeEnabled ( bool enabled ) #

Sets the value indicating if rendering of the reflection for each eye separately is enabled.

Arguments

  • bool enabled - true to enable stereo rendering per each eye; false - to disable it.

bool isStereoPerEyeEnabled ( ) const#

Returns the value indicating if rendering of the reflection for each eye separately is enabled.

Return value

true if stereo rendering per each eye is enabled; false disabled.

void setDistanceScale ( float scale ) #

Sets the distance multiplier for the reflection visibility distance. Distance Scale is applied to the distance measured from the reflection camera to the node (surface) bound.

Arguments

  • float scale - Distance scale multiplier for the reflection. The default value is 0.5f.

float getDistanceScale ( ) const#

Returns the distance multiplier for the reflection visibility distance. Distance Scale is applied to the distance measured from the reflection camera to the node (surface) bound.

Return value

Distance scale multiplier for the reflection. The default value is 0.5f.

void setReflectionDistance ( float distance ) #

Sets the render distance for the reflection that specifies how far the reflection is rendered from the camera.

Arguments

  • float distance - Reflection render distance in units. The default value is 100.0f.

float getReflectionDistance ( ) const#

Returns the render distance for the reflection that specifies how far the reflection is rendered from the camera.

Return value

Reflection render distance in units. The default value is 100.0f.

void setReflectionViewportMask ( int mask ) #

Sets the viewing mask that specifies materials for which reflections are to be rendered in the viewport.

Arguments

  • int mask - Reflection viewport mask (integer, each bit of which is used to represent a mask).

int getReflectionViewportMask ( ) const#

Returns the viewing mask that specifies materials for which reflections are to be rendered in the viewport.

Return value

Reflection viewport mask (integer, each bit of which is used to represent a mask).

int getVisibilitySkipFlags ( ) const#

Returns a bit mask that specifies what objects to skip rendering. Chosen object types won't be rendered in the reflection.

Return value

Visibility bit mask (integer, each bit of which is used to represent a mask)

void setZNear ( float znear ) #

Sets the distance to the near clipping plane for image grabbing.

Arguments

  • float znear - Distance to the near clipping plane. The default value is 0.01f.

float getZNear ( ) const#

Returns the distance to the near clipping plane for image grabbing.

Return value

Distance to the near clipping plane. The default value is 0.01f.

void setZFar ( float zfar ) #

Sets the distance to the far clipping plane defining a frustum to be used for grabbing reflections.

Arguments

  • float zfar - Distance to the far clipping plane. The default value is 100.0f.

float getZFar ( ) const#

Returns the distance to the near clipping plane defining a frustum to be used for grabbing reflections.

Return value

Distance to the far clipping plane. The default value is 100.0f.

void setReflectionVisibilityRoughnessMin ( float val ) #

Sets the bound of the roughness range of the at which the reflection of the planar probe starts to attenuate.

Arguments

  • float val - Minimal visibility roughness bound. The default value is 0.0f.

float getReflectionVisibilityRoughnessMin ( ) const#

Returns the bound of the roughness range of the at which the reflection of the planar probe starts to attenuate.

Return value

Minimal visibility roughness bound. The default value is 0.0f.

void setReflectionVisibilityRoughnessMax ( float val ) #

Sets the higher bound of the roughness range at which the reflection of the planar probe disappears completely.

Arguments

  • float val - Maximal visibility roughness. The default value is 0.25f.

float getReflectionVisibilityRoughnessMax ( ) const#

Returns the higher bound of the roughness range at which the reflection of the planar probe disappears completely.

Return value

Maximal visibility roughness. The default value is 0.25f.

void setVisibilitySky ( bool sky ) #

Sets a value indicating if sky is rendered in the reflection.

Arguments

  • bool sky - true to enable sky rendering in reflection; false.

bool isVisibilitySky ( ) const#

Returns a value indicating if sky is rendered in the reflection.

Return value

true if sky rendering in the reflection is enabled; otherwise false.

void setParallax ( float parallax ) #

Sets degree of reflection distortion. Distortion depends on an angle between the probe plane and the surface onto which the probe projects reflection. Increasing the value amplifies visual distortion as a result of increasing this angle.

Arguments

  • float parallax - Degree of reflection distortion within the range of [0;1].

float getParallax ( ) const#

Returns current degree of reflection distortion. Distortion depends on an angle between the probe plane and the surface onto which the probe projects reflection. Increasing the value amplifies visual distortion as a result of increasing this angle.

Return value

Degree of reflection distortion within the range of [0;1].

void setNoiseIntensity ( float intensity ) #

Sets the intensity of jitter for roughness samples that creates a noise effect on the reflection.

Arguments

  • float intensity - Intensity of reflection noisiness. The default value is 0.5f.

float getNoiseIntensity ( ) const#

Returns current intensity of jitter for roughness samples that creates a noise effect on the reflection.

Return value

Intensity of reflection noisiness. The default value is 0.5f.

void setReflectionOffset ( float offset ) #

Sets reflection Z axis offset relative to the probe coordinate system.

Arguments

  • float offset - Reflection offset along Z axis in units. The default value is 0.01f.

float getReflectionOffset ( ) const#

Returns reflection Z axis offset relative to the probe coordinate system.

Return value

Reflection offset along Z axis in units. The default value is 0.01f.
Last update: 2023-06-23
Build: ()