Qt Quick 3D: ejemplo de materiales personalizados
Muestra cómo escribir materiales personalizados con sombreado.

Este ejemplo muestra cómo crear materiales con sombreado ( custom materials). Con los materiales con sombreado, no es necesario escribir programas de sombreador completos. En su lugar, escribimos funciones que modifican los sombreadores estándar de Qt. De este modo, el material resultante participará por defecto en la iluminación y el mapeo de sombras, y será compatible con las sondas de luz. Solo tenemos que escribir lógica personalizada para los casos en los que queramos un comportamiento especial. Esto se consigue ampliando de forma eficaz el código del sombreador que se generaría para un « PrincipledMaterial » con nuestras propias funciones personalizadas, que se invocan en determinadas etapas de los sombreadores de vértices y de fragmentos.
Para crear un material personalizado con sombreado, establece la propiedad « shadingMode » en « CustomMaterial.Shaded ».
Un material sencillo
El primer modelo utiliza un material sencillo que no añade ninguna lógica personalizada. Configuramos el material personalizado en el modelo igual que cualquier otro material:
Model {
source: "weirdShape.mesh"
scale: Qt.vector3d(100, 100, 100)
rotation: Quaternion.fromEulerAngles(-90, 0, 0)
x: v3d.radius
materials: [
CustomMaterial {
shadingMode: CustomMaterial.Shaded
fragmentShader: "material_simple.frag"
property color uDiffuse: "fuchsia"
property real uSpecular: 1.0
}
]
}Además de establecer « shadingMode » y « fragmentShader », también añadimos dos propiedades al material: « uDiffuse » y « Specular ». El sombreador de fragmentos las tendrá en cuenta.
El código del sombreador de fragmentos es breve:
void MAIN()
{
SPECULAR_AMOUNT = uSpecular;
BASE_COLOR = uDiffuse;
}Todos los sombreadores deben implementar la función MAIN. En este caso, utilizamos las propiedades definidas en los materiales para establecer los valores que utilizará el código del sombreador estándar de Qt. Ten en cuenta que no es necesario declararlas como variables uniformes: lo único que hay que hacer es asegurarse de que los nombres coincidan. Se produciría un error de compilación del sombreador si el material no tuviera propiedades que coincidieran.
Las variables especiales SPECULAR_AMOUNT y BASE_COLOR se corresponden con specularAmount y baseColor de PrincipledMaterial. A continuación, el código estándar del shader las utiliza para realizar cálculos de iluminación, tal y como si hubiéramos utilizado un PrincipledMaterial.
Manejo personalizado de las luces
El siguiente objeto utiliza un material más complejo que implementa una iluminación personalizada. El material tiene nombres de uniformes diferentes, pero por lo demás lo utilizamos de la misma manera:
materials: [
CustomMaterial {
shadingMode: CustomMaterial.Shaded
fragmentShader: "material_customlights.frag"
property color uDiffuse: "orange"
property real uShininess: 150
}
]El sombreador de fragmentos implementa una lógica personalizada para todos los diferentes tipos de luz:
void MAIN()
{
SPECULAR_AMOUNT = 1.0;
ROUGHNESS = 0.5;
BASE_COLOR = uDiffuse;
}
void AMBIENT_LIGHT()
{
DIFFUSE += uDiffuse.rgb * TOTAL_AMBIENT_COLOR;
}
void DIRECTIONAL_LIGHT()
{
DIFFUSE += uDiffuse.rgb * LIGHT_COLOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(NORMAL), TO_LIGHT_DIR)));
}
void POINT_LIGHT()
{
DIFFUSE += uDiffuse.rgb * LIGHT_COLOR * LIGHT_ATTENUATION * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(NORMAL), TO_LIGHT_DIR)));
}
void SPOT_LIGHT()
{
DIFFUSE += uDiffuse.rgb * LIGHT_COLOR * LIGHT_ATTENUATION * SPOT_FACTOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
}Aquí utilizamos muchas nuevas palabras clave especiales que hacen referencia a las propiedades de los distintos tipos de luz. Consulta la documentación de CustomMaterial para obtener una descripción de cada palabra clave. Ten en cuenta que cada tipo de luz tiene su propia función. Cualquier función que no se haya implementado utilizará la implementación por defecto, comportándose como PrincipledMaterial. Por ejemplo: en este sombreador, no hemos implementado SPECULAR_LIGHT(), por lo que obtendremos el reflejo especular integrado.
Añadir un sombreador de vértices
Un material personalizado también puede utilizar un sombreador de vértices para modificar la geometría del modelo. Aquí especificamos tanto el sombreador de fragmentos como el de vértices, y añadimos varias propiedades más que se tomarán como valores uniformes:
materials: [
CustomMaterial {
id: material
shadingMode: CustomMaterial.Shaded
vertexShader: "material_distortion.vert"
fragmentShader: "material_customlights.frag"
property real uTime: 0.0
property real uAmplitude: 0.3
property color uDiffuse: "yellow"
property real uShininess: 50
NumberAnimation {
target: material
property: "uTime"
from: 0.0
to: 31.4
duration: 10000
loops: Animation.Infinite
running: true
}
}
]El sombreador de vértices es muy breve:
// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
void MAIN()
{
VERTEX.y += sin(uTime + VERTEX.x*10.0) * uAmplitude;
}Esto deforma el modelo desplazando cada vértice según una onda sinusoidal que cambia con el tiempo.
Un material transparente
Por último, añadimos una esfera con un material transparente. Por motivos de rendimiento, Qt no implementa la transparencia de una forma totalmente realista. En su lugar, Qt renderiza todos los objetos opacos de la escena en una textura, y luego los materiales transparentes se leen a partir de esta textura. Esto significa que los materiales transparentes darán el mejor resultado cuando se coloquen delante de otros objetos:
Model {
id: screenSphere
source: "#Sphere"
scale: Qt.vector3d(0.75, 0.75, 0.75)
y: 60
z: 750;
materials: [
CustomMaterial {
shadingMode: CustomMaterial.Shaded
fragmentShader: "material_transparent.frag"
}
]Para este ejemplo, implementamos una función de distorsión simplificada que no intenta simular una refracción física real:
void MAIN()
{
vec2 size = vec2(textureSize(SCREEN_TEXTURE, 0));
vec2 uv = FRAGCOORD.xy / size;
vec3 view = normalize(VIEW_VECTOR);
vec3 projection = view - view * normalize(NORMAL);
vec3 refraction = projection * projection;
uv += refraction.xy * 0.5;
vec3 col = texture(SCREEN_TEXTURE, uv).rgb;
col = col * 0.8 + vec3(0.2);
BASE_COLOR = vec4(col, 1.0);
}SCREEN_TEXTURE se refiere a la textura que muestra todos los objetos opacos de la escena. Primero calculamos las coordenadas UV dentro de esta textura que coinciden con la posición en pantalla del vértice actual. A continuación, añadimos un desplazamiento a esta posición, simulando un efecto de refracción, antes de realizar una búsqueda en la textura.
Por último, mezclamos un 20 % de blanco para conseguir una ligera opacidad. Ten en cuenta que el resultado se asigna a ` BASE_COLOR`, por lo que Qt añadirá iluminación sobre ello. Por eso podemos ver reflejos en la superficie de la esfera.
Materiales sin sombreado
También es posible crear materiales personalizados que utilicen programas de sombreado completos (sin dejar de usar las palabras clave de conveniencia). El ejemplo «customshaders» muestra el otro grupo de materiales personalizados: los materiales personalizados sin sombreado.
© 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.