This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
Полезные советы
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Программирование
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
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
Внимание! Эта версия документация УСТАРЕЛА, поскольку относится к более ранней версии SDK! Пожалуйста, переключитесь на самую актуальную документацию для последней версии SDK.
Внимание! Эта версия документации описывает устаревшую версию SDK, которая больше не поддерживается! Пожалуйста, обновитесь до последней версии SDK.

API Migration

Major Changes

Breaking Changes#

Removal and Deprecation List#

  • World Layer and World Cluster, which were marked earlier as deprecated, are removed.
  • WorldLogic::destroyRenderResources() has been removed since now reloading of all graphic resources is automatically handled by UNIGINE when the video mode is changed.
  • Sun Shafts effect has been considered deprecated and removed. It is recommended to use Volumetric objects instead.
  • Render::renderProcedurals() method as well as textures of the "filter" type are considered deprecated and will be removed in future versions. Please, use scriptable materials instead.

Render Callbacks Changes#

The structure of render callbacks has changed with the following ones added:

Now you can use the following methods inside Render callbacks to get a shadow map for a light source (new BEGIN_SHADOWS callbacks listed above) or to obtain camera or scattering parameters and pass them to your custom shaders:

The semantics of CALLBACK_BEGIN and CALLBACK_END callbacks has changed, so now they enclose the whole sequence including both common stages (such as shadows rendering) and per-screen ones. You can use them, for example, to to get a combined projection for both eyes. Each of per-screen sequences (performed for each of the two eyes in case of stereo rendering, or for each of the 6 sides in case of cubemap rendering) is enclosed by CALLBACK_BEGIN_SCREEN and CALLBACK_END_SCREEN. So if you try to get a projection matrix here in case of stereo rendering, you'll get it only for a certain eye or side of the cube.

UNIGINE 2.11 UNIGINE 2.12
Render::CALLBACK_BEGIN The semantics has changed. Use Render::CALLBACK_BEGIN_SCREEN instead.
Render::CALLBACK_END The semantics has changed. Use Render::CALLBACK_END_SCREEN instead.

At the moment when CALLBACK_END is fired all render resources are released, so restoring your callbacks logic you had in 2.11 may require changes like the ones below:

UNIGINE 2.11
Source code (C++)
Unigine::Render::addCallback(Unigine::Render::CALLBACK_END, 
							 MakeCallback(this, &AppWorldLogic::postRenderStep));
UNIGINE 2.12
Source code (C++)
Unigine::Render::addCallback(Unigine::Render::CALLBACK_END_SCREEN, 
							 MakeCallback(this, &AppWorldLogic::postRenderStep));

Loading Screens#

Due to changes with loading screens, the Splash class has been replaced with the LoadingScreen class. Now there are no separate System, World and custom splash screens, they all are called Loading Screens and controlled by the corresponding singleton class. Therefore, the methods, which were specific for each type of splash screen, have been merged. Also, a set of methods and parameters has been changed:

UNIGINE 2.11. Splash class UNIGINE 2.12. LoadingScreen class
setColor() Removed. Use rich text formatting instead.
setSplash() Removed. Use setTexturePath() and setThreshold() instead.
setSplashBackground() Removed. Use setBackgroundColor() instead.
setSplashImage() Removed. Use setImage() instead.
setSplashText() Removed. Use setText() instead.
setSplashTransform() Removed. Use setTransform() instead.
setSystem() Removed. Use setTexturePath() and setThreshold() instead.
setSystemBackground() Removed. Use setBackgroundColor() instead.
setSystemImage() Removed. Use setImage() instead.
setSystemText() Removed. Use setText() instead.
setSystemTransform() Removed. Use setTransform() instead.
setWorld() Removed. Use setTexturePath() and setThreshold() instead.
setWorldBackground() Removed. Use setBackgroundColor() instead.
setWorldImage() Removed. Use setImage() instead.
setWorldText() Removed. Use setText() instead.
setWorldTransform() Removed. Use setTransform() instead.
renderSplash() Removed. Use render() instead.
renderSystem() Removed. Use render() instead.
renderWorld() Removed. Use render() instead.

Important Apps-Related Changes#

New boot screen requires rendering to be performed at the Engine's initialization stage. Certain applications do not support rendering in the init() by design. To ensure stable operation for such apps you can disable render-during-init functionality by setting the legacy mode (available for Engine’s App and CustomApp classes via the isLegacyMode() method). Thus, the boot screen won't be displayed for these applications.

The following new methods were added to API:

Graphic context cannot be destroyed during the operation of any UNIGINE application, so the application is required to be closed before destroying the context. This means you’ll have to revise your implementation of changing video mode in case it destroys graphic context.

Particle System Parameters Management#

Some parameters of particle systems are now controlled via modifiers (ParticleModifierScalar or ParticleModifierVector). The list of such parameters includes (getter-methods for the corresponding modifier are given for each):

Any changes to such parameter are made by getting the corresponding modifier and using its methods:

Source code (C++)
ObjectParticlesPtr particles = ObjectParticles::create();
ParticleModifierScalarPtr angle_modifier = particles->getAngleOverTimeModifier();

switch (angle_modifier->getMode()) {
	case  ParticleModifier::MODE_CONSTANT:
	{
		// setting the 'angle' parameter as constant
		angle_modifier->setConstant(30);
	}
	case  ParticleModifier::MODE_RANDOM_BETWEEN_TWO_CONSTANTS:
	{
		// setting upper and lower bounds for the 'angle' parameter
		angle_modifier->setConstantMin(30);
		angle_modifier->setConstantMax(90);
	}
	case  ParticleModifier::MODE_CURVE:
	{
		// getting a curve to manage keys thus adjusting the angle variation
		Curve2dPtr angle_curve = angle_modifier->getCurve();
		angle_curve->addKey(vec2(0.5f, 0.5f));
		// ...
	}
}

Widget Creation Changes#

Duration and Depth Testing For Visualizer Elements#

You can now control depth testing for each Visualizer element (point, line, triangle, circle, etc.) as well as time period during which each element shall be displayed. The corresponding arguments were updated for all related methods of the Visualizer class.

UNIGINE 2.11 UNIGINE 2.12
renderPoint2D() Set of arguments changed.
renderPoint3D() Set of arguments changed.
renderBillboard3D() Set of arguments changed.
renderBox() Set of arguments changed.
renderCapsule() Set of arguments changed.
renderCircle() Set of arguments changed.
renderCone() Set of arguments changed.
renderCylinder() Set of arguments changed.
renderDirection() Set of arguments changed.
renderEllipse() Set of arguments changed.
renderFrustum() Set of arguments changed.
renderBoundBox() Set of arguments changed.
renderBoundSphere() Set of arguments changed.
renderNodeBoundBox() Set of arguments changed.
renderNodeBoundSphere() Set of arguments changed.
renderNodeHandler() Set of arguments changed.
renderObject() Set of arguments changed.
renderObjectSurface() Set of arguments changed.
renderSolidObject() Set of arguments changed.
renderSolidObjectSurface() Set of arguments changed.
renderObjectSurfaceBoundBox() Set of arguments changed.
renderObjectSurfaceBoundSphere() Set of arguments changed.
renderQuad2D() Set of arguments changed.
renderQuad3D() Set of arguments changed.
renderSector() Set of arguments changed.
renderSphere() Set of arguments changed.
renderSolidBox() Set of arguments changed.
renderSolidSphere() Set of arguments changed.
renderSolidCapsule() Set of arguments changed.
renderSolidCylinder() Set of arguments changed.
renderSolidEllipse() Set of arguments changed.
renderTriangle2D() Set of arguments changed.
renderTriangle3D() Set of arguments changed.
renderVector() Set of arguments changed.
renderLine2D() Set of arguments changed.
renderLine2D() Set of arguments changed.
renderLine2D() Set of arguments changed.
renderLine3D() Set of arguments changed.
renderLine3D() Set of arguments changed.
renderLine3D() Set of arguments changed.
renderMessage2D() Set of arguments changed.
renderMessage3D() Set of arguments changed.

New Functions

Body Class#

BodyFracture Class#

UNIGINE 2.11 UNIGINE 2.12
getMaterialName() Renamed as getMaterial().
getSurfacePropertyName() Renamed as getSurfaceProperty().

BodyParticles Class#

BodyRagdoll Class#

New Functions

BodyRigid Class#

Config Class#

UNIGINE 2.11 UNIGINE 2.12
flush() Removed. Use save() instead.
load() Set of arguments changed.
save() Set of arguments changed.

New Functions

Console Class#

UNIGINE 2.11 UNIGINE 2.12
getActivity() Renamed as isActive().

ControlsApp Class#

UNIGINE 2.11 UNIGINE 2.12

New Functions

Image Class#

UNIGINE 2.11 UNIGINE 2.12
assignFrom() Set of arguments changed.

New Functions

Engine Class#

UNIGINE 2.11 UNIGINE 2.12
getExternDefines() Renamed as getExternDefine().

New Functions

FileSystem Class#

UNIGINE 2.11 UNIGINE 2.12
getModifier() Return value type changed.

Gui Class#

Joint Class#

Light Class#

Node Class#

Material Class#

UNIGINE 2.11 UNIGINE 2.12
setOffset() Removed.
getOffset() Removed.

New Functions

Materials Class#

UNIGINE 2.11 UNIGINE 2.12
setOffset() Removed.
getOffset() Removed.

New Functions

Mesh Class#

New Functions

ObjectMeshSkinned Class#

ObjectParticles Class#

UNIGINE 2.11 UNIGINE 2.12
setAngle() Removed. Use getAngleOverTimeModifier() instead.
setAngularDamping() Removed.
getAngularDamping() Removed.
setEmitterDirection() Removed. Use getDirectionOverTimeModifier() instead.
getEmitterDirection() Removed. Use getDirectionOverTimeModifier() instead.
setEmitterLimit() Removed. Use setEmitterLimitPerSpawn() instead.
getEmitterLimit() Removed. Use getEmitterLimitPerSpawn() instead.
setEmitterSpread() Removed. Use getDirectionOverTimeModifier() instead.
getEmitterSpread() Removed. Use getDirectionOverTimeModifier() instead.
setGravity() Removed. Use getGravityOverTimeModifier() instead.
getGravity() Removed. Use getGravityOverTimeModifier() instead.
setGrowth() Removed. Use getGrowthOverTimeModifier() instead.
getGrowthMean() Removed. Use getGrowthOverTimeModifier() instead.
getGrowthSpread() Removed. Use getGrowthOverTimeModifier() instead.
setGrowthDamping() Removed.
getGrowthDamping() Removed.
setLengthFlattening() Removed. Use getLengthFlatteningOverTimeModifier() instead.
getLengthFlattening() Removed. Use getLengthFlatteningOverTimeModifier() instead.
setLengthStretch() Removed. Use getLengthStretchOverTimeModifier() instead.
setLengthStretch() Removed. Use getLengthStretchOverTimeModifier() instead.
setParticlesRotation() Removed. Use getRotationOverTimeModifier() instead.
getParticlesRotationMean() Removed. Use getRotationOverTimeModifier() instead.
getParticlesRotationSpread() Removed. Use getRotationOverTimeModifier() instead.
setParticlesRotation() Removed. Use getRotationOverTimeModifier() instead.
getParticlesRotationMean() Removed. Use getRotationOverTimeModifier() instead.
getParticlesRotationSpread() Removed. Use getRotationOverTimeModifier() instead.
setRadius() Removed. Use getRadiusOverTimeModifier() instead.
getRadiusMean() Removed. Use getRadiusOverTimeModifier() instead.
getRadiusSpread() Removed. Use getRadiusOverTimeModifier() instead.
setVelocity() Removed. Use getVelocityOverTimeModifier() instead.
getVelocityMean() Removed. Use getVelocityOverTimeModifier() instead.
getVelocitySpread() Removed. Use getVelocityOverTimeModifier() instead.

New Functions

Physics Class#

UNIGINE 2.11 UNIGINE 2.12
getUpdateTime() Removed. Use the getCollisionTime() method of the Render class instead.
getBroadTime() Removed. Use the getCollisionTime() method instead.
loadSettings() Set of arguments changed.

New Functions

Render Class#

UNIGINE 2.11 UNIGINE 2.12
PASS_OBJECT_POST Removed.
loadSettings() Set of arguments changed.
setStreamingTexturesCachePreload() Removed.
isStreamingTexturesCachePreload() Removed.
renderProcedurals() Removed.
setFPSStabilization() Removed.
isFPSStabilization() Removed.
setFPSStabilizationSpeedUP() Removed.
getFPSStabilizationSpeedUP() Removed.
setFPSStabilizationSpeedDown() Removed.
getFPSStabilizationSpeedDown() Removed.
setFPSStabilizationMin() Removed.
getFPSStabilizationMin() Removed.
setFPSStabilizationRounding() Removed.
getFPSStabilizationRounding() Removed.
setFPSStabilizationOffset() Removed.
getFPSStabilizationOffset() Removed.

New Functions

RenderEnvironmentPreset Class#

Renderer Class#

UNIGINE 2.11 UNIGINE 2.12
setPolygonOffset() Removed.

New Functions

RenderState Class#

Sound Class#

UNIGINE 2.11 UNIGINE 2.12
loadSettings() Set of arguments changed.

SystemInfo Class#

TerrainDetail Class#

TerrainDetailMask Class#

Texture Class#

New Functions

World Class#

WorldLogic Class#

UNIGINE 2.11 UNIGINE 2.12
destroyRenderResources() Removed.

Xml Class#

UNIGINE 2.11 UNIGINE 2.12
load() Set of arguments changed.

New Functions

Syncker Plugin#

  • Added an ability to connect additional slaves on the fly (sync_allow_extra_slaves 1) for the synchronous mode (sync_async = 0). However, stable work may require additional effort as channels launched with a significant delay can skip some packets sent from the Master.
  • In case only the Master is present (-sync_count 1) and connection of additional slaves on the fly is enabled (sync_allow_extra_slaves 1) the session shall start immediately and lasts forever (until the Master is on).
  • The setSlavePlayer(slave_index/view_name, player) method now affects only the specified Slave as expected. Synchronization settings for all other Slaves will remain the same and the camera will be automatically changed for them after calling the Game::setPlayer() method on the Master. A crash related to calling the setSlavePlayer() method for a new connected slave was also fixed.
  • Added a new SKIP_FLAGS::SET_PLAYER flag for Slaves to ignore setSlavePlayer() calls by the Master for them.
  • Function call buffering is enabled for Syncker. In case of calling Master::loadNode(), Master::loadNodeReference(), or Master::createNode() methods on the Master these calls are put to a buffer and sent to each new Slave connecting during the active session (sync_allow_extra_slaves 1).
  • Fixed issues with the Master::createNode() method, now it returns a bool value (true - on success).

IG Changes#

Packet IDs#

The sendUserMessage() method now has a packet ID argument, so now you can tell exactly what was sent, unlike in 2.11 and earlier versions. This method can be called from anywhere and at any time, you can subscribe to any packet you want.

Initialization#

Added a new OnIGReady callback - it is used for initialization of various user settings. Since 2.12 you can initialize your settings only when the IG is ready, otherwise Slaves may not receive some data. The best place for initialization of user settings is inside this callback.

Loading Worlds#

The world_load console command doesn’t work now! Do not use the following in your launchers: -console_command "world_load world_name"

It is recommended to specify the ID of the desired database in the autoload_database parameter of the ig_config.xml configuration file instead.

To load the world in case you don’t have a connector available and the default world is not set you can use the following console command: database_load [id]

Working with Cameras#

Cameras in IG are synchronized in a special way. IG now has the following methods to set the desired view for a Slave:

  • void setCurrentView(int view_id);
  • void setSlaveView(int slave_index, int view_id);

A View - is an IG wrapper for the Player, so you can manage a camera via the View only. In case of a multi-channel application the following methods of the View class can be used:

  • copyDefinitionFromPlayer() - to copy projection from a usual camera to the view.
  • copyTransformFromPlayer() - to copy the transformation of a usual camera to the view.

You can also create a dedicated component to copy all camera settings to the view each frame, when necessary.

In the configuration file you can set the desired view for each Slave and specify if it is affected by the Syncker’s projections:

Source code (XML)
<syncker_channels>
	<channel syncker_name="center_view" view_id="0" use_syncker_projection="1"/>
	<channel syncker_name="left_view" view_id="0" use_syncker_projection="1"/>
	<channel syncker_name="ground_cam" view_id="1" use_syncker_projection="0"/>
</syncker_channels>

IG::Entity Class#

UNIGINE 2.11 UNIGINE 2.12
setRate() Removed. Use setVelocity() instead.

New Functions

Last update: 06.08.2020
Build: ()