En esta página

QSGTexture Class

La clase QSGTexture es la clase base de las texturas que se utilizan en el grafo de escena. Más información...

Cabecera: #include <QSGTexture>
CMake: find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick
Heredado de: QObject
Heredado por:

QSGDynamicTexture

Tipos públicos

enum AnisotropyLevel { AnisotropyNone, Anisotropy2x, Anisotropy4x, Anisotropy8x, Anisotropy16x }
enum Filtering { None, Nearest, Linear }
enum WrapMode { Repeat, ClampToEdge, MirroredRepeat }

Funciones públicas

QSGTexture()
virtual ~QSGTexture() override
QSGTexture::AnisotropyLevel anisotropyLevel() const
(since 6.0) virtual void commitTextureOperations(QRhi *rhi, QRhiResourceUpdateBatch *resourceUpdates)
virtual qint64 comparisonKey() const = 0
QRectF convertToNormalizedSourceRect(const QRectF &rect) const
QSGTexture::Filtering filtering() const
virtual bool hasAlphaChannel() const = 0
virtual bool hasMipmaps() const = 0
QSGTexture::WrapMode horizontalWrapMode() const
virtual bool isAtlasTexture() const
QSGTexture::Filtering mipmapFiltering() const
QNativeInterface *nativeInterface() const
virtual QRectF normalizedTextureSubRect() const
virtual QSGTexture *removedFromAtlas(QRhiResourceUpdateBatch *resourceUpdates = nullptr) const
(since 6.0) virtual QRhiTexture *rhiTexture() const
void setAnisotropyLevel(QSGTexture::AnisotropyLevel level)
void setFiltering(QSGTexture::Filtering filter)
void setHorizontalWrapMode(QSGTexture::WrapMode hwrap)
void setMipmapFiltering(QSGTexture::Filtering filter)
void setVerticalWrapMode(QSGTexture::WrapMode vwrap)
virtual QSize textureSize() const = 0
QSGTexture::WrapMode verticalWrapMode() const

Descripción detallada

Los usuarios pueden implementar libremente sus propias clases de texturas para admitir texturas de entrada arbitrarias, como fotogramas de vídeo YUV o máscaras alfa de 8 bits. El grafo de escena proporciona una implementación predeterminada para texturas RGBA. La implementación predeterminada no se instancia directamente, sino que se construye mediante funciones de fábrica, como QQuickWindow::createTextureFromImage().

Con la implementación predeterminada, cada QSGTexture está respaldada por un QRhiTexture, que a su vez contiene un objeto de textura nativo, como una textura de OpenGL o una imagen de Vulkan.

El tamaño en píxeles viene dado por textureSize(). hasAlphaChannel() indica si la textura contiene valores de opacidad y hasMipmaps() indica si la textura contiene niveles de mipmap.

Materials Las funciones que trabajan con texturas reimplementan ` updateSampledImage()` para proporcionar la lógica que decide qué textura nativa subyacente de `QSGTexture` debe exponerse en un punto de enlace de recursos de shader determinado.

QSGTexture no separa los objetos de imagen (textura) y de muestreador. Los parámetros de filtrado y envoltura se pueden especificar con setMipmapFiltering(), setFiltering(), setHorizontalWrapMode() y setVerticalWrapMode(). El grafo de escena y la abstracción gráfica de Qt se encargan de crear objetos de muestreador independientes, cuando sea aplicable.

Atlas de texturas

Algunos backends del grafo de escena utilizan atlas de texturas, que agrupan varias texturas pequeñas en una sola textura grande. Si este es el caso, la función isAtlasTexture() devolverá «true». Los atlas se utilizan para ayudar al algoritmo de renderizado a realizar una mejor clasificación, lo que aumenta el rendimiento. Los atlas también son esenciales para el procesamiento por lotes (fusionar geometría para reducir el número de llamadas de dibujo), ya que dos instancias del mismo material que utilicen dos QSGTextures diferentes no se pueden agrupar por lotes, mientras que si ambas QSGTextures hacen referencia al mismo atlas, sí se puede realizar el procesamiento por lotes, siempre que los materiales sean compatibles en los demás aspectos.

La ubicación de la textura dentro del atlas se obtiene mediante la función normalizedTextureSubRect().

Si la textura se utiliza de tal forma que no es preferible el uso de un atlas, se puede utilizar la función removedFromAtlas() para extraer una copia sin atlas.

Nota: Todas las clases con el prefijo QSG deben utilizarse exclusivamente en el hilo de renderizado del grafo de escena. Consulte «Grafo de escena y renderizado» para obtener más información.

Documentación sobre los tipos de miembros

enum QSGTexture::AnisotropyLevel

Especifica el nivel de filtrado anisotrópico que se utilizará cuando la textura no esté alineada con la pantalla.

ConstanteValorDescripción
QSGTexture::AnisotropyNone0Sin filtrado anisotrópico.
QSGTexture::Anisotropy2x1Filtrado anisotrópico 2x.
QSGTexture::Anisotropy4x2Filtrado anisotrópico 4x.
QSGTexture::Anisotropy8x3Filtrado anisotrópico de 8x.
QSGTexture::Anisotropy16x4Filtrado anisotrópico de 16x.

enum QSGTexture::Filtering

Especifica cómo debe filtrarse el muestreo de los texeles cuando las coordenadas de textura no están alineadas con los píxeles.

ConstanteValorDescripción
QSGTexture::None0No debe producirse ningún filtrado. Este valor solo se utiliza junto con ` setMipmapFiltering()`.
QSGTexture::Nearest1El muestreo devuelve el texel más cercano.
QSGTexture::Linear2El muestreo devuelve una interpolación lineal de los texeles vecinos.

enum QSGTexture::WrapMode

Especifica cómo debe tratar el muestreador las coordenadas de textura.

ConstanteValorDescripción
QSGTexture::Repeat0Solo se utiliza la parte fraccionaria de la coordenada de textura, lo que hace que los valores superiores a 1 e inferiores a 0 se repitan.
QSGTexture::ClampToEdge1Los valores superiores a 1 se limitan a 1 y los inferiores a 0 se limitan a 0.
QSGTexture::MirroredRepeat2Cuando la coordenada de textura es par, solo se utiliza la parte fraccionaria. Cuando es impar, la coordenada de textura se establece en 1 - fractional part. Este valor se ha introducido en Qt 5.10.

Documentación de funciones miembro

QSGTexture::QSGTexture()

Crea la clase base QSGTexture.

[override virtual noexcept] QSGTexture::~QSGTexture()

Destruye el « QSGTexture ».

QSGTexture::AnisotropyLevel QSGTexture::anisotropyLevel() const

Devuelve el nivel de anisotropía utilizado para filtrar esta textura.

Véase también setAnisotropyLevel().

[virtual, since 6.0] void QSGTexture::commitTextureOperations(QRhi *rhi, QRhiResourceUpdateBatch *resourceUpdates)

Llama a esta función para poner en cola las operaciones de subida de imágenes a resourceUpdates, en caso de que haya alguna pendiente. Cuando no hay datos nuevos (por ejemplo, porque no se ha llamado a setImage() desde la última llamada a esta función), la función no realiza ninguna acción.

Se espera que los materiales que utilicen texturas de rhi llamen a esta función desde su implementación de updateSampledImage(), normalmente sin ninguna condición, pasando state.rhi() y state.resourceUpdateBatch() desde QSGMaterialShader::RenderState.

Advertencia: Esta función solo se puede llamar desde el hilo de renderizado.

Esta función se introdujo en Qt 6.0.

[pure virtual] qint64 QSGTexture::comparisonKey() const

Devuelve una clave adecuada para comparar texturas. Se utiliza habitualmente en implementaciones de ` QSGMaterial::compare()`.

La mera comparación de punteros ` QSGTexture ` no siempre es suficiente, ya que dos instancias de ` QSGTexture ` que hacen referencia al mismo objeto de textura nativo subyacente también deben considerarse iguales. De ahí la necesidad de esta función.

No se espera que las implementaciones de esta función creen recursos gráficos (objetos de textura nativos) en caso de que aún no existan, ni deben hacerlo.

Un ` QSGTexture ` que no tenga un objeto de textura nativo subyacente no suele ser igual a ningún otro ` QSGTexture`, por lo que el valor de retorno debe diseñarse en consecuencia. Hay excepciones a esto, en particular cuando se utiliza el atlas (donde varias texturas comparten la misma textura de atlas en segundo plano); en ese caso, corresponde a las implementaciones de las subclases gestionarlo como sea adecuado.

Advertencia: Esta función solo se puede invocar desde el hilo de renderizado.

QRectF QSGTexture::convertToNormalizedSourceRect(const QRectF &rect) const

Devuelve rect convertido a coordenadas normalizadas.

Véase también normalizedTextureSubRect().

QSGTexture::Filtering QSGTexture::filtering() const

Devuelve el modo de muestreo que se utilizará para esta textura.

Véase también setFiltering().

[pure virtual] bool QSGTexture::hasAlphaChannel() const

Devuelve «true» si los datos de la textura contienen un canal alfa.

[pure virtual] bool QSGTexture::hasMipmaps() const

Devuelve «true» si los datos de la textura contienen niveles de mipmap.

QSGTexture::WrapMode QSGTexture::horizontalWrapMode() const

Devuelve el modo de ajuste horizontal que se utilizará para esta textura.

Véase también setHorizontalWrapMode().

[virtual] bool QSGTexture::isAtlasTexture() const

Indica si esta textura forma parte de un atlas o no.

La implementación por defecto devuelve «false».

QSGTexture::Filtering QSGTexture::mipmapFiltering() const

Indica si se debe utilizar mipmapping al muestrear esta textura.

Véase también setMipmapFiltering().

template <typename QNativeInterface> QNativeInterface *QSGTexture::nativeInterface() const

Devuelve una interfaz nativa del tipo indicado para la textura.

Esta función proporciona acceso a la funcionalidad específica de la plataforma de QSGTexture, tal y como se declara en el espacio de nombres QNativeInterface:

QNativeInterface::QSGD3D11Texture

Proporciona acceso a los objetos de textura de Direct3D 11 y permite su adopción

QNativeInterface::QSGD3D12Texture

Proporciona acceso a los objetos de textura de Direct3D 12 y permite su adopción

QNativeInterface::QSGMetalTexture

Proporciona acceso a los objetos de textura de Metal y permite su adopción

QNativeInterface::QSGOpenGLTexture

Proporciona acceso a los objetos de textura de OpenGL y permite su adopción

QNativeInterface::QSGVulkanTexture

Proporciona acceso a los objetos de imagen de Vulkan y permite su adopción

Esto permite acceder al objeto de textura nativo subyacente, como el identificador de textura « GLuint » con OpenGL o el identificador « VkImage » con Vulkan.

Si la interfaz solicitada no está disponible, se devuelve un objeto ` nullptr `.

[virtual] QRectF QSGTexture::normalizedTextureSubRect() const

Devuelve el rectángulo dentro de textureSize() que representa esta textura en coordenadas normalizadas.

La implementación por defecto devuelve un rectángulo en la posición (0, 0) con un ancho y una altura de 1.

[virtual] QSGTexture *QSGTexture::removedFromAtlas(QRhiResourceUpdateBatch *resourceUpdates = nullptr) const

Esta función devuelve una copia de la textura actual, que se elimina de su atlas.

La textura actual permanece inalterada, por lo que no es necesario actualizar las coordenadas de textura.

Extraer una textura de un atlas resulta útil principalmente cuando se pasa a un sombreador que opera con las coordenadas de textura 0-1 en lugar de con la subrecta de textura dentro del atlas.

Si la textura no forma parte de un atlas de texturas, esta función devuelve 0.

Se recomienda que las implementaciones de esta función devuelvan la misma instancia para múltiples llamadas, a fin de limitar el uso de memoria.

resourceUpdates es un lote de actualización de recursos opcional, en el que se ponen en cola las operaciones de textura, si las hay. Los materiales pueden recuperar una instancia de QSGMaterialShader::RenderState. Cuando es nulo, la implementación de removedFromAtlas() crea su propio lote y lo envía de inmediato. Sin embargo, cuando se especifica una instancia válida, esta función no enviará el lote de actualización.

Advertencia: Esta función solo se puede llamar desde el hilo de renderizado.

[virtual, since 6.0] QRhiTexture *QSGTexture::rhiTexture() const

Devuelve el objeto ` QRhiTexture ` correspondiente a este ` QSGTexture `, o `null` si no existe ninguno (ya sea porque aún no se ha creado internamente una textura válida, o porque el concepto no es aplicable al backend del grafo de escena que se está utilizando).

No se espera que esta función cree un nuevo ` QRhiTexture ` en caso de que no haya ninguno. En ese caso, debería devolver `null`. Se espera que el renderizador utilice una textura ficticia transparente en lugar de una textura nula.

Advertencia: Esta función solo se puede invocar desde el hilo de renderizado.

Esta función se introdujo en Qt 6.0.

void QSGTexture::setAnisotropyLevel(QSGTexture::AnisotropyLevel level)

Establece el nivel de filtrado anisotrópico en level. El valor por defecto es QSGTexture::AnisotropyNone, lo que significa que no hay filtrado anisotrópico activado.

Nota: La solicitud puede ignorarse en función de la API gráfica que se utilice. No hay garantía de que el filtrado anisotrópico sea compatible en tiempo de ejecución.

Véase también anisotropyLevel().

void QSGTexture::setFiltering(QSGTexture::Filtering filter)

Establece el modo de muestreo en « filter ».

Véase también filtering().

void QSGTexture::setHorizontalWrapMode(QSGTexture::WrapMode hwrap)

Establece el modo de ajuste horizontal en hwrap

Véase también horizontalWrapMode().

void QSGTexture::setMipmapFiltering(QSGTexture::Filtering filter)

Establece el modo de muestreo de mipmaps en « filter ».

Configurar el filtrado de mipmaps no tiene ningún efecto si la textura no tiene mipmaps.

Véase también ` mipmapFiltering()` y ` hasMipmaps()`.

void QSGTexture::setVerticalWrapMode(QSGTexture::WrapMode vwrap)

Establece el modo de ajuste vertical en vwrap

Véase también verticalWrapMode().

[pure virtual] QSize QSGTexture::textureSize() const

Devuelve el tamaño de la textura en píxeles.

QSGTexture::WrapMode QSGTexture::verticalWrapMode() const

Devuelve el modo de ajuste vertical que se utilizará para esta textura.

Véase también setVerticalWrapMode().

© 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.