Optional features

You can enable the following optional features to improve performance of your applications.

Loading screen

When you start the Embedded Linux player, a separate loading screen appears (typically, within 200 ms on our reference systems) containing the 2D image configured in the Player Settings window. The initial scene content is still available except that it loads behind the loading screen.

Shader cache persistence for GLES3

Embedded Linux supports binary shader caching on the device where the Unity Player is installed for better startup timings. The cache is created at runtime after you load a shader. As this cache is written to the temporary folder:[TEMP]/[COMPANY_NAME]/[PROJECT_NAME]/UnityShaderCache/, it can be wiped when you restart the system.

To use shader caching when your system restarts, copy the cache into the Player data by following the below steps:

  1. Deploy the Unity Player to the target system.
  2. Run the application and make sure all shaders are touched.
  3. Copy all the files from [TEMP]/[COMPANY_NAME]/[PROJECT_NAME]/UnityShaderCache/ to [PATH_TO_PLAYER]/Data/UnityShaderCache/.

Notes:

  • You must refresh the cache every time the player is updated.
  • As the cache is device specific, you must only share it between devices with the exact same hardware and software configuration.

Pipeline cache persistence for Vulkan

Embedded Linux supports binary Vulkan pipeline caching on the device where the Unity Player is installed for better startup timings. The binary Vulkan pipeline cache is created at runtime when you use Vulkan pipelines. As this cache is written to the temporary file:[TEMP]/[COMPANY_NAME]/[PROJECT_NAME]/vulkan_pso_cache.bin, you can wipe it when you restart the system.

To use pipeline caching when your system restarts, copy the cache into the Player data by following the below steps:

  1. Deploy the Unity Player to the target system.
  2. Run the application and make sure all pipelines are being used.
  3. Copy [TEMP]/[COMPANY_NAME]/[PROJECT_NAME]/vulkan_pso_cache.bin file to [PATH_TO_PLAYER]/Data.

Notes:

  • You must refresh the cache every time the player is updated.
  • As the cache is device specific, you must only share it between devices with the exact same hardware and software configuration.

Startup time logging

Startup time logging is the length of time that it takes an application to start up. It's often used as a critical metric for system safety and regulatory requirements.

Startup time logging in Embedded Linux include the duration or total time (in milliseconds) since the application is launched. There are two types of Startup time logging:

  • Real: This is the actual wall or clock time, similar to a stopwatch used for calculating the time.
  • User: This is the time an application or one of its threads has spent on a CPU core. This can be higher than the Real time if multiple threads are busy when an application is starting up.

To add a startup timing log from C#, use:

HmiPlatform.LogStartupTiming("log tag");

The results appear in the following Player.log line:

[TIMING::STARTUP] log tag: Real: xxx ms | User: yyy ms

It contains the log tag, wall time (xxx), and cpu time (yyy) in milliseconds since the player's start time.

You can guard the code using #if UNITY_EMBEDDED_LINUX_API ... #endif.

Additional notes:

Use the same terminology as the Time command to refer to wall vs. CPU time. For more information, refer to the main Linux manual.

Example output

[TIMING::STARTUP] Initial probing done: Real: 19 ms | User: 11 ms
[TIMING::STARTUP] SDL Initialized: Real: 64 ms | User: 54 ms
[TIMING::STARTUP] Scripting runtime loaded: Real: 97 ms | User: 86 ms
[TIMING::STARTUP] Plugins loaded: Real: 97 ms | User: 87 ms
[TIMING::STARTUP] Engine initialized (nogfx): Real: 104 ms | User: 94 ms
[TIMING::STARTUP] Player Prefs loaded: Real: 104 ms | User: 94 ms
[TIMING::STARTUP] Screen initialized: Real: 139 ms | User: 112 ms
[TIMING::STARTUP] Engine initialized (gfx): Real: 187 ms | User: 161 ms
[TIMING::STARTUP] Gfx initialized: Real: 190 ms | User: 163 ms
[TIMING::STARTUP] Input initialized: Real: 190 ms | User: 163 ms
[TIMING::STARTUP] SPLASH - Begin: Real: 190 ms | User: 164 ms
[TIMING::STARTUP] SPLASH - Primary scene assets loaded (async): Real: 2197 ms | User: 1670 ms
[TIMING::STARTUP] SPLASH - All engine initial states established: Real: 2197 ms | User: 1670 ms

Output from a custom event using the Script API

[TIMING::STARTUP] HELLO!!: Real: 2198 ms | User: 1671 ms

When you specify platform-hmi-quit-after-frame in boot.config output, then the following will be in the log up until frame number X. Where, X is the number provided for the boot configuartion value.

[TIMING::STARTUP] Frame 1 rendered: Real: 2209 ms | User: 1687 ms

[TIMING::STARTUP] Frame 2 rendered: Real: 2210 ms | User: 1692 ms

EVDEV input handling with Wayland

To enable the EVDEV SDL2 input driver while running in Wayland, start the player with the -platform-embedded-linux-wayland-enable-evdev-input argument. You can also add it to the config file located in Data/boot.config as platform-embedded-linux-wayland-enable-evdev-input=1.

Force to use Wayland

In a system where both X11 and Wayland windowing systems are available, you can force the Unity Player to use Wayland by setting the environment variable to SDL_VIDEODRIVER=wayland.

Command line arguments

You can launch the Unity Embedded Linux Player from the command line and pass arguments to change how the Player executes.

Important: All command line arguments have precedence over the Unity Editor and boot.config settings.

CommandDetails
-log-startup-times-and-quit

[Deprecated] Quit player after rendering the first frame.

-platform-hmi-force-srgb-blitChange the forced srgb-blit setting. Refer to Player Settings > Rendering > Color Space.

-platform-hmi-quit-after-frame

Enable logging. Refer to Player Settings > Configuration > Logging.

-platform-hmi-log-startup-times

Enable logging. For more information, refer to Player Settings > Configuration > Logging.
-platform-hmi-single-gl-context

Disable context sharing for GLES.

Important: The arguments disable multi-display support.

-platform-hmi-cpu-configuration <configuration>Allows you to specify a CPU configuration for the player. Expects a string containing a combination of the letters H (high performance core), L (low performance core) and/or D (disable core). For example, DHLL for disabling the usage of the first core, tagging the second as High and the third and forth as Low performance on 4+ core CPU. Refer to Player Settings > Configuration > CPU Configuration.
-platform-hmi-player-data-path

Enter the directory path on the system where you want to save the .config and log files. Refer to Player Settings > Configuration > Player Data path.

-platform-hmi-force-vsync-count [C]The number of vertical syncs that are allowed to pass between each frame. Where, setting 0 disables vsync completely, -1 will use the value set in QualitySettings.
-platform-embedded-linux-enable-gamepadinputChange the game controller setting. Refer to Player Settings > Configuration >Enable Game Controllers.
-platform-embedded-linux-offscreen-videoConfigure player to use offscreen rendering driver from SDL2. This is helpful for simulations and creating a render server. All rendering is offscreen but will still be GPU-accelerated. Note: When using this feature you might want to cap CPU/GPU usage by setting Application.targetFrameRate.
-platform-embedded-linux-wayland-enable-evdev-inputEnable the EVDEV SDL2 input driver while running in Wayland. Refer to Optional features > EVDEV input handling with Wayland.

Additional resources:

Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.