API Migration

• 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.

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

• CALLBACK_BEGIN_SHADOWS
• CALLBACK_BEGIN_WORLD_SHADOW
• CALLBACK_END_WORLD_SHADOW
• CALLBACK_BEGIN_PROJ_SHADOW
• CALLBACK_END_PROJ_SHADOW
• CALLBACK_BEGIN_OMNI_SHADOW
• CALLBACK_END_OMNI_SHADOW
• CALLBACK_END_SHADOWS

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:

• getCurrentLight()
• getShaderCBufferCamera()
• getShaderCBufferScattering()

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.

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::Render::addCallback(Unigine::Render::CALLBACK_END, 
							 MakeCallback(this, &AppWorldLogic::postRenderStep));

Unigine::Render::addCallback(Unigine::Render::CALLBACK_END_SCREEN, 
							 MakeCallback(this, &AppWorldLogic::postRenderStep));

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:

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:

• App::isLegacyMode()
• CustomApp::isLegacyMode()

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.

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):

• Angle - getAngleOverTimeModifier()
• Direction - getDirectionOverTimeModifier()
• Growth - getGrowthOverTimeModifier()
• LengthFlattening - getLengthFlatteningOverTimeModifier()
• LengthStretch - getLengthStretchOverTimeModifier()
• Position - getPositionOverTimeModifier()
• Radius - getRadiusOverTimeModifier()
• Rotation - getRotationOverTimeModifier()
• Velocity - getVelocityOverTimeModifier()
• Gravity - getGravityOverTimeModifier()

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

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));
		// ...
	}
}

You can now create widgets without specifying a GUI simplifying your code, in this case a new widget will be added to the Engine GUI. New constructors were added for the following widgets:

• WidgetButton()
• WidgetCanvas()
• WidgetCheckBox()
• WidgetComboBox()
• WidgetDialog()
• WidgetDialogColor()
• WidgetDialogFile()
• WidgetDialogImage()
• WidgetDialogMessage()
• WidgetEditLine()
• WidgetEditText()
• WidgetExtern()
• WidgetGridBox()
• WidgetGroupBox()
• WidgetHBox()
• WidgetHPaned()
• WidgetIcon()
• WidgetLabel()
• WidgetListBox()
• WidgetManipulator()
• WidgetManipulatorRotator()
• WidgetManipulatorScaler()
• WidgetManipulatorTranslator()
• WidgetMenuBar()
• WidgetMenuBox()
• WidgetScroll()
• WidgetScrollBox()
• WidgetSlider()
• WidgetSpacer()
• WidgetSpinBox()
• WidgetSprite()
• WidgetSpriteNode()
• WidgetSpriteShader()
• WidgetSpriteVideo()
• WidgetSpriteViewport()
• WidgetTabBox()
• WidgetTreeBox()
• WidgetVBox()
• WidgetVPaned()
• WidgetWindow()

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.

New Functions

• findContactByID()
• isContactInternal()
• isContactEnter()
• isContactLeave()
• isContactStay()
• addContactEnterCallback()
• setContactEnterCallback()
• removeContactEnterCallback()
• clearContactEnterCallbacks()
• addContactLeaveCallback()
• setContactLeaveCallback()
• removeContactLeaveCallback()
• clearContactLeaveCallbacks()
• renderExternalContacts()
• renderInternalContacts()

• ITERATIONS_MODE_OVERRIDE
• ITERATIONS_MODE_MULTIPLICATION
• setIterationsMode()
• getIterationsMode()

• updateBones()

• setHighPriorityContacts()
• isHighPriorityContacts()

• setAutosave()
• isAutosave()
• setPath()
• getPath()

• setAutosave()
• isAutosave()
• setPath()
• getPath()
• save()
• load()

• invertChannel()

• isDouble()
• getBuildConfig()
• getVersion()

• setToolTipText()
• setToolTipX()
• setToolTipY()
• getVBox()
• isRenderingBootScreen()
• isRenderingLoadingScreen()
• isRenderingSplashScreen()

• setNode0()
• getNode0()
• setNode1()
• getNode1()

• setShadowScreenSpaceThresholdFar()
• getShadowScreenSpaceThresholdFar()
• setShadowScreenSpaceThresholdFarDistance()
• getShadowScreenSpaceThresholdFarDistance()
• setShadowScreenSpaceStepSizeFar()
• getShadowScreenSpaceStepSizeFar()
• setShadowScreenSpaceStepSizeFarDistance()
• getShadowScreenSpaceStepSizeFarDistance()
• setShadowScreenSpaceThresholdNearDistance()
• getShadowScreenSpaceThresholdNearDistance()
• setShadowScreenSpaceStepSizeNearDistance()
• getShadowScreenSpaceStepSizeNearDistance()
• getShadowColorTexture()
• getDepthTexture()

• setTransformWithoutChildren()
• setWorldTransformWithoutChildren()
• getOldWorldPosition()

• TEXTURE_CURVE
• getTextureCurve()
• getTextureCurveOverride()
• isTextureLoaded()

• LOADING_MODE_FAST
• LOADING_MODE_FULL_MATERIALS
• LOADING_MODE_FULL_MATERIALS_SHADERS
• setLoadingMode()
• getLoadingMode()

• assignFrom()

• setBindNode()
• getBindNode().
• removeBindNode()
• setBindNodeOffset().
• getBindNodeOffset()
• setBindMode().
• getBindMode()
• setBindBoneSpace().
• getBindBoneSpace()
• setBindNodeSpace().
• getBindNodeSpace()
• addVisualizeBone().
• removeVisualizeBone()
• clearVisualizeBones().
• setVisualizeAllBones()
• isVisualizeAllBones().
• getBoneNotAdditionalBindLocalTransform()
• getBoneNotAdditionalBindObjectTransform().
• getBoneNotAdditionalBindWorldTransform()
• BIND_MODE_ADDITIVE.
• BIND_MODE_OVERRIDE.
• NODE_SPACE_LOCAL.
• NODE_SPACE_WORLD.
• BONE_SPACE_LOCAL.
• BONE_SPACE_OBJECT.
• BONE_SPACE_WORLD.

• getAngleOverTimeModifier()
• getDirectionOverTimeModifier()
• setEmitterLimitPerSpawn()
• getEmitterLimitPerSpawn()
• getGrowthOverTimeModifier()
• getLengthFlatteningOverTimeModifier()
• getLengthStretchOverTimeModifier()
• getPositionOverTimeModifier()
• getRadiusOverTimeModifier()
• getRotationOverTimeModifier()
• getVelocityOverTimeModifier()
• getGravityOverTimeModifier()

• getCollisionTime()

• CALLBACK_BEGIN_SHADOWS
• CALLBACK_BEGIN_WORLD_SHADOW
• CALLBACK_END_WORLD_SHADOW
• CALLBACK_BEGIN_PROJ_SHADOW
• CALLBACK_END_PROJ_SHADOW
• CALLBACK_BEGIN_OMNI_SHADOW
• CALLBACK_END_OMNI_SHADOW
• CALLBACK_BEGIN_SCREEN
• CALLBACK_END_SCREEN
• CALLBACK_END_SHADOWS
• PASS_PROCEDURAL_DECALS
• PASS_PROCEDURAL_FIELDS
• isAPISupported()
• setCloudsFixCoverageTiling()
• isCloudsFixCoverageTiling()
• setCloudsRounded()
• isCloudsRounded()
• setCloudsRoundedPlanetRadius()
• getCloudsRoundedPlanetRadius()
• getEnvironmentHazePhysicalAmbientColorSaturation()
• getEnvironmentHazePhysicalAmbientLightIntensity()
• getEnvironmentHazePhysicalHalfFalloffHeight()
• getEnvironmentHazePhysicalHalfVisibilityDistance()
• getEnvironmentHazePhysicalSunColorSaturation()
• getEnvironmentHazePhysicalSunLightIntensity()
• getEnvironmentHazePhysicalStartHeight()
• setShowLandscapeAlbedo()
• isShowLandscapeAlbedo()
• setLandscapeTerrainMaskDithering()
• getLandscapeTerrainMaskDithering()

• setHazePhysicalSunColorSaturation()
• getHazePhysicalSunColorSaturation()
• setHazePhysicalSunLightIntensity()
• getHazePhysicalSunLightIntensity()
• setHazePhysicalAmbientColorSaturation()
• getHazePhysicalAmbientColorSaturation()
• setHazePhysicalAmbientLightIntensity()
• getHazePhysicalAmbientLightIntensity()
• setHazePhysicalHalfFalloffHeight()
• getHazePhysicalHalfFalloffHeight()
• setHazePhysicalHalfVisibilityDistance()
• getHazePhysicalHalfVisibilityDistance()
• setHazePhysicalStartHeight()
• getHazePhysicalStartHeight()

• getCurrentLight()
• getShaderCBufferCamera()
• getShaderCBufferScattering()

• setBlendDestFunc()
• setBlendSrcFunc()
• setBlendOperation()
• setStencilFunc()
• setStencilPass()
• setStencilRef()
• setPolygonSlope()
• setPolygonBias()

• GPU_UNKNOWN
• GPU_AMD
• GPU_NVIDIA
• GPU_INTEL
• GPU_ARM
• GPU_APPLE
• GPU_IMGTEC
• GPU_QUALCOMM
• getGPUID()
• getGPUName()
• getGPUName()

• setMaxFadeTexelSize()
• getMaxFadeTexelSize()
• setMaxVisibleTexelSize()
• getMaxVisibleTexelSize()
• setMinFadeTexelSize()
• getMinFadeTexelSize()
• setMinVisibleTexelSize()
• getMinVisibleTexelSize()

• setDithering()
• getDithering()

• isValid()

• CALLBACK_PRE_WORLD_LOAD
• CALLBACK_POST_WORLD_LOAD
• CALLBACK_PRE_WORLD_SAVE
• CALLBACK_POST_WORLD_SAVE
• CALLBACK_PRE_WORLD_CLEAR
• CALLBACK_POST_WORLD_CLEAR
• loadWorld()
• addCallback()
• removeCallback()
• clearCallbacks()

• getLoadPath()

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.

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.

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]

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:

<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>

New Functions