Asynchronous Data Streaming

Data streaming is an optimization technique intended to reduce spikes caused by loading graphic resources. With this technique, not all the data is loaded into memory at once. Instead, only the required data is loaded, and the rest is loaded progressively on demand.

Resource loading is performed and transferred to the GPU in separate asynchronous threads. After that, resources are synchronized and added to the virtual scene on the CPU side.

In UNIGINE, asynchronous data streaming is enabled by default. To disable asynchronous data streaming, enable the Forced mode in the Streaming Settings in the Editor or by using the render_streaming_mode 1 console command. The Forced mode ensures force-loading of all meshes and textures required for each frame at once (e.g., grabbing frame sequences, rendering node previews, warmup, etc.).

When you need to stream all required data for the first frame as soon as possible, you may need to enable the Force mode right after the world is loaded and disable it after couple of frames to turn on the default Async mode again.

The streaming system provides asynchronous loading of the following data to RAM:

• All texture runtime files and textures with the Unchanged option enabled, including cubemaps, voxel probe maps, and shadow maps of baked shadows.
• Meshes of ObjectMeshStatic, ObjectMeshClutter, and ObjectMeshCluster objects.

You can obtain general information on streamed resources by using the render_streaming_info console command.

It is also possible to print the list of loaded resources and detailed information on them by using the render_streaming_list console command.

Procedurally generated objects such as ObjectMeshClutter and ObjectGrass are generated in a separate thread, significantly reducing performance costs.

The Render Budget parameter limits the number of loaded/created graphic resources per frame. Use it to find the balance between loading speed and performance.

To take advantage of multithreading, set the maximum number of threads used for resource streaming by using the render_streaming_max_threads console parameter. A higher number of threads results in faster streaming but may cause spikes in the case of excessive consumption of GPU resources.

By default, the Memory Limit control is enabled. Resources unnecessary for rendering at the moment are unloaded on exceeding specified memory. Maximum memory amounts are defined for meshes, textures, and particles separately via the Memory Limit values specified in a percentage of the total GPU memory.

The graphic resources are regularly checked for being modified in order to be reloaded or deleted. The Destroy Duration defines the corresponding resource cleanup interval in number of frames.

The streaming system uses the texture cache composed of minimized copies generated for all textures with user-defined resolution stored in the data/.cache_textures folder. These copies are used instead of the originals while they are being loaded.

Texture cache is loaded at Engine's startup and always stays in the memory after loading. The following default loading order ensures smooth loading and rendering of resources:

1. Texture cache;
2. Geometry;
3. Uncached textures cause spikes as texture cache is generated for them on the fly; materials with uncached and unloaded textures applied are rendered black;
4. Full-size textures.

Using the textures_cache_preload flag in the boot config file, you can choose the texture cache loading priority — preloaded or loaded after geometry data.

By default, texture cache files are generated with a resolution of 16 x 16 px. Such a low resolution of textures may be noticeable during loading.

Control the resolution of texture cache by setting the Texture Cache Resolution parameter. To apply changes, wipe away existing cache files by using the render_streaming_textures_cache_destroy console command, after which the texture cache will be generated automatically with the new specified resolution.

The video memory amount currently occupied by the texture cache is available in the Performance Profiler tool.

The render_streaming_textures_cache_load and render_streaming_textures_cache_unload console commands enable you to control loading of texture cache. For example, after loading full-size textures, you can unload the texture cache from video memory for better performance.

Settings and workflow for OpenGL API are slightly different than for DirectX API.

Under OpenGL, the Data Streaming System engages two intermediate buffers to provide data transfer between CPU and new resource:

• Async Buffer used for mesh and texture streaming
• Async Buffer Indices used for streaming of vertex indices of meshes

The size of the Async Buffer buffer must correspond to the size of the largest resource (mesh/texture); otherwise, in the case of a larger resource, the buffer will be resized, causing a spike.

The Async Buffer Synchronization parameter stands for the mechanism of buffer synchronization. So, async buffers are created only once and then synchronized, reducing the time on allocating and freeing memory. When the synchronization is disabled, both Async Buffer and Async Buffer Indices are created anew for each new resource. This reduces the number of buffer synchronizations but increases the number of memory allocations.

Sometimes (depending on the hardware/driver used, e.g., when the main thread is affected by synchronization primitives in other threads), memory allocation may be faster than synchronizations; in such cases, when streaming becomes unacceptably slow, it is recommended to disable buffer synchronization.

There are some known issues and workarounds for some hardware/driver software:

• The Mesa 3D GL: The buffer synchronization must be disabled (gl_async_buffer_synchronization 0) for better performance. The updated Open Graphics Drivers are required.
• Intel: It is necessary to consider that VRAM is limited by OS to one-half of RAM.