Efficient custom shapes in Qt Quick

QtQuick includes basic visual item to construct many common user-interface components, but people often ask how to create different visual appearances, beyond rectangles, round-rectangles and images. There’s various solutions to this problem, and with Qt 5.10, there’s the new Shapes module which makes it easy to define paths, ellipses and other standard SVG drawing elements.

However, if these built-in solutions aren’t quite what is needed, or you need to squeeze some additional performance from limited hardware, it’s always possible to create a custom Item using the Scene-Graph API of Qt Quick, and some knowledge of hardware drawing APIs, such as OpenGL and GLES. This is usually a somewhat complex solution, and it’s important to stick to the design philosophy of Qt Quick: create simple, efficient and re-usable items which can be configured via properties. Here I want to show an example item which was inspired by one of KDAB’s Automotive customers: an angular sector:

Defining the Geometry

When creating a subclass of QQuickItem, you define the standard interface to QML as normal: via Q_PROPERTY macros, slots, and Q_INVOKABLE methods. (Such as the radius and color properties in the QML snippet above). But most importantly you must override the updatePaintNode method, and use this to describe the scene-graph nodes which correspond to your item. The scene-graph system in Qt Quick is an efficient mechanism to describe your visual pieces to the hardware APIs, but it’s very different from imperative drawing APIs such as the venerable QPainter. Your visuals must be defined as a tree of nodes, which can specify opacity, clipping, a transformation or most importantly, geometry. Geometry nodes contain both geometry - triangles, usually - and some mechanism to define how the pixels in those triangles are drawn; that mechanism is called a material in the scene-graph, and is closely related to a shader in OpenGL or other hardware APIs.

The first step in defining our sector item, then, is to compute a set of triangles covering the item, based on the inner and outer radius, and the start and end angles. Why are we restricted to triangles? Well, that’s really the only thing hardware knows how to draw; APIs such as the Shapes module have to ultimately translate everything you provide into triangles. So we split our sector into triangles, but of course a triangle has straight sides. We could accept this and some ‘polygonal’ edges on our shapes (as happened in the first few generations of 3D video games and graphics), but we can do better. One solution is to use more, smaller triangles - so that the straight outer edges become a closer approximation of the curved sector we want. But this has its own problems - more triangles means more geometry data to be updated when the sector changes, and potentially slower rendering. (Although in practice, most modern graphics hardware can draw a lot of triangles).

However, we can be smarter, and enable some additional features by using a different approach - we can use fewer triangles, but ensure they are larger than we need, so the entire sector is covered by triangles. Inside our shader code, we will use the discard GLSL keyword to make those pixels transparent, and this also gives us an easy way to smooth the edges of the sector (anti-aliasing), or even render a border. In this method, we're no longer considering our triangle geometry to mean 'pixels defining our shape' but rather 'pixels where we can potentially decide what happens'. Of course we could simply use two triangles covering the entire shape, but there is a cost to evaluating each pixel, so a coarse fit as shown below, is a tradeoff between complexity of the geometry, and covering unecessary amounts of the screen.

Inside the QSGGeometry API, we need to define how many points (vertices) we have, and the X and Y positions of each, using some trigonometry. Unfortunately it’s hard to get very far in APIs such as OpenGL without some basic knowledge of linear algebra and trigonometry, but fortunately there’s many examples to work from. Inside the main code, we subdivide the sector into triangles, and generate the three vertices for each one. The most important piece of trigonometry is to compute X and Y (cartesian) values from polar (angle + radius) form, and of course we have to translate from degrees to radians.

Here's the code which creates our node and associated geometry:

Once this is done, we can ask the geometry to give us a pointer to the storage it allocated internally to hold our vertices and indices. Note that we're using one of the default vertex attribute formats here, TexturedPoint2D. This means each vertex stores four values: X, Y and two other values called S and T we can use. There's other built-in formats, but if you need, you can supply a custom one. Very often, one of the basic three (Point2D, TexturedPoint2D or ColoredPoint2D) will suffice however, and they save some typing! Here's how we retrieve a pointer to the memory we must fill in with our vertices:

Then we need to run some loops, computing the values to insert into the arrays:

The S and T values, we will actually pass the cartesian values again, but modified slightly, so we can compute the polar position of each pixel accurately in our material (see the next post in this series!).
Of course, many triangles in our geometry share the same vertices. Graphics is all about efficiency, so rather than repeating our vertices, we only include each one a single time. Then we use a separate piece of data to indicate which triangles use which vertices. This is called the index data, and it's simply a list of integers, specify vertices by, you guessed, their index. Again the QSGGeomtry will allocate storage for this based on a size we pass in, and can give us a pointer to that memory, to be filled in:

The scene-graph API requires us to perform explicit management of memory and resources - this is because it’s optimised for speed and efficiency, not comfort. And it allows materials and geometry to be shared between nodes or items, so we need to explicitly state if we own our geometry. (You can see in the snippets above, we have to explicitly tell the node, it owns the geometry and hence can delete it) If our item properties change (for example, the radius), we need to recompute our geometry, but then also tell the scene-graph data we made changes, because internally there’s a hardware buffer which needs to be updated; that’s an operation we need to avoid doing if nothing has changed, so we have to explicitly mark the data as changed (‘dirty’) so it will copied to the GPU on the next Qt Quick drawing frame.

If you forget to tell either the geometry or the node, that something has changed, the hardware data won't be updated, and you won't see your changes.
Putting this all together, we now have a way to get our geometry object populated with vertices and indices. Each vertex defines an X,Y position, and each group of three index values identify three vertices, and hence one triangle. We can use some basic trigonometry to work out the X,Y values from our angles and radii. Whenever our angles or radii change, we'll need to recompute our geometric data, and tell the scene-graph that the data is dirty (modified).
If we wanted to show our shape with a simple color, we could now use QSGFlatColorMaterial and we'd be done. As the name suggests, this built-in material will draw ever pixel in your triangles, in a single color. But we want something prettier, so we need a custom material. We'll see how to do that, in the next part.