Overview

Unreal textures in the UI

Gameface allows you to render textures managed by Unreal directly in the UI. This enables you to achieve some pretty amazing effects e.g. using the Material Editor to change how a texture looks on screen. Both static and dynamic textures are supported.

Here you can find more details on all the types of textures that are supported:

  • PreloadedTextures - This feature allows you to preload textures before the UI is rendered, which decreases its loading time
  • LiveViews - Allows the embedding of dynamic textures, rendered by Unreal, inside your UI
  • TextureAtlasing - Allows you to pack multiple Unreal textures, used in your UI, in one larger texture
  • StreamingTextures - Read more about how we handle streaming texture resource requests

Texture lifetime management

Unreal textures that will be rendered by Gameface need to have their lifetime properly managed, as the engine has many mechanisms (like garbage collection, mip level streaming and more) that can invalidate a given texture before it reaches the Gameface rendering plugin for processing.

For this reason, Gameface will always keep an extra reference to the UTexture’s FTexture2DRHIRef, in order to keep it from being destroyed while it is in use by the UI.

Generally, this is how this is handled:

  • Gameface receives a resource request for a texture and won’t reply to it until it has successfully cached the UTexture’s FTexture2DRHIRef
  • After that, the FTexture2DRHIRef, along with the actual UTexture, will be stored in our FCohTexture and picked up by a FCohTextureCollector for preservation, until it is internally processed and forwarded to the Gameface rendering backend class FCohRenoirBackend (which will happen on the render thread)
    • If during this time a UI element changes its texture or the UI element gets removed, such that the texture is no longer needed, a special OnUserImageDropped event will be fired, which will signal the FCohTextureCollector to remove the specific FCohTexture so that the memory is released
  • At some point, the FCohRenoirBackend will receive a WrapUserTexture command, where ownership of the FCohTexture will be transferred from the FCohTextureCollector to the backend’s internal texture collection
  • At a later point, the FCohRenoirBackend will receive a command for binding all textures in its collection
  • Textures in the FCohRenoirBackend collections get removed in these cases:
    • Receiving a DestroyTexture command
      • Can happen if a UI element changes its texture or the element itself gets removed
    • Destroying a View
    • Uninitializing the Gameface System

Events

The Gameface Unreal Engine plugin provides two single non-dynamic delegates that allow for custom logic to be implemented for textures that will be used in the UI:

  • Upon the FCohTextureCollector collecting a texture, right before a Gameface resource request will be signaled as “successful”
    • FCohTextureCollector::OnCohTextureCollected (executed on the Game or async thread)
  • Upon reaching the FCohRenoirBackend after a WrapUserTexture command
    • IRenderingBackend::OnWrapUserTexture (executed on the render thread)
Preloaded Textures →