QQuickPaintedItem Class
La clase `QQuickPaintedItem` permite utilizar la API « QPainter » en el grafo de escena de QML. Más información...
| Encabezado: | #include <QQuickPaintedItem> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| Heredado de: | 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 grafo de escena de QML. Configura un rectángulo con textura en el grafo de escena y utiliza un objeto « QPainter » para pintar sobre la textura. El destino de renderizado en Qt 6 es siempre un « QImage ». Cuando el destino de renderizado es un « QImage », « QPainter » primero renderiza en la imagen y, a continuación, el contenido se carga en la textura. Llama a ` update()` para activar un redibujado.
Para habilitar el renderizado con suavizado en QPainter, utiliza setAntialiasing().
Para crear tu propio elemento pintado, primero debes crear una subclase de `QQuickPaintedItem` y, a continuación, empezar por implementar su única función pública virtual pura: ` paint()`, que se encarga de la pintura propiamente dicha. La pintura se realizará dentro del rectángulo que abarca desde 0,0 hasta ` width()`, `height()`.
Nota: Es importante comprender las implicaciones en el rendimiento que pueden acarrear estos elementos. Véase QQuickPaintedItem::RenderTarget y QQuickPaintedItem::renderTarget.
Véase también «Grafo de escena: elemento pintado» y «Escribir extensiones QML con C++».
Documentación sobre tipos de miembro
enum QQuickPaintedItem::PerformanceHint
flags QQuickPaintedItem::PerformanceHints
Esta enumeración describe los parámetros que se pueden activar para mejorar el rendimiento de la representación en QQuickPaintedItem. De forma predeterminada, ninguno de estos parámetros está activado.
| Constante | Valor | Descripción |
|---|---|---|
QQuickPaintedItem::FastFBOResizing | 0x1 | A partir de Qt 6.0, este valor se ignora. |
El tipo `PerformanceHints` es una definición de tipo (`typedef`) para ` QFlags<PerformanceHint>`. Almacena una combinación OR de valores de `PerformanceHint`.
enum QQuickPaintedItem::RenderTarget
Esta enumeración describe los objetivos de renderizado de QQuickPaintedItem. El objetivo de renderizado es la superficie sobre la que QPainter realiza el pintado antes de que el elemento se muestre en pantalla.
| Constante | Valor | Descripción |
|---|---|---|
QQuickPaintedItem::Image | 0 | El valor por defecto; QPainter pinta en una « QImage » utilizando el motor de pintura rasterizada. El contenido de la imagen debe cargarse posteriormente en la memoria gráfica; esta operación puede resultar lenta si el elemento es grande. Este destino de renderizado permite un suavizado de alta calidad y un rápido cambio de tamaño de los elementos. |
QQuickPaintedItem::FramebufferObject | 1 | A partir de Qt 6.9, este valor habilitará el dibujo acelerado por hardware siempre que la API de renderizado utilizada sea OpenGL; de lo contrario, se ignorará. En las versiones de Qt 6.0 a Qt 6.8, se ignorará en todas las API de renderizado. Esto suele proporcionar un mejor rendimiento de renderizado, pero a costa de la calidad del suavizado. |
QQuickPaintedItem::InvertedYFramebufferObject | 2 | Igual que FramebufferObject, pero con el renderizado invertido alrededor del eje X. |
Véase también setRenderTarget().
Documentación de la propiedad
fillColor : QColor
Esta propiedad determina el color de relleno del fondo del elemento.
De forma predeterminada, el color de relleno está establecido en Qt::transparent.
Establece el color de relleno en 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 destino de renderizado del elemento.
Esta propiedad define en qué destino de renderizado se renderiza el objeto de búfer de fotogramas ( QPainter ); puede ser « QQuickPaintedItem::Image », « QQuickPaintedItem::FramebufferObject » o « QQuickPaintedItem::InvertedYFramebufferObject ».
Cada uno tiene ciertas ventajas, normalmente en términos de rendimiento frente a calidad. El uso de un objeto framebuffer evita la costosa carga del contenido de la imagen a la textura en la memoria gráfica, mientras que el uso de una imagen permite un suavizado de alta calidad.
Advertencia: Cambiar el tamaño de un objeto de framebuffer es una operación costosa; evita utilizar el destino de renderizado QQuickPaintedItem::FramebufferObject si el elemento cambia de tamaño con frecuencia.
Por defecto, el destino de renderizado es QQuickPaintedItem::Image.
Funciones de acceso:
| QQuickPaintedItem::RenderTarget | renderTarget() const |
| void | setRenderTarget(QQuickPaintedItem::RenderTarget target) |
Señal de notificador:
| 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, por lo que el dibujo debería seguir realizándose dentro del rango de 0,0 a width(),height().
Por defecto, el tamaño de la textura será el mismo que el de este elemento.
Nota: Si el elemento se encuentra en una ventana con una relación de píxeles del dispositivo distinta 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 de notificación:
| void | textureSizeChanged() |
Documentación de las funciones de miembro
[explicit] QQuickPaintedItem::QQuickPaintedItem(QQuickItem *parent = nullptr)
Crea un objeto `QQuickPaintedItem` con el elemento ` parent ` indicado.
[override virtual noexcept] QQuickPaintedItem::~QQuickPaintedItem()
Destruye la « QQuickPaintedItem ».
bool QQuickPaintedItem::antialiasing() const
Devuelve «true» si está activado el suavizado; en caso contrario, devuelve «false».
Por defecto, el suavizado 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, el mipmapping no está activado.
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 invocada por el grafo de escena de QML, dibuja el contenido de un elemento en coordenadas locales.
La textura subyacente tendrá un tamaño definido por ` textureSize ` si se ha establecido, o bien el tamaño del elemento multiplicado por la relación de píxeles del dispositivo de la ventana.
La función se invoca después de que el elemento se haya rellenado con el ` fillColor`.
Reimplementa esta función en una subclase de ` QQuickPaintedItem ` para proporcionar la implementación de dibujo del elemento, utilizando ` painter`.
Nota: El grafo de escena de QML utiliza dos subprocesos independientes: el subproceso principal se encarga de tareas como el procesamiento de eventos o la actualización de animaciones, mientras que un segundo subproceso se ocupa de la emisión efectiva de actualizaciones de recursos gráficos y del registro de llamadas de dibujo. Como consecuencia, paint() no se invoca desde el subproceso principal de la interfaz gráfica de usuario, sino desde el subproceso del renderizador habilitado para GL. En el momento en que se invoca a `paint()`, el hilo de la interfaz gráfica de usuario queda bloqueado, por lo que esta operación es segura entre hilos.
Advertencia: Se debe tenermucho cuidado al crear QObjects, emitir señales, iniciar temporizadores y acciones similares dentro de esta función, ya que estas tendrán afinidad con el hilo de renderizado.
Véase también width(), height() y textureSize.
QQuickPaintedItem::PerformanceHints QQuickPaintedItem::performanceHints() const
Devuelve las sugerencias de rendimiento.
Por defecto, no hay ninguna sugerencia de rendimiento activada.
Véase también setPerformanceHint() y setPerformanceHints().
[override virtual protected] void QQuickPaintedItem::releaseResources()
Reimplementa: QQuickItem::releaseResources().
void QQuickPaintedItem::setAntialiasing(bool enable)
Si « enable » es «true», se habilita el sombreado con suavizado.
Por defecto, el suavizado no está activado.
Véase también antialiasing().
void QQuickPaintedItem::setMipmap(bool enable)
Si enable es verdadero, el mipmapping está habilitado 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á habilitado.
Véase también mipmap().
void QQuickPaintedItem::setOpaquePainting(bool opaque)
Si « opaque » es «true», el elemento es opaco; en caso contrario, se considera translúcido.
Los elementos opacos no se mezclan con el resto de la escena; debes establecer este valor en «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 la indicación de rendimiento hint en el elemento si enabled es verdadero; en caso contrario, borra la indicación de rendimiento.
Por defecto, no hay ninguna sugerencia de rendimiento activada.
Véase también setPerformanceHints() y performanceHints().
void QQuickPaintedItem::setPerformanceHints(QQuickPaintedItem::PerformanceHints hints)
Establece las sugerencias de rendimiento en hints
Por defecto, no hay ninguna sugerencia de rendimiento activada/
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 sea necesario redibujar el elemento, por ejemplo, si cambia de aspecto o de tamaño.
Esta función no provoca un redibujado inmediato, sino que programa una solicitud de redibujado que el grafo de escena de QML procesará cuando se renderice el siguiente fotograma. El elemento solo se redibujará si está 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.