En esta página

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

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

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.

ConstanteValorDescripción
QQuickPaintedItem::FastFBOResizing0x1A 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.

ConstanteValorDescripción
QQuickPaintedItem::Image0El 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::FramebufferObject1A 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::InvertedYFramebufferObject2Igual 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.