QSGTexture Class
La clase QSGTexture es la clase base para las texturas utilizadas en el gráfico de escena. Más...
| Cabecera: | #include <QSGTexture> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick)target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| Hereda: | QObject |
| Heredado por: |
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 soportar 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 por defecto para las texturas RGBA, que no se instancian directamente, sino que se construyen a través de funciones de fábrica, como QQuickWindow::createTextureFromImage().
Con la implementación por defecto, cada QSGTexture está respaldada por un QRhiTexture, que a su vez contiene un objeto de textura nativo, como una textura OpenGL o una imagen Vulkan.
El tamaño en píxeles viene dado por textureSize(). hasAlphaChannel() informa si la textura contiene valores de opacidad y hasMipmaps() informa si la textura contiene niveles mipmap.
Materials que trabajan con texturas reimplementan updateSampledImage() para proporcionar la lógica que decide qué textura nativa subyacente de QSGTexture debe ser expuesta en un punto de enlace de recursos de shader dado.
QSGTexture no separa los objetos imagen (textura) y muestreador. Los parámetros para filtrar y envolver se pueden especificar con setMipmapFiltering(), setFiltering(), setHorizontalWrapMode() y setVerticalWrapMode(). El gráfico de escena y la abstracción gráfica de Qt se encargan de crear objetos sampler separados, cuando procede.
Atlas de texturas
Algunos backends de gráficos de escena utilizan atlas de texturas, agrupando múltiples texturas pequeñas en una 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 ordenación, lo que aumenta el rendimiento. Los atlas también son esenciales para la agrupación (fusión de geometría para reducir el número de llamadas a dibujo), porque dos instancias del mismo material utilizando dos QSGTextures diferentes no son agrupables, mientras que si ambos QSGTextures se refieren al mismo atlas, la agrupación puede ocurrir, asumiendo que los materiales son compatibles.
La ubicación de la textura dentro del atlas se da con la función normalizedTextureSubRect().
Si la textura se utiliza de tal manera que el atlas no es preferible, se puede utilizar la función removedFromAtlas() para extraer una copia no atlasada.
Nota: Todas las clases con el prefijo QSG deben utilizarse únicamente en el hilo de renderizado del gráfico de escena. Véase Gráfico de escena y renderizado para más información.
Documentación de 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.
| Constante | Valor | Descripción |
|---|---|---|
QSGTexture::AnisotropyNone | 0 | Sin filtro anisotrópico. |
QSGTexture::Anisotropy2x | 1 | Filtrado anisotrópico 2x. |
QSGTexture::Anisotropy4x | 2 | 4x filtro anisotrópico. |
QSGTexture::Anisotropy8x | 3 | 8x filtro anisotrópico. |
QSGTexture::Anisotropy16x | 4 | 16x filtro anisotrópico. |
enum QSGTexture::Filtering
Especifica cómo debe filtrarse el muestreo de los texels cuando las coordenadas de la textura no están alineadas con el píxel.
| Constante | Valor | Descripción |
|---|---|---|
QSGTexture::None | 0 | No debe producirse filtrado. Este valor sólo se utiliza junto con setMipmapFiltering(). |
QSGTexture::Nearest | 1 | Sampling devuelve el texel más cercano. |
QSGTexture::Linear | 2 | Sampling devuelve una interpolación lineal de los texels vecinos. |
enum QSGTexture::WrapMode
Especifica cómo debe tratar el muestreador las coordenadas de textura.
| Constante | Valor | Descripción |
|---|---|---|
QSGTexture::Repeat | 0 | Sólo se usa la parte fraccionaria de la coordenada de textura, haciendo que los valores por encima de 1 y por debajo de 0 se repitan. |
QSGTexture::ClampToEdge | 1 | Los valores por encima de 1 se fijan en 1 y los valores por debajo de 0 se fijan en 0. |
QSGTexture::MirroredRepeat | 2 | Cuando la coordenada de textura es par, sólo se utiliza la parte fraccionaria. Cuando es impar, la coordenada de la textura se establece en 1 - fractional part. Este valor se ha introducido en Qt 5.10. |
Documentación de las funciones miembro
QSGTexture::QSGTexture()
Construye la clase base QSGTexture.
[override virtual noexcept] QSGTexture::~QSGTexture()
Destruye el QSGTexture.
QSGTexture::AnisotropyLevel QSGTexture::anisotropyLevel() const
Devuelve el nivel de anisotropía en uso 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 operaciones de subida de imágenes a resourceUpdates, en caso de que haya alguna pendiente. Cuando no hay nuevos datos (por ejemplo, porque no se ha producido setImage() desde la última llamada a esta función), la función no hace nada.
Se espera que los materiales que incluyan texturas rhi llamen a esta función desde su implementación updateSampledImage(), normalmente sin ninguna condición, pasando state.rhi() y state.resourceUpdateBatch() desde QSGMaterialShader::RenderState.
Advertencia: Esta función sólo puede ser llamada 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. Típicamente usado en implementaciones de QSGMaterial::compare().
Comparar simplemente punteros QSGTexture no siempre es suficiente porque dos instancias QSGTexture que se refieren al mismo objeto de textura nativa por debajo 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), y no deberían hacerlo, en caso de que aún no existan.
Un QSGTexture que no tiene un objeto de textura nativo debajo no es normalmente igual a ningún otro QSGTexture, por lo que el valor de retorno tiene que ser elaborado en consecuencia. Hay excepciones a esto, en particular cuando se utiliza atlasing (donde múltiples texturas comparten la misma textura atlas bajo el capó), que depende de las implementaciones de la subclase para tratar como corresponda.
Advertencia: Esta función sólo puede ser llamada 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 a 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 textura contienen niveles mipmap.
QSGTexture::WrapMode QSGTexture::horizontalWrapMode() const
Devuelve el modo de envoltura horizontal a utilizar para esta textura.
Véase también setHorizontalWrapMode().
[virtual] bool QSGTexture::isAtlasTexture() const
Devuelve si esta textura es parte de un atlas o no.
La implementación por defecto devuelve false.
QSGTexture::Filtering QSGTexture::mipmapFiltering() const
Devuelve si el mipmapping debe ser usado cuando se muestrea desde esta textura.
Véase también setMipmapFiltering().
template <typename QNativeInterface> QNativeInterface *QSGTexture::nativeInterface() const
Devuelve una interfaz nativa del tipo dado para la textura.
Esta función proporciona acceso a la funcionalidad específica de plataforma de QSGTexture, tal y como se declara en el espacio de nombres QNativeInterface:
Proporciona acceso y permite adoptar objetos de textura Direct3D 11. | |
Proporciona acceso a objetos de textura Direct3D 12 y permite adoptarlos. | |
Proporciona acceso a objetos de textura Metal y permite adoptarlos. | |
Proporciona acceso a objetos de textura OpenGL y permite adoptarlos. | |
Proporciona acceso y permite adoptar objetos de imagen Vulkan. |
Permite acceder al objeto de textura nativo subyacente, como el ID de textura GLuint con OpenGL, o el controlador VkImage con Vulkan.
Si la interfaz solicitada no está disponible, se devuelve nullptr.
[virtual] QRectF QSGTexture::normalizedTextureSubRect() const
Devuelve el rectángulo dentro de textureSize() que esta textura representa en coordenadas normalizadas.
La implementación por defecto devuelve un rectángulo en la posición (0, 0) con anchura y 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 la textura.
Eliminar una textura de un atlas es principalmente útil cuando se pasa a un shader que opera sobre las coordenadas de la textura 0-1 en lugar de la textura subrect 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 en múltiples llamadas para 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 nula, la implementación de removedFromAtlas() crea su propio lote y lo envía inmediatamente. Sin embargo, cuando se especifica una instancia válida, esta función no enviará el lote de actualización.
Advertencia: Esta función sólo puede invocarse desde el subproceso de renderización.
[virtual, since 6.0] QRhiTexture *QSGTexture::rhiTexture() const
Devuelve el QRhiTexture para este QSGTexture o null si no hay ninguno (ya sea porque una textura válida no ha sido creada internamente todavía, o porque el concepto no es aplicable al backend del scenegraph en uso).
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. La expectativa de cara al renderizador es que una textura nula lleve a utilizar una textura ficticia transparente en su lugar.
Advertencia: Esta función sólo puede ser llamada 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 se activa el filtrado anisotrópico.
Nota: La petición puede ser ignorada dependiendo de la API gráfica en uso. No hay garantía de que el filtrado anisotrópico esté soportado 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 mipmap en filter.
Establecer el filtrado mipmap no tiene 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 envoltura vertical a 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.
