Introduction to UIRenderer Sprites and Layouts#

The class that is most commonly accessed when using the UIRenderer is pvr::ui::Sprite. A sprite is an object that can be laid out and rendered using UIRenderer. The sprite is aware of and references a specific pvr::UIRenderer. The sprite allows the developer to render() it and set things like its colour and rendering mode.

The layout itself and the positioning are not done by the sprite interface class. Instead, subclasses of pvr::ui::Sprite will normally provide methods to lay it out, depending on its specific capabilities.

There are two main categories of layout: the 2DComponent and the MatrixComponent.

2D components provide methods to lay the component out in a screen-aligned rectangle, providing methods for anchoring to the corners, offsetting by X/Y pixels, rotations, scaling, and so on.

Note

  • Position refers to the position of a sprite relative to the component it is added to. For example, the top-left corner of the UIRenderer’s surface.

  • Anchor refers to the point on the sprite that position is calculated from. For example, the top-left corner of the sprite.

  • Rotation is the angle of the sprite around the anchor.

  • Scale is the sprite’s size compared to its natural size. Scales are relative to the anchor.

  • Offset is a number of pixels to move the final position by, relative to the parent container, and relatively to the finally scaled sprite

Matrix components directly take a matrix for 3D positioning of the component.

All predefined primitive sprites (pvr::ui::Text, pvr::ui::Image) are 2D components.

Complex layouts can be achieved using pvr::ui::Group. Groups are hierarchical containers of other components including other groups. For example, there could be a PixelGroup representing a panel with components. Text sprites and an image could be added and positioned to this group, which is then added into a MatrixGroup. Finally, the MatrixGroup could be transformed with a projection matrix to display it in a Star Wars intro scrolling marquee way. This use case is shown in the IntroducingUIRenderer example.