Rendering UIRenderer Sprites#

If any changes are made to text or matrices or similar, for the sprite which will be rendered, call its commitUpdates() function.

There is no need to call commitUpdates() on every single sprite, although it will still execute and cause some overhead. This is only necessary if a sprite needs to be rendered both on its own and inside a container. Otherwise, only call commit updates on the container (the object on which render() is called), and the container itself will take care of correctly preparing its children items for rendering.

Note

It is perfectly legal to render a sprite from more than one container. For instance, create the text “Hello” and then render it from five different containers, one spinning, one still, one raw, and so on. Then call commitUpdates() and render() on each of those.

The steps required to render a sprite with UIRenderer are:

  1. Call uiRenderer->beginRendering(…).

    In Vulkan, this takes a SecondaryCommandBuffer where the rendering commands will be recorded.

    Note

    • If the command buffer is open (beginRecording() has been called) when uiRenderer->beginRendering() is called, the commands will be appended. In the end, the command buffer will not be closed when endRendering() is called.

    • If the command buffer is closed (beginRecording() has not been called) when uiRenderer->beginRendering() is called, the command buffer will be reset and opened. Then, when finished rendering with uiRenderer->endRendering(), the command buffer will be closed, and endRecording() will be called on it.

  2. Call the render() method on all top level sprites that will be rendered - the containers, not the contents.

    Do not call render on a component that is contained in another component, as the result is not what would be expected. It will be rendered as if it was not a part of the other component. So if there are two images and a group that contains ten texts and another two images, only three render() calls are necessary.

  3. Call the uiRenderer->endRendering() method.

For OpenGL ES, that is all, the rendering of the objects is complete. The state should be as it was before the beginRendering() command, so any state changes between the beginRendering() and endRendering() commands will be lost.

For Vulkan, the secondary command buffer passed as a parameter in the beginRendering() command will now contain the rendering commands such as bind pipelines, buffers, descriptor sets, and draw commands for the UI. It must be submitted inside the render pass and sub pass which were used to initialise the UIRenderer, or a compatible render pass.