Second-base methods are called through an unadjusted pointer

[blowmage]

Hi. I just started playing with libqt6zig today. Not an expert in zig or qt (or c++ for that matter), and I'm unsure if this is a legit bug or a self-inflicted foot/gun scenario. Apologies if this is the wrong place to post this.

I am unable to call a QPaintDevice method from a QWidget object. My workaround has been to avoid the binding's QPaintDevice methods on widgets and obtain the same values from the widget's screen. I originally missed the workaround in README. So I had my second brain investigate further and here is some AI-generated text it spit out:

Summary

Wherever a pointer must convert to a second base class, the generated code uses @ptrCast, which reinterprets the bits and does not add the subobject offset that C++ inserts for a static_cast.

QWidget derives from QObject and QPaintDevice, so the QPaintDevice subobject sits at a nonzero offset inside every widget.
A reinterpreted widget pointer is therefore not a valid QPaintDevice*, and using it reads state and vtable slots from the wrong place.

The defect appears in two forms:

• Receiver conversion — calling a method inherited from a second base, for example widget.devicePixelRatioF().
  This crashes.
• Argument conversion — passing a widget where a second-base type is expected, for example QPainter.new2(widget).
  This does not crash; it silently misbehaves, and is the likely cause of the QPainter limitation the README already documents.

Both are the same root cause, and the README currently describes the second one as an unrelated limitation with a workaround that only appears to work.

Reproducing

The receiver form, on any widget:

const w = qopenglwidget.QOpenGLWidget.new(...);
const dpr = w.devicePixelRatioF(); // segfault: jump to address 0

Observed on Debian 13 arm64, Qt 6.8.2, Zig 0.16.0, Mesa llvmpipe.

A single-inheritance call on the same object is fine, which isolates the cause.
QOpenGLWidget.screen() emits QWidget_Screen(@ptrCast(self.ptr)), and because QWidget is QOpenGLWidget's only direct base, that pointer needs no adjustment.

Cause

The generated wrapper reinterprets the pointer:

pub fn devicePixelRatioF(self: QOpenGLWidget) f64 {
    return qtc.QPaintDevice_DevicePixelRatioF(@ptrCast(self.ptr));
}

src/opengl/libqopenglwidget.zig#QOpenGLWidget.devicePixelRatioF

The C entry point is declared on the base type, so nothing downstream can recover the offset:

double QPaintDevice_DevicePixelRatioF(const QPaintDevice* self);

src/libqpaintdevice.h, implemented in src/libqpaintdevice.cpp#QPaintDevice_DevicePixelRatioF.

@ptrCast is a bit-level reinterpretation.
C++ would emit static_cast<QPaintDevice*>(w), which adds the offset.
Zig cannot express that adjustment, because only the C++ compiler knows the layout.

The generator already has the information needed to detect the case.
CppClass.DirectInherits is an ordered list built from clang's AST (cmd/genbindings/clang2il.go), and AllInheritsClassInfo walks it recursively (cmd/genbindings/intermediate.go).
What is missing is using a base's position in that list to decide whether a conversion is free or requires an adjustment.

Blast radius

The pattern QPaintDevice_*(@ptrCast(self.ptr)) appears in 252 generated files, and second-base @ptrCast call sites total 898 across include/.
Affected methods include devicePixelRatio, devicePixelRatioF, logicalDpiX, logicalDpiY, physicalDpiX, physicalDpiY, colorCount, depth, widthMM, heightMM, and paintingActive.
In practice this is every widget class a Widgets application touches.

devicePixelRatioF is likely to be hit early, since it is the ordinary way to size a framebuffer for a high-DPI display.

The README's two workarounds do not hold

"Use QStylePainter instead of QPainter"

The limitations section reads:

Due to current limitations, QPainter does not reliably initialize within paint event callbacks, even when using manual begin() and end() calls.
The result is warnings such as "A paint device can only be painted by one painter at a time" and "Painter not active."
As a workaround, use QStylePainter instead… it properly handles the painting context that fails to be managed with the standard QPainter.

The generated constructors suggest the attribution is wrong.
The failure is not painting-context management; the painter is handed a pointer that does not address the QPaintDevice subobject:

pub fn new2(param1: anytype) QPainter {
    return .{ .ptr = qtc.QPainter_new2(@ptrCast(param1.ptr)) };
}

include/libqpainter.zig#QPainter.new2, calling QPainter_new2(QPaintDevice*).

Constructor	C signature	Conversion	Outcome
QPainter.new2(widget)	QPainter_new2(QPaintDevice*)	second base	unadjusted pointer
QStylePainter.new(widget)	QStylePainter_new(QWidget*)	first base	correct
QStylePainter.new3(pd, w)	QStylePainter_new3(QPaintDevice*, QWidget*)	second base	expected to fail

QStylePainter.new takes QWidget* (src/libqstylepainter.h), so it never performs the broken conversion.
The workaround succeeds incidentally rather than by handling the context better, which has two consequences:

• It is incomplete.
  QStylePainter.new3 takes a QPaintDevice* and should fail exactly as QPainter.new2 does, so the advice "use QStylePainter" holds for one of its three constructors and not the others.
• It is misattributed, so it steers users away from QPainter permanently instead of identifying a fixable defect.
  A user who needs QPainter on a non-widget paint device, or who passes a paint device explicitly, gets no guidance at all.

"Upcast manually with @ptrCast"

Elsewhere the README presents manual upcasting as ordinary practice:

the base class version is shadowed and can only be called via manual upcasting QWidget{ .ptr = @ptrCast(menu.ptr) }.sizeHint()

The example is safe, because QWidget is QMenu's first and only base and the offset is zero.
Stated without qualification, though, the idiom is the defect itself: the same construction targeting QPaintDevice, or any second base, silently produces an invalid pointer.
Nothing in the surrounding text marks that boundary, so a reader has no way to tell which upcasts are safe.

Proposed fix

Emit the conversion in C++, where the layout is known, and route every second-base conversion through it.
One helper per (class, non-first base) pair covers both forms of the defect:

QPaintDevice* QWidget_AsQPaintDevice(QWidget* self);

QPaintDevice* QWidget_AsQPaintDevice(QWidget* self) {
    return static_cast<QPaintDevice*>(self); // compiler adds the offset
}

Generated call sites then use it in both positions:

• Receiver: qtc.QPaintDevice_DevicePixelRatioF(qtc.QWidget_AsQPaintDevice(@ptrCast(self.ptr))), where the remaining @ptrCast is a first-base conversion and therefore safe.
• Argument: qtc.QPainter_new2(qtc.QWidget_AsQPaintDevice(@ptrCast(param1.ptr))).

Why this shape rather than a per-method entry point:

• It is comprehensive.
  A per-method approach — emitting QOpenGLWidget_DevicePixelRatioF and so on — fixes receivers only, and leaves every argument conversion such as QPainter_new2 broken.
  The QPainter limitation would survive it.
• It is smaller.
  Qt has few multiply-inheriting classes, so the generated surface grows by roughly one helper per affected pair, not one entry point per inherited method per concrete class.
• It is mechanical.
  The generator already knows the ordered base list; a base at index greater than zero needs a helper, and a base at index zero does not.

One implementation consideration worth raising in the issue: parameters are projected as anytype, so the generator must select the helper by the argument's comptime type.
That fits the existing machinery, since the library already inspects anytype parameters to cast them to the expected type, but it is the part of the change most likely to need design input from a maintainer.

What the fix retires

• The crash reported here, across all 898 second-base call sites.
• The QPainter limitation, if the diagnosis above holds — making QPainter usable in paint callbacks and the QStylePainter recommendation unnecessary.
• The unqualified upcasting advice, which can then be stated as safe, because the generator would no longer emit an unadjusted second-base conversion for users to imitate.

[rcalixte]

Hi! Thanks for the interest!

I originally missed the workaround in README. So I had my second brain investigate further and here is some AI-generated text it spit out:

While there is no official policy for this project, please follow these guidelines as a form of general etiquette. This is a lot of jargon to sift through for what appears to be a legitimate bug. I'm going to summarize this as a bug with classes that have multiple inheritance and the requirement to use helper methods that are currently not defined in the library. I was under the impression that pointer casts would apply for upcasting to parent classes and that appears to be a false assumption in many scenarios. I've historically tested this with many dual inherited classes but not directly dual-inherited in all cases such as QFile.

Ultimately, you have my gratitude since I believe that this solves a few bugs I've been trying to resolve and assuming I can have this generated smoothly, it will probably call for properly documenting somehow. This deserves an issue but I need to pare it down quite a bit before doing so.

[rcalixte]

I have an implementation working for this, not quite as suggested and there are some inaccuracies in the analysis that still leave us with some limitations. Ultimately, I believe that things are much improved as all of the crashes I've been troubleshooting are resolved. I hope to get the fix pushed out soon, ideally reviewed with some fresh eyes. Thanks again for this report. I would still encourage using your first brain for development and getting comfortable with the library. Once you have the mental model, it really is empowering!

[rcalixte]

Hi again!

These changes are now merged and available. You should be able to pull them down with a new fetch.

There are a few notes I thought were important to share. I believe the upcasting information in the documentation is valid and while these could be replaced/augmented by as<T> helper methods, I think that adding more upcasting helper methods than are required might introduce more cognitive load than it is currently worth. There is now a table for which parent types have upcast (and potentially downcast, more on that further) methods and what types they need to be invoked for. As implemented, the current base class implementations for inherited objects call the helper method directly rather than the C ABI wrapper. I thought this was a more readable solution and more importantly, I believe that it does not introduce any overhead outside of Debug mode (which would be a low single digit number of instructions at most). We might even be able to not have any extra instructions generated in Debug mode at all if we inlined the helper method explicitly but I wanted to test for possible side effects before considering that route.

The most critical corrections from the initial report is that this implementation does not resolve parameter-based secondary table references like the QPainter constructor that takes a QPaintDevice parameter type. This is not trivially resolvable without knowing the call-site class type. As an example, because the QPaintDevice does not have or need a method to upcast to itself, we would probably need to do more comptime maneuvering so that the class itself can still be passed as a parameter. This would be for the purpose of serving as an alternative to the more explicit QPainter.new2(widget.asQPaintDevice()). There are various trade-offs to be had here but I'm currently favoring the explicit upcast. That brings me to the next point which was completely omitted from the initial report: downcasting. For methods like QPainter.device() that return QPaintDevice, we need to provide a method for downcasting non-primary inherited types just the same as we do now for the upcasting. This is unfortunately not an automatic mirroring process but fortunately the generator has the information needed to determine where downcast generation is not possible.

Everything net, having this properly resolved and being able to remove the hack of a workaround bring great peace of mind. The change is a little bit noisy but it should still be decipherable. Thanks again! Happy hacking!

EDIT: After another update, the upcasting at call sites is now optional. The comptime implementation ended up not being that expensive and the result is that bare parameters will also succeed. The README has also been simplified to the mandatory use cases.