Scene Graph - Custom Geometry example partially ported to cxx-qt

[OlivierLDff]

Scene Graph - Custom Geometry

Hi I've been experimenting cxx-qt for QQuickItem subclassing, I want to share my experience and give you some hint of what struggle I ran into.

TDLR:

• the code is available there: https://github.com/OlivierLDff/cxx-qt-experiments
• I kept the implementation of updatePaintNode in cpp (and show that it is easy not to go full rust and escape hatch are everywhere). Anyway doing bindings to have 1:1 code won't add any value to the codebase.
• I've subclass QQuickItem and inherited functions with types that are not available in cxx-qt.
• Working on a concrete example from Qt tutorial really helped me demystifying the technologies that come into play.

Note

This readme is a based on the original example.

• I recommend for you to first follow the original example, then follow this one to see how I re-implemented it using cxx-qt.
• You should be familiar with cxx and followed the tutorials in the cxx-qt documentation.
• You should have followed the cxx-qt getting started section to understand shorcut I'm taking.

The objective:

Prerequisite

You have a minimal cxx-qt project with build.rs, a main.rs and a main.qml.

BezierCurve declaration

In src/bezier_curve.rs, we declare the BezierCurve class. This class is a QQuickItem derived class.

#[cxx_qt::bridge]
pub mod ffi {
    unsafe extern "C++" {
        include!("cxx-qt-lib/qpointf.h");
        type QPointF = cxx_qt_lib::QPointF;

        include!(<QtQuick/QQuickItem>);
        type QQuickItem;
    }

    unsafe extern "RustQt" {
        #[qobject]
        #[qml_element]
        #[base = QQuickItem]
        #[qproperty(QPointF, p1)]
        #[qproperty(QPointF, p2)]
        #[qproperty(QPointF, p3)]
        #[qproperty(QPointF, p4)]
        #[qproperty(i32, segmentCount, rust_name = "segment_count")]
        type BezierCurve = super::BezierCurveRust;
    }
}

use cxx_qt_lib::QPointF;

pub struct BezierCurveRust {
    p1: QPointF,
    p2: QPointF,
    p3: QPointF,
    p4: QPointF,
    segment_count: i32,
}

impl Default for BezierCurveRust {
    fn default() -> Self {
        Self {
            p1: QPointF::new(0.0, 0.0),
            p2: QPointF::new(1.0, 0.0),
            p3: QPointF::new(0.0, 1.0),
            p4: QPointF::new(1.0, 1.0),
            segment_count: 32,
        }
    }
}

As of version 0.7.x of cxx-qt, no QQuickItem exists. This is why we import #include!(<QtQuick/QQuickItem>); in the unsafe extern "C++" block. This is a workaround until cxx-qt supports QQuickItem directly.

By itself it won't compile, because the constructor of QQuickItem expects a QQuickItem* and not a QObject*.

This can be dealt with in different ways, either using cxx_qt::Constructor trait or cxx_qt::Initialize trait. More can be found in the Traits section.

We will go with cxx_qt::Initialize trait, because we also need to initialize some stuff:

• set the ItemHasContents flag
• connect the p1, p2, p3, p4 and segment_count properties to the update() method of the QQuickItem.

#[cxx_qt::bridge]
pub mod ffi {
    // ... other code
    impl cxx_qt::Initialize for BezierCurve {}
}

impl cxx_qt::Initialize for ffi::BezierCurve {
    fn initialize(mut self: Pin<&mut Self>) {
        self.as_mut()
            .set_flag(QQuickItemFlag::ItemHasContents, true);

        self.as_mut()
            .on_p1_changed(|qobject| qobject.update())
            .release();
        self.as_mut()
            .on_p2_changed(|qobject| qobject.update())
            .release();
        self.as_mut()
            .on_p3_changed(|qobject| qobject.update())
            .release();
        self.as_mut()
            .on_p4_changed(|qobject| qobject.update())
            .release();
        self.as_mut()
            .on_segment_count_changed(|qobject| qobject.update())
            .release();
    }
}

And here we start to hit the limitations of cxx-qt. But it's ok we can deal with it ourself. We need to be able to call:

• set_flag method of QQuickItem to set the ItemHasContents flag and access the associated enum.
• Call the update() method of QQuickItem to update the item when the properties change.

All the code shouldn't be required anymore if cxx-qt supports QQuickItem directly and with the new upcast feature they are working on.

#[cxx_qt::bridge]
pub mod ffi {
    // ... other code

    unsafe extern "RustQt" {
        #[inherit]
        #[rust_name = "set_flag"]
        fn setFlag(self: Pin<&mut BezierCurve>, flag: QQuickItemFlag, enabled: bool);

        #[inherit]
        fn update(self: Pin<&mut BezierCurve>);
    }
}

So far so good, we use the inherit attribute to inherit the setFlag and update methods from QQuickItem. This allows us to call them directly on our BezierCurve object. The correct way in the future will be to upcast our BezierCurve object to QQuickItem and call the methods on it.

But what about QQuickItemFlag that I wrote? In c++ this is QQuickItem::Flag, but we can't directly access it in rust. I followed what I've seen in the cxx-qt codebase, and used the cxx documentation about extern enum. We want to use an enum that already exists in c++ world, not create a new one.

So in cpp/cxxqtlib1_qquickitem.h we have:

#pragma once
#include <QtQuick/QQuickItem>
namespace rust::cxxqtlib1
{
    using QQuickItemFlag = QQuickItem::Flag;
}

The namespace doesn't matter, but I used the one cxx-qt uses in it's codebase. Then let's use it in our code:

#[cxx_qt::bridge]
pub mod ffi {
    #[repr(i32)]
    #[namespace = "rust::cxxqtlib1"]
    #[derive(Debug)]
    enum QQuickItemFlag {
        /// Indicates this item should visually clip its children so that they are rendered only
        /// within the boundaries of this item.
        ItemClipsChildrenToShape = 0x01,
        /// Indicates the item supports text input methods.
        ItemAcceptsInputMethod = 0x02,
        /// Indicates the item is a focus scope. See Keyboard Focus in Qt Quick for more
        /// information.
        ItemIsFocusScope = 0x04,
        /// Indicates the item has visual content and should be rendered by the scene graph.
        ItemHasContents = 0x08,
        /// Indicates the item accepts drag and drop events.
        ItemAcceptsDrops = 0x10,
        /// Indicates that the item defines a viewport for its children.
        ItemIsViewport = 0x20,
        /// Indicates that the item wishes to know the viewport bounds when any ancestor has the
        /// ItemIsViewport flag set.
        ItemObservesViewport = 0x40,
    }

    #[namespace = "rust::cxxqtlib1"]
    unsafe extern "C++" {
        include!("cxxqtlib1_qquickitem.h");
        type QQuickItemFlag;
    }
}

Of course don't forget to update build.rs to include the new header file:

use cxx_qt_build::{CxxQtBuilder, QmlModule};
fn main() {
    CxxQtBuilder::new()
        // ... stuff
        .cc_builder(|cc| {
            cc.include("./cpp");
        })
        .build();
}

Overriding the paint method

From now on, I will take a shortcut of not porting the whole updatePaintNode method to rust, as this is no longer a cxx-qt usage, but more a cxx usage. Starting to work on bindings for the whole QSG* family of classes is out of scope of this example.

I believe the cxx-qt could do gradual work on adding new API, but I guess a lot of discussion should go on because they are many way to approach the problem (as with any bindings library).

Let's override the updatePaintNode method of QQuickItem to use our own BezierCurve class. Note that you will see QQuickItemUpdatePaintNodeData in the code, I used the same alias technique as for QQuickItemFlag.

#[cxx_qt::bridge]
pub mod ffi {
    unsafe extern "C++" {
        include!(<QtQuick/QSGNode>);
        type QSGNode;
    }

    unsafe extern "RustQt" {
        #[cxx_override]
        #[cxx_name = "updatePaintNode"]
        unsafe fn update_paint_node(
            self: Pin<&mut BezierCurve>,
            old_node: *mut QSGNode,
            update_paint_node_data: *mut QQuickItemUpdatePaintNodeData,
        ) -> *mut QSGNode;
    }

    unsafe extern "C++" {
        include!("beziercurve.h");
        unsafe fn bezier_curve_update_paint_node(
            old_node: *mut QSGNode,
            item_size: &QSizeF,
            p1: &QPointF,
            p2: &QPointF,
            p3: &QPointF,
            p4: &QPointF,
            segmentCount: i32,
        ) -> *mut QSGNode;
    }
}

impl ffi::BezierCurve {
    unsafe fn update_paint_node(
        self: Pin<&mut Self>,
        old_node: *mut QSGNode,
        update_paint_node_data: *mut QQuickItemUpdatePaintNodeData,
    ) -> *mut QSGNode {
        unsafe {
            return ffi::bezier_curve_update_paint_node(
                old_node,
                &self.size(),
                self.p1(),
                self.p2(),
                self.p3(),
                self.p4(),
                *self.segment_count(),
            );
        }
    }
}

And beziercurve.h mostly taken from the original example.

#pragma once

#include <QtCore/QSizeF>
#include <QtCore/QPointF>
#include <QtQuick/QQuickItem>
#include <QtQuick/QSGGeometryNode>
#include <QtQuick/QSGGeometry>
#include <QtQuick/QSGFlatColorMaterial>
#include <QtQuick/QSGNode>

QSGNode *bezier_curve_update_paint_node(QSGNode *oldNode,
                                        QSizeF const &itemSize,
                                        QPointF const &p1,
                                        QPointF const &p2,
                                        QPointF const &p3,
                                        QPointF const &p4,
                                        std::int32_t segmentCount)
{
    QSGGeometryNode *node = nullptr;
    QSGGeometry *geometry = nullptr;

    if (!oldNode)
    {
        node = new QSGGeometryNode;
        geometry = new QSGGeometry(QSGGeometry::defaultAttributes_Point2D(), segmentCount);
        geometry->setLineWidth(2);
        geometry->setDrawingMode(QSGGeometry::DrawLineStrip);
        node->setGeometry(geometry);
        node->setFlag(QSGNode::OwnsGeometry);
        auto *material = new QSGFlatColorMaterial;
        material->setColor(QColor(255, 0, 0));
        node->setMaterial(material);
        node->setFlag(QSGNode::OwnsMaterial);
    }
    else
    {
        node = static_cast<QSGGeometryNode *>(oldNode);
        geometry = node->geometry();
        geometry->allocate(segmentCount);
    }

    geometry = node->geometry();

    QSGGeometry::Point2D *vertices = geometry->vertexDataAsPoint2D();
    for (int i = 0; i < segmentCount; ++i)
    {
        qreal t = i / qreal(segmentCount - 1);
        qreal invt = 1 - t;

        QPointF pos = invt * invt * invt * p1 + 3 * invt * invt * t * p2 + 3 * invt * t * t * p3 + t * t * t * p4;

        float x = pos.x() * itemSize.width();
        float y = pos.y() * itemSize.height();

        vertices[i].set(x, y);
    }
    node->markDirty(QSGNode::DirtyGeometry);

    return node;
}

And there we should have everything!

---

Some general questions I had:

• When using wrapped type from cxx-qt there is no explanation why include!("cxx-qt-lib/qpointf.h") is required.
• Would be nice to have an example of how to add bindings to non trivial qt type that isn't supported by cxx-qt (ie what I'm doing, with the enum trick etc…)
• Would be nice to have general guideline on how to add missing bindings in user project while waiting they are part of cxx-qt.
• What minimal functionality do you expect from a quick feature? So we could have at least bindings for QQuickItem.
• Compilation errors are hard to read due to the layer of tools
• Somehow compilation is incredibly slow (15s on my mac), and it is the same at each modification. Haven't tried on linux.

Thank you for the good work.

[LeonMatthesKDAB]

Hi @OlivierLDff , great work and an interesting read, thank you for showing this here.

Your use-case is one of the exact reasons why we want to be a superset of CXX.
It should be relatively easy to hop between C++ and Rust as needed.

Something like the QSG* API may never be part of "official" CXX-Qt, as it's a (somewhat) niche API with a ton of complexity and little value to wrapping it in Rust.
The approach you took of mixing with C++ there is absolutely the right way for the foreseeable future.

You're right that more documentation on this would be useful (I'm happy to accept PRs on this if you're willing to contribute :) ).

Regarding the slow compilation: Are you using CXX-Qt 0.7.x or the main branch?
Compile-time should be a lot better on the main branch due to some build improvements we've made.
Keep an eye out for 0.8 which we're hoping to land soon.

[OlivierLDff]

Nice to here I correctly understand the position of cxx-qt. I like this approach and I think it makes lots of sense.
One thing I didn't mention is that using the qproperty macro was a very nice experience, and this is really something that I'm doing way more often in normal projects.

I will wait for 0.8 to land and see if I can contribute in the extra crate the QQuickItem related things I've had to use.

[LeonMatthesKDAB]

Awesome, thanks!

[OlivierLDff]

I compared main & 0.7:

Linux

On main:

touch src/gizmo/qml/main.qml

❯ time cargo build -p gizmo
   Compiling gizmo v0.1.0 (/home/naostage/dev/cxx-qt-experiments/src/gizmo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 6.34s
cargo build -p gizmo  24,48s user 3,34s system 437% cpu 6,365 total

On 0.7:

touch src/gizmo/qml/main.qml

❯ time cargo build -p gizmo
   Compiling gizmo v0.1.0 (/home/naostage/dev/cxx-qt-experiments/src/gizmo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 30.61s
cargo build -p gizmo  46,18s user 3,79s system 163% cpu 30,632 total

Mac

main:

touch src/gizmo/src/gizmo.rs 
❯ time cargo build -p gizmo   
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 11.10s
cargo build -p gizmo  23.65s user 4.54s system 253% cpu 11.134 total

0.7:

touch src/gizmo/src/gizmo.rs 
time cargo build -p gizmo   
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 21.42s
cargo build -p gizmo  31.24s user 4.51s system 166% cpu 21.461 total

Conclusion

So yes I can see the difference, still this is lots of time because I only have 1 qml file & one rust file. How is this scaling up? My testing branch: OlivierLDff/cxx-qt-experiments#2

[LeonMatthesKDAB]

Thanks for testing, still a bit slow though..

Hm, are you using sccache as the rustc-wrapper?
In my experience that's what helps the most with incremental builds.

But yeah, still more work to be done to improve the build experience...

[OlivierLDff]

You are right I forgot to bring sccache to the mix while trying to create a minimal flake:

❯ time cargo build -p gizmo
   Compiling gizmo v0.1.0 (/home/naostage/dev/cxx-qt-experiments/src/gizmo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 4.29s
cargo build -p gizmo  3,03s user 0,93s system 91% cpu 4,316 total

So we earn 2 seconds with sccache. I updated my PR if you want to replicate my env setup.

sccache --show-stats
Compile requests                     65
Compile requests executed            58
Cache hits                           42
Cache hits (C/C++)                   42
Cache misses                         16
Cache misses (C/C++)                 16
Cache hits rate                   72.41 %
Cache hits rate (C/C++)           72.41 %
Cache timeouts                        0
Cache read errors                     0
Forced recaches                       0
Cache write errors                    0
Cache errors                          0
Compilations                         16
Compilation failures                  0
Non-cacheable compilations            0
Non-cacheable calls                   7
Non-compilation calls                 0
Unsupported compiler calls            0
Average cache write               0.000 s
Average compiler                  3.514 s
Average cache read hit            0.000 s
Failed distributed compilations       0

Non-cacheable reasons:
crate-type                            4
missing input                         2
-                                     1