QSGGeometry Class

Detailed Description

The QSGGeometry class stores the geometry of the primitives rendered with the scene graph. It contains vertex data and optionally index data. The mode used to draw the geometry is specified with setDrawingMode(), which maps directly to the graphics API's drawing mode, such as GL_TRIANGLE_STRIP, GL_TRIANGLES, or GL_POINTS in case of OpenGL.

Vertices can be as simple as points defined by x and y values or can be more complex where each vertex contains a normal, texture coordinates and a 3D position. The QSGGeometry::AttributeSet is used to describe how the vertex data is built up. The attribute set can only be specified on construction. The QSGGeometry class provides a few convenience attributes and attribute sets by default. The defaultAttributes_Point2D() function returns an attribute set to be used in normal solid color rectangles, while the defaultAttributes_TexturedPoint2D function returns attributes to be used for textured 2D geometry. The vertex data is internally stored as a void * and is accessible with the vertexData() function. Convenience accessors for the common attribute sets are available with vertexDataAsPoint2D() and vertexDataAsTexturedPoint2D(). Vertex data is allocated by passing a vertex count to the constructor or by calling allocate() later.

The QSGGeometry can optionally contain indices of either unsigned 32-bit, unsigned 16-bit, or unsigned 8-bit integers. The index type must be specified during construction and cannot be changed.

Below is a snippet illustrating how a geometry composed of position and color vertices can be built.

 struct MyPoint2D {
     float x;
     float y;
     float r;
     float g;
     float b;
     float a;

     void set(float x_, float y_, float r_, float g_, float b_, float a_) {
         x = x_;
         y = y_;
         r = r_;
         g = g_;
         b = b_;
         a = a_;
     }
 };

 QSGGeometry::Attribute MyPoint2D_Attributes[] = {
     QSGGeometry::Attribute::create(0, 2, GL_FLOAT, true),
     QSGGeometry::Attribute::create(1, 4, GL_FLOAT, false)
 };

 QSGGeometry::AttributeSet MyPoint2D_AttributeSet = {
     2,
     sizeof(MyPoint2D),
     MyPoint2D_Attributes
 };

 ...

 geometry = new QSGGeometry(MyPoint2D_AttributeSet, 2);
 geometry->setDrawingMode(GL_LINES);

 MyPoint2D *vertices = static_cast<MyPoint2D *>(geometry->vertexData());
 vertices[0].set(0, 0, 1, 0, 0, 1);
 vertices[1].set(width(), height(), 0, 0, 1, 1);

The QSGGeometry is a software buffer and client-side in terms of OpenGL rendering, as the buffers used in 2D graphics typically consist of many small buffers that change every frame and do not benefit from being uploaded to graphics memory. However, the QSGGeometry supports hinting to the renderer that a buffer should be uploaded using the setVertexDataPattern() and setIndexDataPattern() functions. Whether this hint is respected or not is implementation specific.