Datos programables de materiales, efectos, geometría y texturas
Aunque los materiales integrados de Qt Quick 3D, DefaultMaterial y PrincipledMaterial permiten un amplio grado de personalización a través de sus propiedades, no ofrecen programabilidad a nivel de sombreadores de vértices y fragmentos. Para permitirlo, se proporciona el tipo « CustomMaterial ».
| Un modelo con PrincipledMaterial | Con un « CustomMaterial » que transforma los vértices |
|---|---|
|
|
Los efectos de posprocesamiento, en los que se realizan una o más pasadas de procesamiento sobre el búfer de color —teniendo en cuenta opcionalmente el búfer de profundidad— antes de que la salida del « View3D » se pase a « Qt Quick », también existen en dos variantes:
- pasos de posprocesamiento integrados que se pueden configurar a través de ExtendedSceneEnvironment, como resplandor/bloom, profundidad de campo, viñeteado, destello de lente,
customefectos implementados por la aplicación en forma de código de sombreador de fragmentos y una especificación de las pasadas de procesamiento en un objeto ` Effect `.
En la práctica, existe una tercera categoría de efectos de posprocesamiento: los efectos 2D implementados a través de Qt Quick, que actúan sobre la salida del elemento View3D sin ninguna intervención del renderizador 3D. Por ejemplo, para aplicar un desenfoque a un elemento « View3D », el enfoque más sencillo consiste en utilizar las funciones existentes de « Qt Quick », como « MultiEffect ». El sistema de posprocesamiento 3D resulta útil para efectos complejos que implican conceptos de la escena 3D, como el búfer de profundidad o la textura de pantalla, o que requieren gestionar el mapeo de tonos HDR o necesitan múltiples pasadas con búferes intermedios, etc. Los efectos 2D sencillos que no requieren ningún conocimiento de la escena 3D ni del renderizador siempre pueden implementarse utilizando, en su lugar, ShaderEffect o MultiEffect.
| Escena sin efecto | La misma escena con un efecto de posprocesamiento personalizado aplicado |
|---|---|
|
|
Además de los materiales programables y el posprocesado, hay dos tipos de datos que normalmente se proporcionan en forma de archivos (archivos.mesh o imágenes como .png):
- datos de vértices, que incluyen la geometría de la malla que se va a renderizar, las coordenadas de textura, las normales, los colores y otros datos,
- el contenido de las texturas que luego se utilizan como mapas de textura para los objetos renderizados, o que se emplean con skybox o iluminación basada en imágenes.
Si así lo desean, las aplicaciones pueden proporcionar dichos datos desde C++ en forma de un QByteArray. Dichos datos también pueden modificarse a lo largo del tiempo, lo que permite generar de forma procedural y alterar posteriormente los datos para un Model o un Texture.
| Una rejilla, renderizada especificando los datos de vértices de forma dinámica desde C++ | Un cubo texturizado con datos de imagen generados desde C++ |
|---|---|
|
|
Estos cuatro enfoques para personalizar y hacer dinámicos los materiales, los efectos, la geometría y las texturas permiten la programabilidad del sombreado y la generación procedural de los datos que los sombreadores reciben como entrada. Las secciones siguientes ofrecen una visión general de estas características. La referencia completa está disponible en las páginas de documentación de los tipos respectivos:
Nota: Para obtener un control total sobre todo el proceso de renderizado, incluidas las pasadas de renderizado múltiples y los destinos de renderizado personalizados, consulta «Pasadas de renderizado definidas por el usuario» en « Qt Quick 3D». Las pasadas de renderizado definidas por el usuario complementan las características descritas en esta página, ya que te permiten definir toda la arquitectura del proceso de renderizado, mientras que « CustomMaterial » y «Effect» se centran en personalizar materiales individuales y pasos de posprocesamiento dentro de dicho proceso.
| Funcionalidad | Documentación de referencia | Ejemplos relevantes |
|---|---|---|
| Materiales personalizados | CustomMaterial | Qt Quick 3D - Ejemplo de sombreadores personalizados, Qt Quick 3D - Ejemplo de materiales personalizados |
| Efectos de posprocesamiento personalizados | Effect | Qt Quick 3D - Ejemplo de efecto personalizado |
| Geometría personalizada | QQuick3DGeometry, Model::geometry | Qt Quick 3D - Ejemplo de geometría personalizada |
| Datos de texturas personalizadas | QQuick3DTextureData, Texture::textureData | Qt Quick 3D - Ejemplo de textura procedural |
Programabilidad de los materiales
Creemos una escena con un cubo y empecemos con un « PrincipledMaterial » y un « CustomMaterial » predeterminados:
| PrincipledMaterial | CustomMaterial |
|---|---|
| |
Ambos dan exactamente el mismo resultado, ya que un « CustomMaterial » es, en la práctica, un « PrincipledMaterial », cuando no se le añade código de sombreador de vértices ni de fragmentos.

Nota: Las propiedades como baseColor, metalness, baseColorMap y muchas otras no tienen propiedades equivalentes en el tipo QML CustomMaterial. Esto es intencionado: la personalización del material se realiza mediante código de sombreador, no simplemente proporcionando unos pocos valores fijos.
Nuestro primer sombreador de vértices
Añadamos un fragmento de código de sombreador de vértices personalizado. Para ello, hacemos referencia a un archivo en la propiedad vertexShader. El procedimiento será el mismo para los sombreadores de fragmentos. Estas referencias funcionan como Image.source o ShaderEffect.vertexShader: son URL locales o de qrc, y una ruta relativa se interpreta con respecto a la ubicación del archivo .qml. Por lo tanto, el enfoque habitual consiste en colocar los archivos .vert y .frag en el sistema de recursos de Qt (qt_add_resources cuando se utiliza CMake) y hacer referencia a ellos mediante una ruta relativa.
En Qt 6.0 ya no se admiten las cadenas de shader en línea, ni en Qt Quick ni en Qt Quick 3D. (Ten en cuenta que estas propiedades son URL, no cadenas de caracteres). Sin embargo, debido a su naturaleza intrínsecamente dinámica, los materiales personalizados y los efectos de posprocesamiento en Qt Quick 3D siguen proporcionando fragmentos de shader en formato fuente en los archivos a los que se hace referencia. Esto difiere de ShaderEffect, donde los shaders están completos por sí mismos, sin que el motor realice modificaciones adicionales, por lo que se espera que se proporcionen como paquetes de shaders .qsb preconfigurados.
Nota: En Qt Quick 3D, las URL solo pueden hacer referencia a recursos locales. No se admiten esquemas para contenido remoto.
Nota: El lenguaje de sombreado utilizado es GLSL compatible con Vulkan. Los archivos .vert y .frag no son sombreadores completos por sí mismos, por lo que a menudo se denominan « snippets ». Por eso no hay bloques uniformes, variables de entrada y salida, ni uniformes de muestreador proporcionados directamente por estos fragmentos de código. En su lugar, el motor 3D Qt Quick los modificará según corresponda.
| Modificación en main.qml, material.vert | Resultado |
|---|---|
|
|
Se espera que un fragmento de código de shader de vértices o de fragmentos personalizado proporcione una o más funciones con nombres predefinidos, tales como MAIN, DIRECTIONAL_LIGHT, POINT_LIGHT, SPOT_LIGHT, AMBIENT_LIGHT y SPECULAR_LIGHT. Por ahora, centrémonos en MAIN.
Como se muestra aquí, el resultado final con un MAIN() vacío es exactamente el mismo que antes.
Antes de complicarlo un poco más, echemos un vistazo general a las palabras clave especiales más utilizadas en los fragmentos de código de sombreadores de vértices personalizados. Esta no es la lista completa. Para consultar la referencia completa, visita la página CustomMaterial.
| Palabra clave | Tipo | Descripción |
|---|---|---|
| MAIN | void MAIN() es el punto de entrada. Esta función debe estar siempre presente en un fragmento de código de sombreador de vértices personalizado; de lo contrario, no tiene sentido incluirla. | |
| VERTEX | vec3 | La posición del vértice que el sombreador recibe como entrada. Un caso de uso habitual de los sombreadores de vértices en materiales personalizados es modificar (desplazar) los valores x, y o z de este vector, simplemente asignando un valor al vector completo o a algunos de sus componentes. |
| NORMAL | vec3 | La normal del vértice procedente de los datos de la malla de entrada, o todos ceros si no se han proporcionado normales. Al igual que con VERTEX, el sombreador es libre de modificar el valor como considere oportuno. El valor modificado es utilizado posteriormente por el resto del proceso, incluidos los cálculos de iluminación en la etapa de fragmento. |
| UV0 | vec2 | El primer conjunto de coordenadas de textura de los datos de la malla de entrada, o todos ceros si no se han proporcionado valores UV. Al igual que con VERTEX y NORMAL, el valor puede modificarse. |
| MODELVIEWPROJECTION_MATRIX | mat4 | La matriz de modelo-vista-proyección. Para unificar el comportamiento independientemente de la API gráfica con la que se realice el renderizado, todos los datos de vértices y las matrices de transformación siguen las convenciones de OpenGL en este nivel. (Eje Y apuntando hacia arriba, matriz de proyección compatible con OpenGL). Solo lectura. |
| MODEL_MATRIX | mat4 | La matriz del modelo (mundo). Solo lectura. |
| MATRIZ_NORMAL | mat3 | La inversa transpuesta del segmento 3x3 situado en la esquina superior izquierda de la matriz del modelo. Solo lectura. |
| CAMERA_POSITION | vec3 | La posición de la cámara en el espacio mundial. En los ejemplos de esta página, es (0, 0, 600). Solo lectura. |
| CAMERA_DIRECTION | vec3 | El vector de dirección de la cámara. En los ejemplos de esta página es (0, 0, -1). Solo lectura. |
| CAMERA_PROPERTIES | vec2 | Los valores de recorte cercano y lejano de la cámara. En los ejemplos de esta página es (10, 10000). Solo lectura. |
| POINT_SIZE | float | Solo es relevante al renderizar con una topología de puntos, por ejemplo, porque la función « custom geometry » proporciona dicha geometría para la malla. Escribir en este valor equivale a establecer « pointSize on a PrincipledMaterial ». |
| POSITION | vec4 | Al igual que gl_Position. Cuando no está presente, se genera automáticamente una instrucción de asignación por defecto utilizando MODELVIEWPROJECTION_MATRIX y VERTEX. Por eso funciona un MAIN() vacío y, en la mayoría de los casos, no será necesario asignarle un valor personalizado. |
Creemos un material personalizado que desplace los vértices según un patrón determinado. Para hacerlo más interesante, incluiremos algunas propiedades QML animadas, cuyos valores acabarán exponiéndose como uniformes en el código del sombreador. (Para ser precisos, la mayoría de las propiedades se asignarán a miembros de un bloque «uniform», respaldado por un búfer «uniform» en tiempo de ejecución, pero Qt Quick 3D hace que, convenientemente, estos detalles sean transparentes para el creador del material personalizado).
| Modificación en main.qml, material.vert | Resultado |
|---|---|
|
Uniformes a partir de propiedades de QML
Las propiedades personalizadas del objeto ` CustomMaterial ` se asignan a uniformes. En el ejemplo anterior, esto incluye ` uAmplitude ` y ` uTime`. Cada vez que los valores cambien, el valor actualizado se hará visible en el shader. Es posible que ya te resulte familiar este concepto por ShaderEffect.
El nombre de la propiedad QML y el de la variable GLSL deben coincidir. No hay una declaración separada en el código del sombreador para cada uno de los uniformes. En su lugar, el nombre de la propiedad QML se puede utilizar tal cual. Por eso, en el ejemplo anterior basta con hacer referencia a uTime y uAmplitude en el fragmento de código del sombreador de vértices sin necesidad de declararlos previamente.
La siguiente tabla muestra cómo se asignan los tipos:
| Tipo QML | Tipo de sombreador | Notas |
|---|---|---|
| real, int, bool | float, int, bool | |
| color | vec4 | La conversión de sRGB a lineal se realiza de forma implícita |
| vector2d | vec2 | |
| vector3d | vec3 | |
| vector4d | vec4 | |
| matriz4x4 | mat4 | |
| cuaternión | vec4 | valor escalar es w |
| rect | vec4 | |
| punto, tamaño | vec2 | |
| TextureInput | sampler2D |
Mejorando el ejemplo
Antes de continuar, vamos a mejorar un poco el aspecto del ejemplo. Añadiendo una malla rectangular girada y haciendo que el « DirectionalLight » proyecte sombras, podemos comprobar que la modificación de los vértices del cubo se refleja correctamente en todas las pasadas de renderizado, incluidos los mapas de sombras. Para conseguir una sombra visible, ahora se coloca la luz un poco más arriba en el eje Y y se le aplica una rotación para que apunte parcialmente hacia abajo. (Al tratarse de una luz de tipo « directional », la rotación es importante)
| main.qml, material.vert | Resultado |
|---|---|
|
Añadir un sombreador de fragmentos
Muchos materiales personalizados también querrán tener un sombreador de fragmentos. De hecho, muchos solo querrán un sombreador de fragmentos. Si no hay datos adicionales que pasar de la etapa de vértices a la de fragmentos, y la transformación de vértices por defecto es suficiente, se puede omitir la configuración de la propiedad « vertexShader » en el « CustomMaterial ».
| Modificación en main.qml, material.frag | Resultado |
|---|---|
|
|
Nuestro primer sombreador de fragmentos contiene una función MAIN() vacía. Esto no difiere en nada de no especificar ningún fragmento de código de sombreador de fragmentos: el resultado es similar al que se obtiene con un PrincipledMaterial por defecto.
Veamos algunas de las palabras clave más utilizadas en los sombreadores de fragmentos. Esta no es la lista completa; consulta la documentación de CustomMaterial para obtener una referencia completa. Muchas de ellas son de lectura y escritura, lo que significa que tienen un valor por defecto, pero el sombreador puede —y a menudo querrá— asignarles un valor diferente.
Como sugieren sus nombres, muchas de ellas se corresponden con propiedades de PrincipledMaterial de nombre similar, con el mismo significado y semántica, siguiendo el modelo de material «metalic-roughness». Depende de la implementación del material personalizado decidir cómo se calculan estos valores: por ejemplo, un valor para « BASE_COLOR » puede estar codificado de forma fija en el sombreador, puede basarse en el muestreo de una textura o puede calcularse a partir de propiedades QML expuestas como uniformes o de datos interpolados pasados desde el sombreador de vértices.
| Palabra clave | Tipo | Descripción |
|---|---|---|
| BASE_COLOR | vec4 | El color base y el valor alfa. Se corresponde con PrincipledMaterial::baseColor. El valor alfa final del fragmento es la opacidad del modelo multiplicada por el alfa del color base. El valor por defecto es (1.0, 1.0, 1.0, 1.0). |
| EMISSIVE_COLOR | vec3 | El color de la autoiluminación. Se corresponde con PrincipledMaterial::emissiveFactor. El valor por defecto es (0.0, 0.0, 0.0). |
| METALNESS | float | Metalness Valor comprendido entre 0 y 1. El valor por defecto es 0, lo que significa que el material es dieléctrico (no metálico). |
| ROUGHNESS | flotante | Roughness valor comprendido entre 0 y 1. El valor por defecto es 0. Los valores más altos suavizan los reflejos especulares y difuminan los reflejos. |
| SPECULAR_AMOUNT | flotante | The strength of specularity en el rango de 0 a 1. El valor por defecto es 0.5. Para objetos metálicos con « metalness » establecido en 1, este valor no tendrá ningún efecto. Cuando tanto « SPECULAR_AMOUNT » como « METALNESS » tienen valores mayores que 0 pero menores que 1, el resultado es una mezcla entre los dos modelos de material. |
| NORMAL | vec3 | La normal interpolada en el espacio del mundo, ajustada para tener en cuenta la doble cara cuando el culling de caras está desactivado. Solo lectura. |
| UV0 | vec2 | Las coordenadas de textura interpoladas. Solo lectura. |
| VAR_WORLD_POSITION | vec3 | Posición interpolada del vértice en el espacio mundial. Solo lectura. |
Hagamos que el color de base del cubo sea rojo:
| Cambia en main.qml, material.frag | Resultado |
|---|---|
|
|
Ahora aumentemos un poco el nivel de autoiluminación:
| Modificación en main.qml, material.frag | Resultado |
|---|---|
|
|
En lugar de tener valores codificados de forma fija en el sombreador, también podríamos utilizar propiedades de QML expuestas como variables uniformes, incluso animadas:
| Modificación en main.qml, material.frag | Resultado |
|---|---|
|
Hagamos algo menos trivial, algo que no se pueda implementar con un « PrincipledMaterial » y sus propiedades estándar integradas. El siguiente material visualiza las coordenadas UV de la textura de la malla del cubo. U va de 0 a 1, es decir, de negro a rojo, mientras que V también va de 0 a 1, de negro a verde.
| Modificación en main.qml, material.frag | Resultado |
|---|---|
|
|
Ya que estamos, ¿por qué no visualizar también las normales, esta vez en una esfera? Al igual que con las coordenadas UV, si un fragmento de sombreador de vértices personalizado modificara el valor de NORMAL, el valor interpolado por fragmento en el sombreador de fragmentos —que también se expone con el nombre NORMAL— reflejaría esos ajustes.
| Modificación en main.qml, material.frag | Resultado |
|---|---|
|
|
Colores
Pasemos por un momento a un modelo de tetera, hagamos que el material sea una mezcla de metálico y dieléctrico, e intentemos establecer un color base verde para él. El valor « green » QColor se corresponde con (0, 128, 0), por lo que nuestro primer intento podría ser:
| main.qml, material.frag |
|---|
|

Esto no parece del todo correcto. Compáralo con el segundo enfoque:
| Cambio en main.qml, material.frag | Resultado |
|---|---|
|
|
Al cambiar a un PrincipledMaterial, podemos confirmar que, al establecer el PrincipledMaterial::baseColor en «green» y ajustando la metalidad y otras propiedades, el resultado es idéntico al de nuestro segundo enfoque:
| Cambio en main.qml | Resultado |
|---|---|
|
|
Si el tipo de la propiedad « uColor » se cambiara a « vector4d », o a cualquier otro tipo distinto de « color », los resultados cambiarían repentinamente y pasarían a ser idénticos a los de nuestro primer enfoque.
¿A qué se debe esto?
La respuesta radica en la conversión de sRGB a lineal que se realiza de forma implícita para las propiedades de color de DefaultMaterial, PrincipledMaterial, y también para las propiedades personalizadas con un tipo color en un CustomMaterial. Dicha conversión no se realiza para ningún otro valor, por lo que si el sombreador codifica de forma fija un valor de color, o lo basa en una propiedad QML con un tipo distinto de color, será responsabilidad del sombreador realizar la linealización en caso de que el valor de origen estuviera en el espacio de color sRGB. La conversión a lineal es importante, ya que Qt Quick 3D realiza un proceso de « tonemapping » sobre los resultados del sombreado de fragmentos, y dicho proceso asume valores en el espacio sRGB como entrada.
Las constantes integradas de QColor, como "green", se expresan todas en el espacio sRGB. Por lo tanto, limitarse a asignar vec4(0.0, 0.5, 0.0, 1.0) a BASE_COLOR en un primer intento resulta insuficiente si queremos obtener un resultado que coincida con un valor RGB (0, 128, 0) en el espacio sRGB. Consulte la documentación de « BASE_COLOR » en CustomMaterial para ver una fórmula que permita linealizar dichos valores de color. Lo mismo se aplica a los valores de color obtenidos al muestrear texturas: si los datos de la imagen de origen no están en el espacio de color sRGB, es necesaria una conversión (a menos que se haya desactivado « tonemapping »).
Mezcla
No basta con asignar un valor inferior a 1.0 a BASE_COLOR.a si se desea obtener una mezcla alfa. Estos materiales suelen modificar los valores de las propiedades sourceBlend y destinationBlend para obtener los resultados deseados.
Ten en cuenta también que el valor alfa combinado es el de Node opacity multiplicado por el alfa del material.
Para visualizarlo, utilicemos un sombreador que asigne el color rojo con alfa 0.5 a BASE_COLOR:
| main.qml, material.frag | Resultado |
|---|---|
|
|
El primer cubo asigna un valor alfa de 0,5 al color, pero no se aprecian resultados visibles, ya que la mezcla alfa no está habilitada. El segundo cubo habilita una mezcla alfa sencilla a través de las propiedades « CustomMaterial ». El tercero también asigna una opacidad de 0,5 al modelo, lo que significa que la opacidad efectiva es de 0,25.
Pasar datos entre el sombreador de vértices y el de fragmentos
Se calcula un valor por vértice (por ejemplo, suponiendo un único triángulo, para las tres esquinas del triángulo) y, a continuación, se pasa a la etapa de fragmentos, donde, para cada fragmento (por ejemplo, cada fragmento cubierto por el triángulo rasterizado), se hace accesible un valor interpolado. En los fragmentos de código de sombreadores de material personalizados, esto es posible gracias a la palabra clave « VARYING ». Esta proporciona una sintaxis similar a la de GLSL 120 y GLSL ES 100, pero funcionará independientemente de la API gráfica utilizada en tiempo de ejecución. El motor se encargará de reescribir la declaración de variables según corresponda.
Veamos cómo quedaría el muestreo clásico de texturas con coordenadas UV. Las texturas se tratarán en una sección posterior; por ahora, centrémonos en cómo obtener las coordenadas UV que se pueden pasar a la función ` texture() ` en el sombreador.
| main.qml, material.vert, material.frag |
|---|
|
| qt_logo_rect.png | Resultado |
|---|---|
|
|
Fíjate en las declaraciones « VARYING ». El nombre y el tipo deben coincidir; « uv » en el sombreador de fragmentos expondrá la coordenada UV interpolada para el fragmento actual.
Cualquier otro tipo de datos puede pasarse a la etapa de fragmento de manera similar. Cabe destacar que, en muchos casos, no es necesario configurar las variables propias del material, ya que existen variables integradas que cubren muchas de las necesidades típicas. Esto incluye la generación de normales (interpoladas), coordenadas UV, posición en el mundo (VAR_WORLD_POSITION) o el vector que apunta hacia la cámara (VIEW_VECTOR).
De hecho, el ejemplo anterior se puede simplificar de la siguiente manera, ya que UV0 también está disponible automáticamente en la etapa de fragmento:
| Modificación en main.qml, material.frag | Resultado |
|---|---|
|
|
Para desactivar la interpolación de una variable, utiliza la palabra clave flat tanto en el fragmento de código del sombreador de vértices como en el del sombreador de fragmentos. Por ejemplo:
VARYING flat vec2 v;Texturas
Un « CustomMaterial » no tiene mapas de textura integrados, lo que significa que no existe un equivalente a, por ejemplo, « PrincipledMaterial::baseColorMap ». Esto se debe a que implementar lo mismo suele ser trivial, al tiempo que ofrece mucha más flexibilidad que la que tienen integrada «DefaultMaterial» y « PrincipledMaterial ». Además de simplemente muestrear una textura, los fragmentos de código personalizados del sombreador de fragmentos tienen libertad para combinar y mezclar datos de diversas fuentes al calcular los valores que asignan a BASE_COLOR, EMISSIVE_COLOR, ROUGHNESS, etc. Pueden basar estos cálculos en datos proporcionados a través de propiedades QML, datos interpolados enviados desde la etapa de vértices, valores recuperados del muestreo de texturas y en valores codificados de forma fija.
Como muestra el ejemplo anterior, exponer una textura al sombreador de vértices, al de fragmentos o a ambos es muy similar a los valores uniformes escalares y vectoriales: una propiedad QML del tipo TextureInput se asociará automáticamente con un sampler2D en el código del sombreador. Como siempre, no es necesario declarar este muestreador en el código del sombreador.
Un « TextureInput » hace referencia a un « Texture », con una propiedad adicional « enabled ». Un « Texture » puede obtener sus datos de tres formas: « from an image file », from a texture with live Qt Quick contento can be provided from C++ a través de QQuick3DTextureData.
Nota: En lo que respecta a las propiedades Texture, las relacionadas con el origen, el mosaico y el filtrado son las únicas que se tienen en cuenta de forma implícita con los materiales personalizados, ya que el resto (como, por ejemplo, las transformaciones UV) depende de que los sombreadores personalizados las implementen como consideren oportuno.
Veamos un ejemplo en el que se aplica una textura a un modelo —una esfera, en este caso— utilizando contenido de « Qt Quick » en tiempo real:
| main.qml, material.frag |
|---|
|
Aquí, el subárbol 2D (un rectángulo con dos elementos hijos: otro rectángulo y el texto) se renderiza en una textura 2D de 512x512 cada vez que cambia esta miniescena. A continuación, la textura se asigna al material personalizado con el nombre de « someTextureMap ».
Fíjate en la inversión de la coordenada V en el shader. Como se ha señalado anteriormente, los materiales personalizados, en los que existe una programabilidad total a nivel de shader, no ofrecen las características «fijas» de Texture y PrincipledMaterial. Esto significa que cualquier transformación de las coordenadas UV deberá ser aplicada por el shader. En este caso sabemos que la textura se genera mediante Texture::sourceItem, por lo que hay que invertir la coordenada V para obtener un resultado que coincida con el conjunto UV de la malla que estamos utilizando.
Lo que muestra este ejemplo también se puede hacer con un « PrincipledMaterial ». Hagámoslo más interesante añadiendo además un sencillo efecto de relieve:
| material.frag | Resultado |
|---|---|
|
Con las funciones vistas hasta ahora, se abre un amplio abanico de posibilidades para crear materiales que sombreen las mallas de formas visualmente impresionantes. Para terminar el recorrido básico, veamos un ejemplo en el que se aplican mapas de altura y de normales a una malla plana. (Aquí se utiliza un archivo « .mesh » específico, ya que el « #Rectangle » integrado no tiene suficientes subdivisiones) Para obtener mejores resultados de iluminación, utilizaremos iluminación basada en imágenes con una imagen HDR de 360 grados. La imagen también se configura como skybox para que quede más claro lo que está sucediendo.
Empecemos primero con un archivo CustomMaterial vacío:
| main.qml | Resultado |
|---|---|
|
|
Ahora vamos a crear algunos shaders que apliquen un mapa de altura y un mapa de normales a la malla:
| Mapa de altura | Mapa de normales |
|---|---|
|
|
| material.vert, material.frag |
|---|
|
| Cambio en main.qml | Resultado |
|---|---|
|
|
Nota: El objeto ` WasdController ` puede resultar de gran ayuda durante el desarrollo y la resolución de problemas, ya que permite navegar y explorar la escena con el teclado y el ratón de una forma familiar. Contar con una cámara controlada por ` WasdController ` es tan sencillo como:
import QtQuick3D.Helpers
View3D {
PerspectiveCamera {
id: camera
}
// ...
}
WasdController {
controlledObject: camera
}Texturas de profundidad y de pantalla
Cuando un fragmento de shader personalizado utiliza las palabras clave « DEPTH_TEXTURE » o « SCREEN_TEXTURE », opta por generar las texturas correspondientes en una pasada de renderizado independiente, lo cual no es necesariamente una operación económica, pero permite implementar diversas técnicas, como la refracción para materiales similares al cristal.
DEPTH_TEXTURE « sampler2D » permite muestrear una textura con el contenido del búfer de profundidad una vez renderizados todos los objetos « opaque » de la escena. Del mismo modo, « SCREEN_TEXTURE » es un « sampler2D » que permite muestrear una textura que contenga el contenido de la escena, excluyendo cualquier material transparente o cualquier material que también utilice «SCREEN_TEXTURE». La textura se puede utilizar para materiales que requieran el contenido del búfer de fotogramas en el que se están renderizando. La textura SCREEN_TEXTURE utiliza el mismo modo de borrado que el View3D. El tamaño de estas texturas coincide con el tamaño del View3D en píxeles.
Veamos una demostración sencilla visualizando el contenido del búfer de profundidad mediante DEPTH_TEXTURE. Aquí se ha reducido el valor de « far clip value » de la cámara de los 10 000 predeterminados a 2 000, con el fin de obtener un rango más reducido y que así las diferencias en los valores de profundidad visualizados resulten más evidentes. El resultado es un rectángulo que muestra el búfer de profundidad de la escena sobre su superficie.
| main.qml, material.frag | Resultado |
|---|---|
|
Obsérvese que el cilindro no aparece en DEPTH_TEXTURE debido a que utiliza semitransparencia, lo que lo sitúa en una categoría diferente a la de los demás objetos, que son todos opacos. Estos objetos no escriben en el búfer de profundidad, aunque sí comparan sus valores con los valores de profundidad escritos por los objetos opacos, y dependen de que se rendericen en orden de atrás hacia adelante. Por lo tanto, tampoco aparecen en DEPTH_TEXTURE.
¿Qué ocurre si cambiamos el shader para que muestree « SCREEN_TEXTURE » en su lugar?
| material.frag | Resultado |
|---|---|
|
|
Aquí, el rectángulo se texturiza con SCREEN_TEXTURE, sustituyendo los píxeles transparentes por morados.
Funciones del procesador de luz
Una característica avanzada de CustomMaterial es la capacidad de definir funciones en el sombreador de fragmentos que reimplementan las ecuaciones de iluminación utilizadas para calcular el color del fragmento. Una función del procesador de luz, cuando está presente, se invoca una vez por cada luz de la escena, para cada fragmento. Existe una función específica para cada tipo de luz, así como para la contribución ambiental y especular. Cuando no hay ninguna función de procesador de luz correspondiente, se utilizan los cálculos estándar, tal y como haría un « PrincipledMaterial ». Cuando hay un procesador de luz, pero el cuerpo de la función está vacío, significa que no habrá contribución de un tipo determinado de luces en la escena.
Consulta la documentación de CustomMaterial para obtener más detalles sobre funciones como DIRECTIONAL_LIGHT, POINT_LIGHT, SPOT_LIGHT, AMBIENT_LIGHT y SPECULAR_LIGHT.
Materiales personalizados sin sombreado
Existe otro tipo de « CustomMaterial »: los materiales personalizados « unshaded ». Todos los ejemplos anteriores utilizaban materiales personalizados « shaded », con la propiedad « shadingMode » establecida en su valor predeterminado « CustomMaterial.Shaded».
¿Qué ocurre si cambiamos esta propiedad a CustomMaterial.Unshaded?
En primer lugar, las palabras clave como BASE_COLOR, EMISSIVE_COLOR, METALNESS, etc., ya no tienen el efecto deseado. Esto se debe a que un material sin sombreado, como su nombre indica, no se modifica automáticamente con gran parte del código de sombreado estándar, por lo que ignora las luces, la iluminación basada en imágenes, las sombras y la oclusión ambiental de la escena. En cambio, un material sin sombreado otorga control total al sombreador a través de la palabra clave « FRAGCOLOR ». Esto es similar a «gl_FragColor»: el color asignado a « FRAGCOLOR » es el resultado y el color final del fragmento, sin ningún ajuste adicional por parte de « Qt Quick » 3D.
| main.qml, material.frag, material2.frag | Resultado |
|---|---|
|
|
Fíjate en cómo el cilindro de la derecha ignora el DirectionalLight de la escena. Su sombreado no tiene en cuenta la iluminación de la escena, por lo que el color final del fragmento es totalmente blanco.
El sombreador de vértices de un material sin sombreado sigue disponiendo de las entradas habituales: VERTEX, NORMAL, MODELVIEWPROJECTION_MATRIX, etc., y puede escribir en POSITION. Sin embargo, el sombreador de fragmentos ya no cuenta con esas mismas facilidades: NORMAL, UV0 o VAR_WORLD_POSITION no están disponibles en el sombreador de fragmentos de un material sin sombreado. En su lugar, ahora corresponde al código del sombreador calcular y pasar, mediante VARYING, todo lo que necesita para determinar el color final del fragmento.
Veamos un ejemplo que cuenta tanto con un sombreador de vértices como con uno de fragmentos. La posición modificada del vértice se transmite al sombreador de fragmentos, donde se pone a disposición de cada fragmento un valor interpolado.
| main.qml, material.vert, material.frag |
|---|
|
Los materiales sin sombreado resultan útiles cuando no es necesario ni deseable interactuar con la iluminación de la escena, y el material necesita un control total sobre el color final del fragmento. Fíjate en que el ejemplo anterior no tiene ni una luz « DirectionalLight » ni ninguna otra luz, pero la esfera con el material personalizado se muestra tal y como se esperaba.
Nota: Un material sin sombreado que solo tenga un fragmento de sombreador de vértices, pero que no especifique la propiedad fragmentShader, seguirá siendo funcional, pero los resultados serán como si el shadingMode estuviera establecido en Shaded. Por lo tanto, no tiene mucho sentido cambiar el shadingMode para materiales que solo tengan un sombreador de vértices.
Programabilidad para efectos
Los efectos de posprocesamiento aplican uno o más sombreadores de fragmento al resultado de un sombreador de vértices ( View3D). A continuación, se muestra la salida de estos sombreadores de fragmento en lugar de los resultados originales del renderizado. Conceptualmente, esto es muy similar a los « ShaderEffect » y « ShaderEffectSource » de Qt Quick.
Nota: Los efectosde posprocesamiento solo están disponibles cuando el ` renderMode ` del ` View3D ` está configurado en ` View3D.Offscreen`.
También se pueden especificar fragmentos de shader de vértices personalizados para un efecto, pero su utilidad es limitada, por lo que se espera que se utilicen con relativa poca frecuencia. La entrada de vértices para un efecto de posprocesamiento es un cuadrilátero (ya sean dos triángulos o una tira de triángulos), por lo que transformar o desplazar los vértices de este a menudo no resulta útil. Sin embargo, puede tener sentido disponer de un sombreador de vértices para calcular y pasar datos al sombreador de fragmentos utilizando la palabra clave VARYING. Como es habitual, el sombreador de fragmentos recibirá entonces un valor interpolado basado en la coordenada actual del fragmento.
La sintaxis de los fragmentos de código de shader asociados a un « Effect » es idéntica a la de los shaders para un « CustomMaterial » sin sombreado. En cuanto a las palabras clave especiales integradas, « VARYING », « MAIN », « FRAGCOLOR » (solo en el shader de fragmentos), « POSITION » (solo en el shader de vértices), « VERTEX » (solo en el shader de vértices) y « MODELVIEWPROJECTION_MATRIX » funcionan de forma idéntica a « CustomMaterial ».
Las palabras clave especiales más importantes para los shaders de fragmento de « Effect » son las siguientes:
| Nombre | Tipo | Descripción |
|---|---|---|
| INPUT | sampler2D o sampler2DArray | El muestreador para la textura de entrada. Normalmente, un efecto muestreará esto utilizando « INPUT_UV ». |
| ENTRADA_UV | vec2 | Coordenadas UV para el muestreo de INPUT. |
| INPUT_SIZE | vec2 | El tamaño de la textura « INPUT », en píxeles. Es una alternativa práctica a llamar a textureSize(). |
| OUTPUT_SIZE | vec2 | El tamaño de la textura de salida, en píxeles. En muchos casos es igual a ` INPUT_SIZE `, pero un efecto de múltiples pasadas puede tener pasadas que generen texturas intermedias con tamaños diferentes. |
| DEPTH_TEXTURE | sampler2D | Textura de profundidad con el contenido del búfer de profundidad que incluye los objetos opacos de la escena. Al igual que con ` CustomMaterial`, la presencia de esta palabra clave en el shader activa la generación automática de la textura de profundidad. |
Nota: Cuando el renderizado multivista está habilitado, la textura de entrada es una matriz de texturas 2D. En ese caso, las funciones GLSL como `texture()` y `textureSize()` toman y devuelven un `vec3` o `ivec3`, respectivamente. Utiliza VIEW_INDEX para la capa. En aplicaciones de RV/RA que deseen funcionar tanto con como sin renderizado multivista, el enfoque más portátil consiste en escribir el código del sombreador de la siguiente manera:
#if QSHADER_VIEW_COUNT >= 2
vec4 c = texture(INPUT, vec3(INPUT_UV, VIEW_INDEX));
#else
vec4 c = texture(INPUT, INPUT_UV);
#endifUn efecto de posprocesamiento
Empecemos con una escena sencilla, esta vez utilizando algunos objetos más, incluido un rectángulo texturizado que utiliza una textura de tablero de ajedrez como mapa de colores base.
| main.qml | Resultado |
|---|---|
|
|
Ahora apliquemos un efecto a toda la escena. Más concretamente, a la capa « View3D ». Cuando hay varios elementos « View3D » en la escena, cada uno tiene su propio « SceneEnvironment » y, por lo tanto, su propia cadena de efectos de posprocesamiento. En el ejemplo hay un único « View3D » que cubre toda la ventana.
| Modificación en main.qml | effect.frag |
|---|---|
| |
Este sencillo efecto modifica el valor del canal de color rojo. Exponer propiedades QML como uniformes funciona de la misma manera con los efectos que con los materiales personalizados. El sombreador comienza con una línea que resultará muy habitual al escribir sombreadores de fragmentos para efectos: muestrear INPUT en las coordenadas UV INPUT_UV. A continuación, realiza los cálculos deseados y asigna el color final del fragmento a FRAGCOLOR.
Muchas de las propiedades definidas en el ejemplo aparecen en plural (efectos, pasadas, sombreadores). Aunque la sintaxis de la lista [ ] puede omitirse cuando solo hay un elemento, todas estas propiedades son listas y pueden contener más de un elemento. ¿A qué se debe esto?
- effects es una lista, porque View3D permite encadenar varios efectos. Los efectos se aplican en el orden en que se añaden a la lista. Esto permite aplicar fácilmente dos o más efectos juntos a View3D, y es similar a lo que se puede conseguir en Qt Quick anidando elementos de ShaderEffect. La textura «
INPUT» del siguiente efecto es siempre una textura que contiene la salida del efecto anterior. La salida del último efecto es la que se utiliza como salida final de « View3D ». - passes es una lista, ya que, a diferencia de ShaderEffect, Effect cuenta con soporte integrado para múltiples pasadas. Un efecto de múltiples pasadas es más potente que encadenar varios efectos independientes en effects: una pasada puede generar una textura temporal e intermedia, que luego puede utilizarse como entrada para las pasadas posteriores, además de la textura de entrada original del efecto. Esto permite crear efectos complejos que calculan, renderizan y mezclan varias texturas para obtener el color final del fragmento. Este caso de uso avanzado no se tratará aquí. Consulta la página de documentación Effect para obtener más detalles.
- shaders es una lista, ya que un efecto puede tener asociados tanto un sombreador de vértices como un sombreador de fragmentos.
Encadenamiento de varios efectos
Veamos un ejemplo en el que el efecto del ejemplo anterior se complementa con otro efecto similar al efecto integrado « DistortionSpiral ».
| Modificación en main.qml | effect2.frag |
|---|---|
| |
Ahora, la pregunta que quizá resulte sorprendente: ¿por qué es este un mal ejemplo?
Más concretamente, no es malo, sino que muestra un patrón que a menudo conviene evitar.
Encadenar efectos de esta manera puede resultar útil, pero es importante tener en cuenta las implicaciones en el rendimiento: realizar dos pasadas de renderizado (una para generar una textura con el canal de color rojo ajustado y otra para calcular la distorsión) es un gran derroche cuando bastaría con una sola. Si se hubieran combinado los fragmentos de código del sombreador de fragmentos, se habría podido conseguir el mismo resultado con un único efecto.
Definición de datos de malla y textura desde C++
La generación procedural de datos de malla y de imágenes de textura sigue pasos similares:
- Subclasificar ` QQuick3DGeometry ` o QQuick3DTextureData
- Establecer los datos de vértices o de imagen deseados durante la construcción llamando a las funciones miembro protegidas de la clase base
- Si posteriormente se necesitan cambios dinámicos en algún momento, establecer los nuevos datos y llamar a `update()`
- Una vez realizada la implementación, es necesario registrar la clase para que sea visible en QML
- Model y los objetos ` Texture ` en QML ya pueden utilizar el proveedor de datos de vértices o imágenes personalizado estableciendo la propiedad ` Model::geometry ` o ` Texture::textureData `
Datos de vértices personalizados
Los datos de vértices se refieren a la secuencia de valores (normalmente de tipo ` float`) que conforman una malla. En lugar de cargar archivos ` .mesh `, un proveedor de geometría personalizado se encarga de proporcionar los mismos datos. Los datos de vértices consisten en attributes, tales como la posición, las coordenadas de textura (UV) o las normales. La especificación de los atributos describe qué tipo de atributos están presentes, el tipo de componente (por ejemplo, un vector flotante de 3 componentes para la posición del vértice compuesto por los valores x, y, z), en qué desplazamiento comienzan en los datos proporcionados y cuál es el paso (el incremento que hay que sumar al desplazamiento para apuntar al siguiente elemento del mismo atributo).
Esto puede resultar familiar a quienes hayan trabajado directamente con API gráficas, como OpenGL o Vulkan, ya que la forma en que se especifica la entrada de vértices con esas API se corresponde, a grandes rasgos, con lo que define un archivo .mesh o una instancia de QQuick3DGeometry.
Además, también debe especificarse la topología de la malla (tipo de primitiva). Para el dibujo indexado, también deben proporcionarse los datos de un búfer de índices.
Existe una implementación integrada de geometría personalizada: el módulo QtQuick3D.Helpers incluye un tipo GridGeometry. Esto permite renderizar una cuadrícula en la escena con primitivas de línea, sin tener que implementar una subclase personalizada de QQuick3DGeometry.
Otro caso de uso habitual es la representación de puntos. Esto resulta bastante sencillo, ya que la especificación de atributos es mínima: proporcionamos tres valores flotantes (x, y, z) para cada vértice, nada más. Una subclase de ` QQuick3DGeometry ` podría implementar una geometría compuesta por 2000 puntos de forma similar a la siguiente:
clear();
const int N = 2000;
const int stride = 3 * sizeof(float);
QByteArray v;
v.resize(N * stride);
float *p = reinterpret_cast<float *>(v.data());
QRandomGenerator *rg = QRandomGenerator::global();
for (int i = 0; i < N; ++i) {
const float x = float(rg->bounded(200.0f) - 100.0f) / 20.0f;
const float y = float(rg->bounded(200.0f) - 100.0f) / 20.0f;
*p++ = x;
*p++ = y;
*p++ = 0.0f;
}
setVertexData(v);
setStride(stride);
setPrimitiveType(QQuick3DGeometry::PrimitiveType::Points);
addAttribute(QQuick3DGeometry::Attribute::PositionSemantic, 0, QQuick3DGeometry::Attribute::F32Type);En combinación con un material de
DefaultMaterial {
lighting: DefaultMaterial.NoLighting
cullMode: DefaultMaterial.NoCulling
diffuseColor: "yellow"
pointSize: 4
}el resultado final es similar a este (aquí visto desde un ángulo de cámara modificado, con la ayuda de ` WasdController`):

Nota: Ten en cuenta que es posible que, en tiempo de ejecución, no se admitan tamaños de punto ni anchos de línea distintos de 1, dependiendo de la API gráfica subyacente. Esto es algo sobre lo que Qt no tiene control. Por lo tanto, puede ser necesario implementar técnicas alternativas en lugar de depender del dibujo de puntos y líneas.
Datos de texturas personalizadas
En el caso de las texturas, los datos que hay que proporcionar son mucho más sencillos desde el punto de vista estructural: se trata de los datos de píxeles sin procesar, con un número variable de bytes por píxel, dependiendo del formato de la textura. Por ejemplo, una textura RGBA espera cuatro bytes por píxel, mientras que RGBA16F utiliza cuatro valores de tipo half-float por píxel. Esto es similar a lo que almacena internamente un QImage. Sin embargo, Qt Quick las texturas 3D pueden tener formatos cuyos datos no pueden representarse mediante un QImage. Por ejemplo, texturas HDR de punto flotante o texturas comprimidas. Por lo tanto, los datos de QQuick3DTextureData siempre se proporcionan como una secuencia sin procesar de bytes. Esto puede resultar familiar a quienes hayan trabajado directamente con API gráficas, como OpenGL o Vulkan.
Para obtener más detalles, consulta las páginas de documentación QQuick3DGeometry y QQuick3DTextureData.
Véase también CustomMaterial, Effect, QQuick3DGeometry, QQuick3DTextureData, Qt Quick 3D - Ejemplo de efecto personalizado, Qt Quick 3D - Ejemplo de sombreadores personalizados, Qt Quick 3D - Ejemplo de materiales personalizados, Qt Quick 3D - Ejemplo de geometría personalizada y Qt Quick 3D - Ejemplo de textura procedural.
© 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.























