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 InputGamepad.GetButtonEvent() method and get the whole current buffer via InputGamepad.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:

InputGamePad.BUTTON runButton = InputGamePad.BUTTON.SHOULDER_RIGHT;

InputGamePad.BUTTON jumpButton = InputGamePad.BUTTON.A;

InputGamePad.BUTTON crouchButton = InputGamePad.BUTTON.SHOULDER_LEFT;

// getting the first active gamepad
if (Input.CountActiveGamePads > 0)
   		 gamepad = Input.GetActiveGamePad(0);

Input.GAMEPAD_BUTTON runButton = Input.GAMEPAD_BUTTON.SHOULDER_RIGHT;

Input.GAMEPAD_BUTTON jumpButton = Input.GAMEPAD_BUTTON.A;

Input.GAMEPAD_BUTTON crouchButton = Input.GAMEPAD_BUTTON.SHOULDER_LEFT;

// getting the first active gamepad
for (int i = 0; i < Input.NumGamePads; i++)
{
	 Unigine.InputGamePad gamepad = Input.GetGamePad(i);
	 if (game_pad.IsAvailable)
	 {
		 last_gamepad = gamepad;
		 break;
	 }
 }

int JoysticksCount = 4;
List<InputJoystick> joysticks = new List<ControlsJoystick>();
for (int i = 0; i < JoysticksCount; i++)
{
	// create new joystick
	ControlsJoystick joystick = new ControlsJoystick(i);
	if (!joystick)
		break;
	joysticks.Add(joystick);
}

for (int i = 0; i < joysticks.Count; i++)
		{
			JoysticksInfo[i].isAvailable = joysticks[i].IsAvailable;
			if (!JoysticksInfo[i].isAvailable)
				continue;

		}
			joysticks[i].UpdateEvents();

			// update pressed button
			for (int j = 0; j < joysticks[i].NumButtons; j++)
				if (joysticks[i].GetButton(j) != 0)
				{
					JoysticksInfo[i].lastPressedButton = j;
					break;
				}

List<InputJoystick> joysticks = new List<InputJoystick>();
for (int i = 0; i < Input.NumJoystics; i++)
{
	// get joystick
	InputJoystick joystick = Input.GetJoystick(i);
	if (!joystick)
		break;

	joysticks.Add(joystick);
}
int JoysticksCount = joysticks.Count;

for (int i = 0; i < joysticks.Count; i++)
		{
			JoysticksInfo[i].isAvailable = joysticks[i].IsAvailable;
			if (!JoysticksInfo[i].isAvailable)
				continue;
		}
		
// update pressed button
			for (int j = 0; j < joysticks[i].NumButtons; j++)
			{
				if (joysticks[i].IsButtonPressed((uint)j))
				{
					JoysticksInfo[i].lastPressedButton = j;
					break;
				}
			}

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.BackgroundUpdate = true;

Engine.BackgroundUpdate = Engine.BACKGROUND_UPDATE.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.

// creating a new image
Image image = new Image();

// transferring GPU data to CPU
viewport.RenderImage2D(player.Camera, image, width, height);

// flipping image if necessary
if (!Render.IsFlipped)
	image.FlipY();
	
// saving an image to a file
image.Save("screenshot.dds");

// creating a new texture
Texture texture = new Texture(); 

// rendering to a texture
viewport.RenderTexture2D(player.Camera, texture, width, height);

// transferring texture (GPU) data to CPU
Render.AsyncTransferTextureToImage(
	null,
	(Image image) =>
		{
			// flipping image if necessary
			if (!Render.IsFlipped)
				image.FlipY();

			// saving an image to a file
			image.Save("screenshot.dds");
		},
	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.

New Functions

New Properties

New Functions

New Functions

New Properties

New Functions

New Functions

New Functions

New Functions

New Properties

New Functions

New Properties

New Functions

New Functions

New Functions