1.4.0.3
Gameface
Rendering Architecture
Note
As mentioned in the Product Overview, Gameface is powered by the Cohtml library. Respectively, all C++ classes reside in the cohtml namespace. This document will use the name of the library (Cohtml) instead of the name of SDK (Gameface) for the rest of it.

Cohtml draws the UI (a View) in a user-provided texture. This happens by calling cohtml::ViewRenderer::SetRenderTarget. The texture must have 4 color channels and depth and stencil buffers attached. On OpenGL, a complete framebuffer must be passed with all its attachments set.

Cohtml performs incremental rendering by updating only the parts of the UI texture that have changed. It will not redraw everything in the UI, which improves performance significantly. The user should not draw anything on the UI texture except the output of Cohtml. Internally Cohtml uses the Coherent Labs Renoir graphics library.

Cohtml asynchronously records rendering commands that are later executed in the render thread when calling cohtml::ViewRenderer::Paint(). This method draws the new frame if one was recorded or returns immediately if nothing in the UI has changed.

This is the reason every View object has a corresponding ViewRenderer. The View lives on the main thread and "controls" the page, while the ViewRenderer is only in charge of drawing it and lives on the render thread.

Backends

On different platforms, Cohtml can draw with different rendering APIs. The API specific code is encapsulated in a Renoir backend. The application can also define its own rendering backend that uses the graphics facilities it has or modify the existing backends provided in the Cohtml package.

The backend is registered and used with a call to cohtml::SystemRenderer::RegisterRenderThread. This call tells Cohtml which is the render thread and what backend to use during View rendering.

The backends themselves are objects that implement the renoir::RendererBackend interface. The backends provided in the Cohtml package can be used as a starting point for modification or for implementing new backends.

Cohtml comes with the following backends:

  • DirectX 11
  • DirectX 12
  • Metal
  • Vulkan
  • OpenGL 3.3+
  • OpenGL ES 2
  • OpenGL ES 3
  • libGNM
Note
The Metal and Vulkan backends expect to textures in which it draws to have RGBA pixel format.
Warning
The Vulkan backend requires the VK_KHR_MAINTENANCE1 device extension to be enabled, because it passes negative height in the VkViewport in order to force y-inversion of the clip-space to framebuffer-space transform.

Rendering Platform Specifics

The Vulkan SDK includes validation layers, which hook into API entry points and provide debugging functionality. In our samples we enable Vulkan validation layers by default on Windows, but not on Android. The motivation for this is, that on Android the layers should be explicitly packaged in the apk. Generally the following guide should be followed. Alternatively, if you want to package the validation layers in an already built apk you can use ApkTool and SignApk to do so. This can be achieved by extracting all the tools in the apk output directory and executing a script similar to the following one:

@ECHO OFF
SETLOCAL
SET FileName=ActivityCohtml
SET Platform=armeabi-v7a
SET AndroidNDKPath=C:\Microsoft\AndroidNDK64\android-ndk-r16b
SET ValidationLayerFolder=%AndroidNDKPath%\sources\third_party\vulkan\src\build-android\jniLibs\%Platform%
SET ApkTool=apktool_2.3.3.jar
ECHO %FileName%
java -jar %ApkTool% d %FileName%.apk`
copy /Y %ValidationLayerFolder%\libVkLayer_core_validation.so %FileName%\lib\%Platform%\
copy /Y %ValidationLayerFolder%\libVkLayer_image.so %FileName%\lib\%Platform%\
copy /Y %ValidationLayerFolder%\libVkLayer_object_tracker.so %FileName%\lib\%Platform%\
copy /Y %ValidationLayerFolder%\libVkLayer_parameter_validation.so %FileName%\lib\%Platform%\
copy /Y %ValidationLayerFolder%\libVkLayer_swapchain.so %FileName%\lib\%Platform%\
copy /Y %ValidationLayerFolder%\libVkLayer_threading.so %FileName%\lib\%Platform%\
copy /Y %ValidationLayerFolder%\libVkLayer_unique_objects.so %FileName%\lib\%Platform%\
java -jar %ApkTool% b %FileName%
move %FileName%\dist\%FileName%.apk %FileName%_UNALIGNED.apk
java -jar signapk.jar certificate.pem key.pk8 %FileName%_UNALIGNED.apk %FileName%.apk
del %FileName%_UNALIGNED.apk
rmdir /s /q %FileName%
ENDLOCAL

Advanced Rendering Debugging

Developers have the possibility to gain further insight in the rendering commands generated by the runtime by calling the View::EmitRenderingMetadata method. Metadata markers will be inserted in the rendering command stream that can be hooked to third-party tools like PIX, RenderDoc, Razor etc. or internal engine profilers. The markers will show which elements generate every rendering command in the stream.

Note: Enabling this option would only be reserved during application development and debugging as it incurs a significant CPU overhead!