QQuickPaintedItem Class
QQuickPaintedItem クラスは、QML シーングラフ内でQPainter API を使用する方法を提供します。詳細...
| ヘッダー: | #include <QQuickPaintedItem> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| 継承元: | QQuickItem |
パブリック型
| enum | PerformanceHint { FastFBOResizing } |
| flags | PerformanceHints |
| enum | RenderTarget { Image, FramebufferObject, InvertedYFramebufferObject } |
プロパティ
- fillColor : QColor
- renderTarget : RenderTarget
- textureSize : QSize
パブリック関数
| QQuickPaintedItem(QQuickItem *parent = nullptr) | |
| virtual | ~QQuickPaintedItem() override |
| bool | antialiasing() const |
| QColor | fillColor() const |
| bool | mipmap() const |
| bool | opaquePainting() const |
| virtual void | paint(QPainter *painter) = 0 |
| QQuickPaintedItem::PerformanceHints | performanceHints() const |
| QQuickPaintedItem::RenderTarget | renderTarget() const |
| void | setAntialiasing(bool enable) |
| void | setFillColor(const QColor &) |
| void | setMipmap(bool enable) |
| void | setOpaquePainting(bool opaque) |
| void | setPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true) |
| void | setPerformanceHints(QQuickPaintedItem::PerformanceHints hints) |
| void | setRenderTarget(QQuickPaintedItem::RenderTarget target) |
| void | setTextureSize(const QSize &size) |
| QSize | textureSize() const |
| void | update(const QRect &rect = QRect()) |
再実装されたパブリック関数
| virtual bool | isTextureProvider() const override |
| virtual QSGTextureProvider * | textureProvider() const override |
シグナル
| void | fillColorChanged() |
| void | renderTargetChanged() |
| void | textureSizeChanged() |
再実装された保護関数
| virtual void | itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value) override |
| virtual void | releaseResources() override |
| virtual QSGNode * | updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data) override |
詳細な説明
QQuickPaintedItem を使用すると、QML シーングラフでQPainter APIを利用できるようになります。これは、シーングラフ内にテクスチャ付きの矩形を設定し、QPainter を使用してそのテクスチャに描画を行います。Qt 6におけるレンダリングターゲットは常にQImage です。レンダリングターゲットがQImage の場合、QPainter はまず画像にレンダリングを行い、その後その内容をテクスチャにアップロードします。 再描画をトリガーするには、update() を呼び出します。
QPainter でアンチエイリアスレンダリングを有効にするには、setAntialiasing()を使用します。
独自のペイントアイテムを作成するには、まず QQuickPaintedItem のサブクラスを作成し、その唯一の純粋仮想パブリック関数であるpaint() を実装することから始めます。この関数が実際のペイント処理を実装します。ペイントは、0,0 からwidth()、height() に及ぶ矩形内で行われます。
注: このようなアイテムが引き起こす可能性のあるパフォーマンスへの影響を理解することが重要です 。QQuickPaintedItem::RenderTarget およびQQuickPaintedItem::renderTarget を参照してください。
「シーングラフ - ペイントされたアイテム」および「C++ を使用した QML 拡張機能の作成」も参照してください 。
メンバ型のドキュメント
enum QQuickPaintedItem::PerformanceHint
flags QQuickPaintedItem::PerformanceHints
この列挙型は、QQuickPaintedItem のレンダリングパフォーマンスを向上させるために有効にできるフラグを表しています。デフォルトでは、これらのフラグはいずれも設定されていません。
| 定数 | 値 | 説明 |
|---|---|---|
QQuickPaintedItem::FastFBOResizing | 0x1 | Qt 6.0 以降、この値は無視されます。 |
PerformanceHints 型は、QFlags<PerformanceHint> の typedef です。これは、PerformanceHint 値の論理和(OR)を格納します。
enum QQuickPaintedItem::RenderTarget
この列挙型は、QQuickPaintedItem のレンダリングターゲットを表します。レンダリングターゲットとは、アイテムが画面上にレンダリングされる前に、QPainter が描画を行うサーフェスのことです。
| 定数 | 値 | 説明 |
|---|---|---|
QQuickPaintedItem::Image | 0 | デフォルト。QPainter は、ラスター描画エンジンを使用してQImage に描画を行います。画像の内容はその後グラフィックスメモリにアップロードされる必要があり、アイテムが大きい場合、この処理に時間がかかる可能性があります。このレンダリングターゲットでは、高品質なアンチエイリアシングと高速なアイテムのサイズ変更が可能です。 |
QQuickPaintedItem::FramebufferObject | 1 | Qt 6.9 以降、この値は、使用されるレンダリング API が OpenGL である場合に限り、ハードウェアアクセラレーションによる描画を有効にします。それ以外の場合は無視されます。 Qt 6.0 から Qt 6.8 までのバージョンでは、すべてのレンダリング API においてこの値は無視されます。これにより通常はレンダリング性能が向上しますが、アンチエイリアシングの品質が犠牲になります。 |
QQuickPaintedItem::InvertedYFramebufferObject | 2 | FramebufferObject と同じですが、レンダリングが X 軸を中心に反転します。 |
setRenderTarget()も参照してください 。
プロパティのドキュメント
fillColor : QColor
このプロパティは、項目の背景色を指定します。
デフォルトでは、塗りつぶし色はQt::transparent に設定されています。
背景の塗りつぶしを無効にするには、塗りつぶし色として無効な色(例:QColor())を設定します。これによりパフォーマンスが向上する場合があり、paint() 関数が各フレームですべてのピクセルに描画を行う場合には、安全に実行できます。
アクセス関数:
| QColor | fillColor() const |
| void | setFillColor(const QColor &) |
通知シグナル:
| void | fillColorChanged() |
renderTarget : RenderTarget
このプロパティには、アイテムのレンダリングターゲットが格納されます。
このプロパティは、QPainter がどのレンダリングターゲットに描画するかを定義します。値としては、QQuickPaintedItem::Image 、QQuickPaintedItem::FramebufferObject 、またはQQuickPaintedItem::InvertedYFramebufferObject のいずれかを指定できます。
それぞれに特定の利点があり、一般的にはパフォーマンスと品質のトレードオフとなります。フレームバッファオブジェクトを使用すると、グラフィックメモリ内のテクスチャへの画像コンテンツのアップロードという負荷の高い処理を回避できますが、画像を使用すると高品質なアンチエイリアシングが可能になります。
警告: フレームバッファオブジェクトのサイズ変更は 負荷の高い操作です。アイテムのサイズ変更が頻繁に行われる場合は、QQuickPaintedItem::FramebufferObject レンダリングターゲットの使用を避けてください。
デフォルトでは、レンダリングターゲットは `QQuickPaintedItem::Image` です。
アクセス関数:
| QQuickPaintedItem::RenderTarget | renderTarget() const |
| void | setRenderTarget(QQuickPaintedItem::RenderTarget target) |
通知シグナル:
| void | renderTargetChanged() |
textureSize : QSize
テクスチャのサイズを指定します。
テクスチャのサイズを変更しても、paint() で使用される座標系には影響しません。代わりにスケーリング係数が適用されるため、描画は引き続き 0,0 からwidth()、height() の範囲内で行われます。
デフォルトでは、テクスチャのサイズは本アイテムと同じサイズになります。
注: アイテムが、デバイスピクセル比が 1 とは異なるウィンドウ上にある場合 、このスケール係数がテクスチャサイズに暗黙的に適用されます。
アクセス関数:
| QSize | textureSize() const |
| void | setTextureSize(const QSize &size) |
通知シグナル:
| void | textureSizeChanged() |
メンバ関数のドキュメント
[explicit] QQuickPaintedItem::QQuickPaintedItem(QQuickItem *parent = nullptr)
指定されたparent アイテムを使用して、QQuickPaintedItemを構築します。
[override virtual noexcept] QQuickPaintedItem::~QQuickPaintedItem()
QQuickPaintedItem を削除します。
bool QQuickPaintedItem::antialiasing() const
アンチエイリアス描画が有効になっている場合はtrueを返し、そうでない場合はfalseを返します。
デフォルトでは、アンチエイリアシングは有効になっていません。
setAntialiasing()も参照してください 。
[override virtual] bool QQuickPaintedItem::isTextureProvider() const
QQuickItem::isTextureProvider() const を再実装します。
[override virtual protected] void QQuickPaintedItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value)
QQuickItem::itemChange (QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value)を再実装します。
bool QQuickPaintedItem::mipmap() const
ミップマップが有効になっている場合は true を返し、そうでない場合は false を返します。
デフォルトでは、ミップマッピングは有効になっていません。
setMipmap()も参照してください 。
bool QQuickPaintedItem::opaquePainting() const
このアイテムが不透明である場合は true を返し、そうでない場合は false を返します。
デフォルトでは、描画されたアイテムは不透明ではありません。
setOpaquePainting()も参照してください 。
[pure virtual] void QQuickPaintedItem::paint(QPainter *painter)
この関数は、通常QMLシーングラフによって呼び出され、ローカル座標系でアイテムの内容を描画します。
基になるテクスチャのサイズは、textureSize が設定されている場合はその値によって定義され、設定されていない場合は、アイテムのサイズにウィンドウのデバイスピクセル比を乗じた値になります。
この関数は、アイテムが `fillColor` で塗りつぶされた後に呼び出されます。
QQuickPaintedItem のサブクラスでこの関数を再実装し、painter を使用して、アイテムの描画実装を提供してください。
注: QMLシーングラフは 2 つの別々のスレッドを使用します。メインスレッドはイベントの処理やアニメーションの更新などを担当し、2 つ目のスレッドはグラフィックリソースの更新の実際の発行やドローコールの記録を担当します。その結果、paint() はメインの GUI スレッドからではなく、GL 対応のレンダラスレッドから呼び出されます。 paint() が呼び出される瞬間、GUI スレッドはブロックされるため、この処理はスレッドセーフとなります。
警告: この関数内で QObject の作成、シグナルの発信、タイマーの開始などを行う場合は、これらがレンダリングスレッドに紐づくことになるため、細心の 注意を払う必要があります。
関連項目: width()、height()、およびtextureSize 。
QQuickPaintedItem::PerformanceHints QQuickPaintedItem::performanceHints() const
パフォーマンス・ヒントを返します。
デフォルトでは、パフォーマンスヒントは有効になっていません。
setPerformanceHint() およびsetPerformanceHints()も参照してください 。
[override virtual protected] void QQuickPaintedItem::releaseResources()
QQuickItem::releaseResources() を再実装します。
void QQuickPaintedItem::setAntialiasing(bool enable)
enable がtrueの場合、アンチエイリアス描画が有効になります。
デフォルトでは、アンチエイリアシングは有効になっていません。
antialiasing()も参照してください 。
void QQuickPaintedItem::setMipmap(bool enable)
enable が true の場合、関連付けられたテクスチャでミップマッピングが有効になります。
ミップマッピングは、アイテムが縮小された際のレンダリング速度を向上させ、エイリアシングのアーティファクトを低減します。
デフォルトでは、ミップマッピングは有効になっていません。
mipmap()も参照してください 。
void QQuickPaintedItem::setOpaquePainting(bool opaque)
opaque がtrueの場合、そのアイテムは不透明となります。そうでない場合は、半透明とみなされます。
不透明なアイテムはシーン内の他の要素とブレンドされません。アイテムの内容が不透明な場合は、レンダリングを高速化するためにこの値を true に設定してください。
デフォルトでは、ペイントされたアイテムは不透明ではありません。
opaquePainting()も参照してください 。
void QQuickPaintedItem::setPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true)
enabled がtrueの場合、指定されたパフォーマンスhint をアイテムに設定します。そうでない場合は、パフォーマンスヒントをクリアします。
デフォルトでは、パフォーマンスヒントは有効になっていません。
setPerformanceHints() およびperformanceHints()も参照してください 。
void QQuickPaintedItem::setPerformanceHints(QQuickPaintedItem::PerformanceHints hints)
パフォーマンス・ヒントを次のように設定します。hints
デフォルトでは、パフォーマンスヒントは有効になっていません。
setPerformanceHint() およびperformanceHints()も参照してください 。
[override virtual] QSGTextureProvider *QQuickPaintedItem::textureProvider() const
QQuickItem::textureProvider() const を再実装します。
void QQuickPaintedItem::update(const QRect &rect = QRect())
このアイテム内のrect で指定された領域の再描画をスケジュールします。この関数は、アイテムの外観やサイズが変更された場合など、アイテムの再描画が必要なときにいつでも呼び出すことができます。
この関数は即座に描画を実行するものではなく、次のフレームがレンダリングされる際に QML シーングラフによって処理される描画要求をスケジュールします。アイテムは、表示されている場合にのみ再描画されます。
paint()も参照してください 。
[override virtual protected] QSGNode *QQuickPaintedItem::updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data)
QQuickItem::updatePaintNode (QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *updatePaintNodeData)を再実装します。
© 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.