API Migration

The plugin files structure has been rearranged, approach to their naming has changed as well.

The naming convention is:

• <vendor_name><plugin_name>_plugin_<precision>_x64<debug_version>.* for Windows binaries
• lib<vendor_name><plugin_name>_plugin_<precision>_x64<debug_version>.so for Linux binaries
• <vendor_name><plugin_name>.h for headers

The paths to plugin files are as follows.

For UNIGINE plugins:

• binaries — bin\plugins\Unigine\<plugin_name> (e.g. bin\plugins\Unigine\ARTTracker\UnigineARTTracker_plugin_double_x64d.dll)
• headers — include\plugins\Unigine\<plugin_name>\Unigine<plugin_name>.h (e.g. include\plugins\Unigine\ARTTracker\UnigineARTTracker.h)

For user plugins:

• binaries — bin\plugins\<vendor_name>\<plugin_name> (e.g. bin\plugins\Vendor\Plugin\VendorPlugin_plugin_double_x64.dll)
• headers — include\plugins\<vendor_name>\<plugin_name>\<vendor_name><plugin_name>.h (e.g. include\plugins\Vendor\Plugin\VendorPlugin.h)

Adjust the build paths and plugin names for all plugins in the projects that you've migrated.

The following changes were made for this release:

1. ControlsGamePad and ControlsJoystick classes were completely replaced with InputGamepad and InputJoystick respectively with all necessary functions migrated.

   Instances of these classes are managed by the Engine, therefore, you should not create or delete them manually anymore. Previously the number of gamepads was predefined and equal to 4, so you had to get active devices via the corresponding methods (GetActiveGamePad() and GetCountActiveGamePads()), now these methods are removed, because the numbers of gamepads and joysticks changes dynamically as you connect or disconnect devices (these numbers are not limited by the Engine, while there is an SDL limit of 16 devices). To get the number of currently connected joysticks or gamepads use Input::getNumGamePads() and Input::getNumJoysticks().

   You can get a particular joystick or gamepad (as InputGamePad or InputJoystick class instances) by its number via the Input::getGamePad() and Input::getJoystick() methods.

   In case a joystick/gamepad is disconnected the corresponding InputGamePad / InputJoystick class instance is not removed from the list, you can check its availability via the isAvailable method.

   New connected devices are become bound to the first InputGamePad / InputJoystick class instance that is unbound (isAvailable == false) and become available again. In case there are no unbound instances a new one is created and added to the list.

2. Gamepads and joysticks are now updated automatically by the Engine, so the updateEvents() method is removed from InputGamePad and InputJoystick classes as unnecessary.
3. Event buffer is now available for gamepads and joysticks enabling you to avoid lost input events. You can get the last gamepad button event from the buffer via the InputJoystick::getButtonEvent() method and get the whole current buffer via InputJoystick::getButtonEvents(). The same for joysticks (InputJoystick::getButtonEvent() and InputJoystick::getButtonEvents() respectively).
4. A new set of callbacks has been added to the Input class for both, joysticks and gamepads, enabling you to track various events:
   • GAMEPAD_CONNECTED
   • GAMEPAD_DISCONNECTED
   • GAMEPAD_BUTTON_DOWN
   • GAMEPAD_BUTTON_UP
   • GAMEPAD_AXIS_MOTION
   • GAMEPAD_TOUCH_DOWN
   • GAMEPAD_TOUCH_UP
   • GAMEPAD_TOUCH_MOTION
   • JOY_CONNECTED
   • JOY_DISCONNECTED
   • JOY_BUTTON_DOWN
   • JOY_BUTTON_UP
   • JOY_AXIS_MOTION
   • JOY_POV_MOTION

See the instructions and examples below to migrate your code related to gamepads and joysticks to UNIGINE 2.17 properly:

// checking for gamepads and getting the active one
if (Input::getCountActiveGamePads() == 0)
{
	Log::error("GamepadInput::init(): No available gamepads!\n");
	return;
}

gamepad = Input::getActiveGamePad(0);

// ...

// reload the current world if X button is pressed
if (gamepad->isButtonPressed(InputGamePad::BUTTON::BUTTON_X))
	World::reloadWorld();

// activate vibration if Y button is pressed
if(gamepad->isButtonDown(InputGamePad::BUTTON::BUTTON_Y))
	gamepad->setVibration(low_frequency, high_frequency, vibration_duration);

// getting the active gamepad
if(!gamepad && Input::getCountActiveGamePads() > 0)
	gamepad = Input::getActiveGamePad(0);

// ...

// getting the name of the last pressed button
for (int i = 0; i < InputGamePad::NUM_BUTTONS; i++)
{
	if (gamepad->isButtonDown((InputGamePad::BUTTON)i))
		last_button_down = getGamePadButtonName((InputGamePad::BUTTON)i);
}

// checking for gamepads and getting the active one
if (Input::getNumGamePads() > 0)
	gamepad = Input::getGamePad(0);
else
{
	Log::error("GamepadInput::init(): No available gamepads!\n");
	return;
}

// ...

// reload the current world if X button is pressed
if (gamepad->isButtonPressed(Input::GAMEPAD_BUTTON_X))
	World::reloadWorld();

// activate vibration if Y button is pressed
if(gamepad->isButtonDown(Input::GAMEPAD_BUTTON_Y))
	gamepad->setVibration(low_frequency, high_frequency, vibration_duration);

// getting the active gamepad
if(!gamepad && Input::getNumGamePads())
	gamepad = Input::getGamePad(0);

// ...

// getting the name of the last pressed button
for (int i = 0; i < Input::NUM_GAMEPAD_BUTTONS; i++)
{
	Input::GAMEPAD_BUTTON i_button = Input::GAMEPAD_BUTTON(i);

	if (gamepad->isButtonDown(i_button))
		last_button_down = getGamePadButtonName(i_button);
}

// including a header required for managing joysticks
#include <UnigineControls.h>

// declaring the list of joysticks
Unigine::Vector<Unigine::ControlsJoystickPtr> joysticks;

// ...

// setting the number of joysticks
int count_joysticks = 4;

// creating and adding joysticks to the list
for (int i = 0; i < count_joysticks; i++)
	joysticks.append(ControlsJoystick::create(i));

// ...

for (int i =0; i < count_joysticks; i++)
{
	// performing joystick update
	joysticks[i]->updateEvents();

	// iterating over all available joysticks
	if (joysticks[i]->isAvailable())
	{
		// printing joystick number
		Log::message("Joystick Number: %s", String::itoa(joysticks[i]->getNumber()));

		// getting the names of pressed buttons
		for (int j = 0; j < joysticks[i]->getNumButtons(); j++)
			if (joysticks[i]->getButton(j) != 0)
				last_pressed_buttons[i] = joysticks[i]->getButtonName(j);
	}
}

// ...

// removing all created joysticks
for(int i =0; i < joysticks.size(); i++)
	joysticks[i].deleteLater();

// including a header required for managing joysticks
#include <UnigineInput.h>

// declaring the list of joysticks
Unigine::Vector<Unigine::InputJoystickPtr> joysticks;

// ...

// setting the number of joysticks
int count_joysticks = Input::getNumJoystics();

// adding joysticks to the list
for (int i = 0; i < count_joysticks; i++)
	joysticks.append(Input::getJoystick(i));

// ...

for (int i =0; i < count_joysticks; i++)
{

	// iterating over all available joysticks
	if (joysticks[i] && joysticks[i]->isAvailable())
	{
		// printing joystick number
		Log::message("Joystick Number: %s", String::itoa(i));

		// getting the names of pressed buttons
		for (int j = 0; j < joysticks[i]->getNumButtons(); j++)
			if (joysticks[i]->getButton(j) != 0)
				last_pressed_buttons[i] = joysticks[i]->isButtonPressed(j);
	}
}

// ...

// just clearing the list of joysticks (instances are managed by the Engine)
joysticks.clear();

Added a new background update mode to ensure rendering for windows minimized to tray (this can be useful for grabbing frame sequences in background when the application window is minimized). Thee modes are available now:

• BACKGROUND_UPDATE_DISABLED - Background update is disabled.
• BACKGROUND_UPDATE_RENDER_NON_MINIMIZED - Background update is enabled (rendering is performed when the window is out of focus, but stops if the window is minimized).
• BACKGROUND_UPDATE_RENDER_ALWAYS - Background update is always enabled (rendering is performed all the time, regardless of the window state.

To manage modes use setBackgroundUpdate() / getBackgroundUpdate() methods.

Engine::get()->setBackgroundUpdate(true);

Engine::get()->setBackgroundUpdate(Engine::BACKGROUND_UPDATE_RENDER_NON_MINIMIZED);

Implementation of Vulkan and DirectX 12 support has changed a lot, and the old-style way of getting GPU-generated data on CPU has become invalid.

Thus, we have removed Texture::getImage/StructuredBuffer::getData() methods and added the following ones instead:

• Render::transferTextureToImage() - getting an image inside a callback-function in the same frame (swap). Calls CPU-GPU synchronization (like it was before).
• Render::asyncTransferTextureToImage() - getting an image inside a callback-function without calling CPU-GPU synchronization. The Engine Loop should cycle again and again to complete this async operation
• Render::transferStructuredBuffer()/asyncTransferStructuredBuffer() - similar to StructuredBuffer

All other methods transferring data generated by GPU to CPU (returning the result as an Image) have been replaced with the ones that return their result as a Texture. In order to get this data as Image (the way it was before) you'll have to transfer the obtained data to CPU using a synchronous or asynchronous transferring method of the Render class - Render::transferTextureToImage() or Render::asyncTransferTextureToImage() respectively. This is relevant for methods like Viewport::renderImage*(), Render::renderImage*(), FieldShoreline::createShorelineDistanceField(), WidgetSpriteViewport::renderTexture(), and others. Render::compressImage()/Render::asyncCompressImage() represent the only exception - they cannot output the result to a texture accepting callbacks as arguments.

temporary_texture = Render::getTemporaryTexture2D(window->getRenderSize().x, window->getRenderSize().y, Texture::FORMAT_RGB8);
temporary_texture->copy2D();

// transferring texture data to CPU
temporary_texture->getImage(image);

// flipping image if necessary
if (!Render::isFlipped())
	image->flipY();
	
// saving an image to a file
image->save("screenshot.dds");

TexturePtr temporary_texture = Render::getTemporaryTexture2D(window->getClientRenderSize().x, window->getClientRenderSize().y, Texture::FORMAT_RGB8);
temporary_texture->copy2D();

// transferring texture data to CPU
Render::asyncTransferTextureToImage(
	nullptr,
	MakeCallback([this](ImagePtr image)
		{
			// flipping image if necessary
			if (!Render::isFlipped())
				image->flipY();

			// saving an image to a file
			image->save("screenshot.dds");

		}),
	temporary_texture);

Other related API changes:

• A new createMipmapsCubeGGX() method has been added to the Image class to enable generation of GGX mipmaps on CPU, of course slower and with lower quality than on GPU but providing the result synchronously (actually this should be the only case, when this method is to be used).
• The ImageConverter class now has a new run() method with a callback making it possible to use GPU, and runCpu() that uses CPU only and is capable of returning the result synchronously.
• Added new Engine::beginOutsideLoopRender()/endOutsideLoopRender(), methods for cases when it is required to call Render class methods from outside the Engine's Loop.
• Render::transferTextureToImage()/Render::transferStructuredBuffer() callbacks will be called in endOutsideLoopRender(). It is recommended to render inside the Engine Loop whenever possible.

To avoid various issues with passing unsafe pointers to arrays when creating, setting, or getting values of matrices (mat2, mat3, mat4, and dmat4) we have added a pack of safe types for them (mat2x2_values, mat3x3_values, etc.) and replaced all constructors, setters, and getters that received unsafe pointers with new ones receiving these safe types.

So, starting from 2.17 when creating, setting, or getting values of matrices you'll have to specify the corresponding types explicitly. You can also use the old-style way at your own risk if you want, as we have added a set of unsafe conversion functions to MathLib, that you'll have to call when using unsafe pointers.

float *elements;
elements = new float[9];

// ...

Math::mat3 myMatrix = Math::mat3(elements);

// - - - - - - - - - - - - - - 
//        New Style
// - - - - - - - - - - - - - - 
Math::mat3x3_values elements;

// ...

Math::mat3 myMatrix = mat3(elements);

// - - - - - - - - - - - - - - 
//        Old Style
// - - - - - - - - - - - - - - 
float *elements;
elements = new float[9];

// ...

Math::mat3 myMatrix; 
myMatrix = Math::mat3(Math::unsafeToMat3x3(elements));

New Math Functions

New Functions

New Functions

New Functions

New Functions

New Functions

New Functions

New Functions