QQuickPaintedItem Class
La clase QQuickPaintedItem proporciona una forma de utilizar la API QPainter en el gráfico de escena QML. Más...
| Cabecera: | #include <QQuickPaintedItem> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick)target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| Hereda: | QQuickItem |
Tipos públicos
| enum | PerformanceHint { FastFBOResizing } |
| flags | PerformanceHints |
| enum | RenderTarget { Image, FramebufferObject, InvertedYFramebufferObject } |
Propiedades
- fillColor : QColor
- renderTarget : RenderTarget
- textureSize : QSize
Funciones públicas
| 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()) |
Funciones públicas reimplementadas
| virtual bool | isTextureProvider() const override |
| virtual QSGTextureProvider * | textureProvider() const override |
Señales
| void | fillColorChanged() |
| void | renderTargetChanged() |
| void | textureSizeChanged() |
Funciones protegidas reimplementadas
| virtual void | itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value) override |
| virtual void | releaseResources() override |
| virtual QSGNode * | updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data) override |
Descripción detallada
QQuickPaintedItem permite utilizar la API QPainter con el gráfico de escena QML. Establece un rectángulo texturizado en el Scene Graph y utiliza QPainter para pintar sobre la textura. El objetivo de renderizado en Qt 6 es siempre un QImage. Cuando el objetivo de renderizado es un QImage, QPainter renderiza primero en la imagen y luego el contenido se carga en la textura. Llama a update() para activar un repintado.
Para habilitar QPainter para hacer renderizado anti-aliasing, use setAntialiasing().
Para escribir tu propio item pintado, primero debes crear una subclase de QQuickPaintedItem, y luego comenzar implementando su única función pública virtual pura: paint(), que implementa la pintura real. La pintura se realizará dentro del rectángulo que va de 0,0 a width(),height().
Nota: Es importante entender las implicaciones de rendimiento que estos elementos pueden tener. Véase QQuickPaintedItem::RenderTarget y QQuickPaintedItem::renderTarget.
Véase también Gráfico de escena - Elemento pintado y Escribir extensiones QML con C++.
Documentación de tipos de miembros
enum QQuickPaintedItem::PerformanceHint
flags QQuickPaintedItem::PerformanceHints
Este enum describe los indicadores que puedes activar para mejorar el rendimiento de renderizado en QQuickPaintedItem. Por defecto, ninguno de estos indicadores está activado.
| Constante | Valor | Descripción |
|---|---|---|
QQuickPaintedItem::FastFBOResizing | 0x1 | A partir de Qt 6.0, este valor se ignora. |
El tipo PerformanceHints es un typedef para QFlags<PerformanceHint>. Almacena una combinación OR de valores PerformanceHint.
enum QQuickPaintedItem::RenderTarget
Este enum describe los objetivos de renderizado de QQuickPaintedItem. El objetivo de renderizado es la superficie sobre la que pinta QPainter antes de que el elemento se renderice en pantalla.
| Constante | Valor | Descripción |
|---|---|---|
QQuickPaintedItem::Image | 0 | Por defecto; QPainter pinta en un QImage utilizando el motor de pintura raster. El contenido de la imagen necesita ser cargado a la memoria gráfica después, esta operación puede ser potencialmente lenta si el ítem es grande. Este objetivo de renderizado permite un anti-aliasing de alta calidad y un redimensionamiento rápido del elemento. |
QQuickPaintedItem::FramebufferObject | 1 | A partir de Qt 6.9, este valor habilitará el pintado acelerado por hardware siempre que la API de renderizado utilizada sea OpenGL, de lo contrario será ignorado. Para las versiones Qt 6.0 a Qt 6.8, será ignorado en todas las APIs de renderizado. Esto normalmente dará un mejor rendimiento de renderizado, pero a expensas de la calidad del antialiasing. |
QQuickPaintedItem::InvertedYFramebufferObject | 2 | Igual que FramebufferObject, pero con el renderizado invertido alrededor del eje X. |
Véase también setRenderTarget().
Documentación de propiedades
fillColor : QColor
Esta propiedad contiene el color de relleno de fondo del elemento.
Por defecto, el color de relleno es Qt::transparent.
Establezca el color de relleno a un color no válido (por ejemplo, QColor()) para desactivar el relleno de fondo. Esto puede mejorar el rendimiento, y es seguro hacerlo si la función paint() dibuja en todos los píxeles de cada fotograma.
Funciones de acceso:
| QColor | fillColor() const |
| void | setFillColor(const QColor &) |
Señal de notificador:
| void | fillColorChanged() |
renderTarget : RenderTarget
Esta propiedad contiene el objetivo de renderizado del elemento.
Esta propiedad define el destino de renderizado de QPainter, que puede ser QQuickPaintedItem::Image, QQuickPaintedItem::FramebufferObject o QQuickPaintedItem::InvertedYFramebufferObject.
Cada uno tiene ciertas ventajas, normalmente de rendimiento frente a calidad. Usar un objeto framebuffer evita una costosa carga del contenido de la imagen a la textura en la memoria gráfica, mientras que usar una imagen permite un anti-aliasing de alta calidad.
Advertencia: Redimensionar un objeto framebuffer es una operación costosa, evite usar el objetivo de renderizado QQuickPaintedItem::FramebufferObject si el elemento se redimensiona a menudo.
Por defecto, el objetivo de renderizado es QQuickPaintedItem::Image.
Funciones de acceso:
| QQuickPaintedItem::RenderTarget | renderTarget() const |
| void | setRenderTarget(QQuickPaintedItem::RenderTarget target) |
Señal notificadora:
| void | renderTargetChanged() |
textureSize : QSize
Define el tamaño de la textura.
Cambiar el tamaño de la textura no afecta al sistema de coordenadas utilizado en paint(). En su lugar, se aplica un factor de escala para que la pintura siga ocurriendo dentro de 0,0 a width(),height().
Por defecto, el tamaño de la textura tendrá el mismo tamaño que este ítem.
Nota: Si el elemento está en una ventana con un ratio de píxeles del dispositivo diferente de 1, este factor de escala se aplicará implícitamente al tamaño de la textura.
Funciones de acceso:
| QSize | textureSize() const |
| void | setTextureSize(const QSize &size) |
Señal del notificador:
| void | textureSizeChanged() |
Documentación de funciones miembro
[explicit] QQuickPaintedItem::QQuickPaintedItem(QQuickItem *parent = nullptr)
Construye un QQuickPaintedItem con el elemento parent dado.
[override virtual noexcept] QQuickPaintedItem::~QQuickPaintedItem()
Destruye el QQuickPaintedItem.
bool QQuickPaintedItem::antialiasing() const
Devuelve true si el pintado con antialiasing está activado; en caso contrario, devuelve false.
Por defecto, el antialiasing no está activado.
Véase también setAntialiasing().
[override virtual] bool QQuickPaintedItem::isTextureProvider() const
Reimplementa: QQuickItem::isTextureProvider() const.
[override virtual protected] void QQuickPaintedItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value)
Reimplementa: QQuickItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value).
bool QQuickPaintedItem::mipmap() const
Devuelve true si los mipmaps están habilitados; en caso contrario, devuelve false.
Por defecto, los mipmaps no están activados.
Véase también setMipmap().
bool QQuickPaintedItem::opaquePainting() const
Devuelve true si este elemento es opaco; en caso contrario, devuelve false.
Por defecto, los elementos pintados no son opacos.
Véase también setOpaquePainting().
[pure virtual] void QQuickPaintedItem::paint(QPainter *painter)
Esta función, que suele ser llamada por el gráfico de escena QML, pinta el contenido de un elemento en coordenadas locales.
La textura subyacente tendrá un tamaño definido por textureSize cuando se establezca, o el tamaño del elemento, multiplicado por la proporción de píxeles del dispositivo de la ventana.
La función se ejecuta una vez que el elemento se ha rellenado con fillColor.
Reimplemente esta función en una subclase de QQuickPaintedItem para proporcionar la implementación de pintura del elemento, utilizando painter.
Nota: El Gráfico de Escena QML utiliza dos hilos separados, el hilo principal hace cosas como procesar eventos o actualizar animaciones mientras que un segundo hilo hace la emisión real de actualizaciones de recursos gráficos y la grabación de llamadas a dibujar. Como consecuencia, paint() no es llamada desde el hilo principal de la GUI sino desde el hilo del renderizador habilitado para GL. En el momento en que se llama a paint(), el hilo de la GUI se bloquea y, por lo tanto, es seguro para los hilos.
Advertencia: Se debe tener extremo cuidado al crear QObjects, emitir señales, iniciar temporizadores y similares dentro de esta función ya que estos tendrán afinidad con el hilo de renderizado.
Ver también width(), height(), y textureSize.
QQuickPaintedItem::PerformanceHints QQuickPaintedItem::performanceHints() const
Devuelve las sugerencias de rendimiento.
Por defecto, no se activa ninguna sugerencia de rendimiento.
Véase también setPerformanceHint() y setPerformanceHints().
[override virtual protected] void QQuickPaintedItem::releaseResources()
Reimplementa: QQuickItem::releaseResources().
void QQuickPaintedItem::setAntialiasing(bool enable)
Si enable es verdadero, se activa la pintura antialiasing.
Por defecto, el antialiasing no está activado.
Véase también antialiasing().
void QQuickPaintedItem::setMipmap(bool enable)
Si enable es verdadero, se activa el mipmapping en la textura asociada.
El mipmapping aumenta la velocidad de renderizado y reduce los artefactos de aliasing cuando se reduce la escala del elemento.
Por defecto, el mipmapping no está activado.
Véase también mipmap().
void QQuickPaintedItem::setOpaquePainting(bool opaque)
Si opaque es verdadero, el elemento es opaco; en caso contrario, se considera translúcido.
Los elementos opacos no se mezclan con el resto de la escena, debes establecerlo a true si el contenido del elemento es opaco para acelerar el renderizado.
Por defecto, los elementos pintados no son opacos.
Véase también opaquePainting().
void QQuickPaintedItem::setPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true)
Establece el rendimiento dado hint en el elemento si enabled es verdadero; de lo contrario, borra la sugerencia de rendimiento.
Por defecto, no se activa ninguna sugerencia de rendimiento/.
Véase también setPerformanceHints() y performanceHints().
void QQuickPaintedItem::setPerformanceHints(QQuickPaintedItem::PerformanceHints hints)
Establece las sugerencias de rendimiento en hints
Por defecto, no se activa ninguna sugerencia de rendimiento/
Véase también setPerformanceHint() y performanceHints().
[override virtual] QSGTextureProvider *QQuickPaintedItem::textureProvider() const
Reimplementa: QQuickItem::textureProvider() const.
void QQuickPaintedItem::update(const QRect &rect = QRect())
Programa un redibujado del área cubierta por rect en este elemento. Puedes llamar a esta función siempre que tu elemento necesite ser redibujado, por ejemplo si cambia de apariencia o tamaño.
Esta función no provoca un pintado inmediato, sino que programa una solicitud de pintado que es procesada por el gráfico de escena QML cuando se renderiza el siguiente fotograma. El elemento sólo se redibujará si es visible.
Véase también paint().
[override virtual protected] QSGNode *QQuickPaintedItem::updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data)
Reimplementa: 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.
