QCanvasPainterFactory Class
QCanvasPainterFactory manages instances of QCanvasPainter and the associated rendering engine. More...
| Header: | #include <QCanvasPainterFactory> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter) |
| Since: | Qt 6.11 |
Public Functions
| QCanvasPainterFactory() | |
| QCanvasPainter * | create(QRhi *rhi) |
| void | destroy() |
| bool | isValid() const |
| QCanvasRhiPaintDriver * | paintDriver() |
| QCanvasPainter * | painter() |
Static Public Members
| QCanvasPainterFactory * | sharedInstance(QRhi *rhi) |
Detailed Description
Applications rendering via QCanvasPainter do not create instances of the painter class themselves, but rather are expected to use a QCanvasPainterFactory.
Note: This class is relevant only when working with QCanvasPainter without a convenience class such as QCanvasPainterWidget or QCanvasPainterItem, because those provide a QCanvasPainter instance to the application.
The following is an example code snippet of getting a QCanvasPainter for use with an existing, successfully initialized QRhi:
std::unique_ptr<QCanvasPainterFactory> factory(new QCanvasPainterFactory);
QCanvasPainter *painter = factory->create(rhi);
QCanvasRhiPaintDriver *paintDriver = factory->paintDriver();All drawing code that operates on the same thread with the same QRhi is recommended to share and reuse the same QCanvasPainter, instead of having a dedicated painter (and so factory) in each component. This can be achieved by calling sharedInstance(), instead of constructing a new QCanvasPainterFactory:
QCanvasPainterFactory *factory = QCanvasPainterFactory::sharedInstance(rhi);
QCanvasPainter *painter = factory->painter();
QCanvasRhiPaintDriver *paintDriver = factory->paintDriver();Member Function Documentation
QCanvasPainterFactory::QCanvasPainterFactory()
Constructor.
See also sharedInstance().
QCanvasPainter *QCanvasPainterFactory::create(QRhi *rhi)
Initializes the QCanvasPainter rendering infrastructure, if it has not been done already for this factory.
Returns the painter, or null if the renderer could not be initialized.
The factory will be associated with rhi, and it cannot be used with any other QRhi, unless destroy(), and then create() are called again.
Repeated calls to this function have no effect and are harmless. Call destroy() first if a reinitialization of the painter infrastructure is desired, possibly with a different rhi.
Note: There is no need to call this function when sharedInstance() was used to retrieve a factory instance.
See also destroy(), isValid(), and painter().
void QCanvasPainterFactory::destroy()
Tears down the rendering infrastructure. Normally there is no need to call this function. Rather, it is used in situations where it will be followed by a create().
See also create().
bool QCanvasPainterFactory::isValid() const
Returns true if the create() has ben called successfully.
QCanvasRhiPaintDriver *QCanvasPainterFactory::paintDriver()
Returns the paint driver object, or null if isValid() is false.
Note: The returned object is not owned by the caller.
QCanvasPainter *QCanvasPainterFactory::painter()
Returns the painter, or null if isValid() is false.
Note: The returned object is not owned by the caller.
[static] QCanvasPainterFactory *QCanvasPainterFactory::sharedInstance(QRhi *rhi)
Returns a QCanvasPainterFactory instance associated with the given rhi.
Calling this function with the same rhi will always return the same QCanvasPainterFactory.
There is no need to call create() on the returned factory, and the painter() can be queried right away, because the result is always already initialized, meaning isValid() returns true.
This function is thread safe. However, the QRhi threading rules apply as usual: a QRhi object, and by extension, an instance of QCanvasPainterFactory, QCanvasRhiPaintDriver, and QCanvasPainter associated with that QRhi are all expected to be used on the same one single thread.
Note: The returned QCanvasPainterFactory is not owned by the caller, and it becomes invalid when rhi is destroyed.
See also painter().
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
