Shaders espaciales

Spatial shaders are used for shading 3D objects. They are the most complex type of shader Godot offers. Spatial shaders are highly configurable with different render modes and different rendering options (e.g. Subsurface Scattering, Transmission, Ambient Occlusion, Rim lighting, etc.). Users can optionally write vertex, fragment, and light processor functions to affect how objects are drawn.

Modos de renderizado

For visual examples of these render modes, see Standard Material 3D and ORM Material 3D.

Modo de renderizado	Descripción
blend_mix	Modo de blending por mezcla (alfa es transparencia), es el modo por defecto.
blend_add	Modo de blending aditivo.
blend_sub	Modo de blending substractivo.
blend_mul	Modo de blending multiplicativo.
blend_premul_alpha	Premultiplied alpha blend mode (fully transparent = add, fully opaque = mix).
depth_draw_opaque	Sólo dibuja "depth" para geometría opaca (no transparente).
depth_draw_always	Siempre dibuja "depth" (opaco y transparente).
depth_draw_never	Nunca dibuja depth.
depth_prepass_alpha	Realiza un pre-pass de depth opaco para geometría transparente.
depth_test_disabled	Desactiva testing de depth.
depth_test_default	Depth test will discard the pixel if it is behind other pixels. In Forward+ only, the pixel is also discarded if it's at the exact same depth as another pixel.
depth_test_inverted	Depth test will discard the pixel if it is in front of other pixels. Useful for stencil effects.
sss_mode_skin	Subsurface Scattering mode for skin (optimizes visuals for human skin, e.g. boosted red channel).
cull_back	Culling de caras internas (por defecto).
cull_front	Culling de caras frontales.
cull_disabled	Culling deshabilitado (doble cara).
unshaded	Result is just albedo. No lighting/shading happens in material, making it faster to render.
wireframe	Geometry draws using lines (useful for troubleshooting).
debug_shadow_splits	Directional shadows are drawn using different colors for each split (useful for troubleshooting).
diffuse_burley	Burley (Disney PBS) for diffuse (default).
diffuse_lambert	Lambert shading for diffuse.
diffuse_lambert_wrap	Lambert-wrap shading (roughness-dependent) for diffuse.
diffuse_toon	Shading Toon para diffuse.
specular_schlick_ggx	Schlick-GGX for direct light specular lobes (default).
specular_toon	Toon for direct light specular lobes.
specular_disabled	Disable direct light specular lobes. Doesn't affect reflected light (use SPECULAR = 0.0 instead).
skip_vertex_transform	VERTEX, NORMAL, TANGENT, and BITANGENT need to be transformed manually in the vertex() function.
world_vertex_coords	VERTEX, NORMAL, TANGENT, and BITANGENT are modified in world space instead of model space.
ensure_correct_normals	Use when non-uniform scale is applied to mesh (note: currently unimplemented).
shadows_disabled	Disable computing shadows in shader. The shader will not receive shadows, but can still cast them.
ambient_light_disabled	Deshabilitar la contribución de la luz ambiental y el mapa de radiaciones.
shadow_to_opacity	La iluminación modifica el alfa para que las áreas sombreadas sean opacas y las no sombreadas sean transparentes. Útil para superponer sombras a una cámara en AR.
vertex_lighting	Use vertex-based lighting instead of per-pixel lighting.
particle_trails	Enables the trails when used on particle geometry.
alpha_to_coverage	Modo Alpha antialiasing, ver aquí para más detalles.
alpha_to_coverage_and_one	Modo Alpha antialiasing, ver aquí para más detalles.
fog_disabled	Disable receiving depth-based or volumetric fog. Useful for blend_add materials like particles.

Stencil modes

Nota

Stencil support is experimental, use at your own risk. We will try to not break compatibility as much as possible, but if significant flaws are found in the API, it may change in the next minor version.

Stencil operations are a set of operations that allow writing to an efficient buffer in an hardware-accelerated manner. This is generally used to mask in or out parts of the scene.

Some of the most well-known uses are:

• Outlines: Mask out the inner mesh that is being outlined to avoid inner outlines.

• X-Ray: Display a mesh behind other objects.

• Portals: Draw geometry that is normally "impossible" (non-Euclidian) by masking objects.

Nota

You can only read from the stencil buffer in the transparent pass. Any attempt to read in the opaque pass will fail, as it's currently not supported behavior.

Note that for compositor effects, the main renderer's stencil buffer can't be copied to a custom texture.

Stencil mode	Descripción
read	Read from the stencil buffer.
write	Write reference value to the stencil buffer.
write_if_depth_fail	Write reference value to the stencil buffer if the depth test fails.
compare_always	Always pass stencil test.
compare_equal	Pass stencil test if the reference value is equal to the stencil buffer value.
compare_not_equal	Pass stencil test if the reference value is not equal to the stencil buffer value.
compare_less	Pass stencil test if the reference value is less than the stencil buffer value.
compare_less_or_equal	Pass stencil test if the reference value is less than or equal to the stencil buffer value.
compare_greater	Pass stencil test if the reference value is greater than the stencil buffer value.
compare_greater_or_equal	Pass stencil test if the reference value is greater than or equal to the stencil buffer value.

Funciones propias

Values marked as in are read-only. Values marked as out can optionally be written to and will not necessarily contain sensible values. Values marked as inout provide a sensible default value, and can optionally be written to. Samplers cannot be written to so they are not marked.

Not all built-ins are available in all processing functions. To access a vertex built-in from the fragment() function, you can use a varying. The same applies for accessing fragment built-ins from the light() function.

Funciones incorporadas globales

Las internas globales están disponibles en todas partes, incluyendo las funciones personalizadas.

Integrado	Descripción
en real TIME	Global time since the engine has started, in seconds. It repeats after every 3,600 seconds (which can be changed with the rollover setting). It's affected by time_scale but not by pausing. If you need a TIME variable that is not affected by time scale, add your own global shader uniform and update it each frame.
in float PI	A PI constant (3.141592). The ratio of a circle's circumference to its diameter and the number of radians in a half turn.
in float TAU	A TAU constant (6.283185). Equivalent to PI * 2 and the number of radians in a full turn.
in float E	An E constant (2.718281). Euler's number, the base of the natural logarithm.
in booleano OUTPUT_IS_SRGB	true cuando la salida está en el espacio de color sRGB (esto es true en el renderizador Compatibility, y false en Forward+ y Mobile).
in float CLIP_SPACE_FAR	Espacio de recorte hasta el valor z. En los renderizadores Forward+ o Mobile, es 0.0. En el renderizador Compatibility, es -1.0.

Incorporados en Vertex

Vertex data (VERTEX, NORMAL, TANGENT, and BITANGENT) are presented in model space (also called local space). If not written to, these values will not be modified and be passed through as they came, then transformed into view space to be used in fragment().

They can optionally be presented in world space by using the world_vertex_coords render mode.

Los usuarios pueden desactivar la transformada incorporada de modelview (la proyección seguirá sucediendo más tarde) y hacerlo manualmente con el siguiente código:

shader_type spatial;
render_mode skip_vertex_transform;

void vertex() {
    VERTEX = (MODELVIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
    NORMAL = normalize((MODELVIEW_MATRIX * vec4(NORMAL, 0.0)).xyz);
    BINORMAL = normalize((MODELVIEW_MATRIX * vec4(BINORMAL, 0.0)).xyz);
    TANGENT = normalize((MODELVIEW_MATRIX * vec4(TANGENT, 0.0)).xyz);
}

Other built-ins, such as UV, UV2, and COLOR, are also passed through to the fragment() function if not modified.

Users can override the modelview and projection transforms using the POSITION built-in. If POSITION is written to anywhere in the shader, it will always be used, so the user becomes responsible for ensuring that it always has an acceptable value. When POSITION is used, the value from VERTEX is ignored and projection does not happen. However, the value passed to the fragment shader still comes from VERTEX.

For instancing, the INSTANCE_CUSTOM variable contains the instance custom data. When using particles, this information is usually:

• x: Ángulo de rotación en radianes.

• y: Phase during lifetime (0.0 to 1.0).

• z: Fotograma de animación.

This allows you to easily adjust the shader to a particle system using default particle material. When writing a custom particle shader, this value can be used as desired.

Integrado	Descripción
en vec2 VIEWPORT_SIZE	Tamaño del viewport (en píxeles).
in mat4 VIEW_MATRIX	El espacio mundial para ver la transformada del espacio.
in mat4 INV_VIEW_MATRIX	Transform de espacio de vista a espacio de mundo.
in mat4 MAIN_CAM_INV_VIEW_MATRIX	View space to world space transform of the camera used to draw the current viewport.
in mat4 INV_PROJECTION_MATRIX	Recortar el espacio para ver la transformada del espacio.
in vec3 NODE_POSITION_WORLD	Posición del nodo, en el espacio mundial.
in vec3 NODE_POSITION_VIEW	Node position, in view space.
in vec3 CAMERA_POSITION_WORLD	Camera position, in world space. Represents the midpoint of the two eyes when in multiview/stereo rendering.
in vec3 CAMERA_DIRECTION_WORLD	Camera direction, in world space.
in uint CAMERA_VISIBLE_LAYERS	Cull layers of the camera rendering the current pass.
en entero INSTANCE_ID	ID de instancia para el instanciamiento.
in vec4 INSTANCE_CUSTOM	Datos personalizados de la instancia (para las partículas, en su mayoría).
in int VIEW_INDEX	The view that we are rendering. VIEW_MONO_LEFT (0) for Mono (not multiview) or left eye, VIEW_RIGHT (1) for right eye.
in int VIEW_MONO_LEFT	Constant for Mono or left eye, always 0.
in int VIEW_RIGHT	Constant for right eye, always 1.
in vec3 EYE_OFFSET	Position offset for the eye being rendered, in view space. Only applicable for multiview rendering.
inout vec3 VERTEX	Position of the vertex, in model space. In world space if world_vertex_coords is used.
in int VERTEX_ID	The index of the current vertex in the vertex buffer.
inout vec3 NORMAL	Normal in model space. In world space if world_vertex_coords is used.
inout vec3 TANGENT	Tangent in model space. In world space if world_vertex_coords is used.
inout vec3 BINORMAL	Binormal in model space. In world space if world_vertex_coords is used.
out vec4 POSITION	If written to, overrides final vertex position in clip space.
inout vec2 UV	Canal principal de UV.
inout vec2 UV2	Canal secundario UV.
inout vec4 COLOR	Color from vertices. Limited to values between 0.0 and 1.0 for each channel and 8 bits per channel precision (256 possible levels). Alpha channel is supported. Values outside the allowed range are clamped, and values may be rounded due to precision limitations. Use CUSTOM0-CUSTOM3 to pass data with more precision if needed.
out float ROUGHNESS	Rugosidad para la iluminación del vértice.
inout float POINT_SIZE	Tamaño de punto para la representación de puntos.
inout mat4 MODELVIEW_MATRIX	Model/local space to view space transform (use if possible).
inout mat3 MODELVIEW_NORMAL_MATRIX
in mat4 MODEL_MATRIX	Model/local space to world space transform.
in mat3 MODEL_NORMAL_MATRIX
inout mat4 PROJECTION_MATRIX	Ver el espacio para recortar la transformación del espacio.
in uvec4 BONE_INDICES
in vec4 BONE_WEIGHTS
in vec4 CUSTOM0	Custom value from vertex primitive. When using extra UVs, xy is UV3 and zw is UV4.
in vec4 CUSTOM1	Custom value from vertex primitive. When using extra UVs, xy is UV5 and zw is UV6.
in vec4 CUSTOM2	Custom value from vertex primitive. When using extra UVs, xy is UV7 and zw is UV8.
in vec4 CUSTOM3	Custom value from vertex primitive.
out float Z_CLIP_SCALE	If written to, scales the vertex towards the camera to avoid clipping into things like walls. Lighting and shadows will continue to work correctly when this is written to, but screen-space effects like SSAO and SSR may break with lower scales. Try to keep this value as close to 1.0 as possible.

Nota

MODELVIEW_MATRIX combines both the MODEL_MATRIX and VIEW_MATRIX and is better suited when floating point issues may arise. For example, if the object is very far away from the world origin, you may run into floating point issues when using the separated MODEL_MATRIX and VIEW_MATRIX.

Nota

INV_VIEW_MATRIX is the matrix used for rendering the object in that pass, unlike MAIN_CAM_INV_VIEW_MATRIX, which is the matrix of the camera in the scene. In the shadow pass, INV_VIEW_MATRIX's view is based on the camera that is located at the position of the light.

Incorporados en Fragment

El uso por defecto de una función del procesador de fragmentos Godot es configurar las propiedades materiales de su objeto y dejar que el renderizador incorporado se encargue del shader final. Sin embargo, no es necesario que utilices todas estas propiedades, y si no las escribes, Godot optimizará la funcionalidad correspondiente.

Integrado	Descripción
en vec2 VIEWPORT_SIZE	Tamaño del viewport (en píxeles).
in vec4 FRAGCOORD	Coordinate of pixel center in screen space. xy specifies position in window. Origin is upper left. z specifies fragment depth. It is also used as the output value for the fragment depth unless DEPTH is written to.
in booleano FRONT_FACING	true if current face is front facing, false otherwise.
in vec3 VIEW	Normalized vector from fragment position to camera (in view space). This is the same for both perspective and orthogonal cameras.
in vec2 UV	UV that comes from the vertex() function.
in vec2 UV2	UV2 that comes from the vertex() function.
in vec4 COLOR	COLOR that comes from the vertex() function.
in vec2 POINT_COORD	Point coordinate for drawing points with POINT_SIZE.
in mat4 MODEL_MATRIX	Model/local space to world space transform.
in mat3 MODEL_NORMAL_MATRIX	Model/local space to world space transform for normals. This is the same as MODEL_MATRIX by default unless the object is scaled non-uniformly, in which case this is set to transpose(inverse(mat3(MODEL_MATRIX))).
in mat4 VIEW_MATRIX	El espacio mundial para ver la transformada del espacio.
in mat4 INV_VIEW_MATRIX	Transform de espacio de vista a espacio de mundo.
in mat4 PROJECTION_MATRIX	Ver el espacio para recortar la transformación del espacio.
in mat4 INV_PROJECTION_MATRIX	Recortar el espacio para ver la transformada del espacio.
in vec3 NODE_POSITION_WORLD	Posición del nodo, en el espacio mundial.
in vec3 NODE_POSITION_VIEW	Node position, in view space.
in vec3 CAMERA_POSITION_WORLD	Camera position, in world space. Represents the midpoint of the two eyes when in multiview/stereo rendering.
in vec3 CAMERA_DIRECTION_WORLD	Camera direction, in world space.
in uint CAMERA_VISIBLE_LAYERS	Cull layers of the camera rendering the current pass.
in vec3 VERTEX	Position of the fragment (pixel), in view space. It is the VERTEX value from vertex() interpolated between the face's vertices and transformed into view space. If skip_vertex_transform is enabled, it may not be in view space.
inout vec3 LIGHT_VERTEX	A writable version of VERTEX that can be used to alter light and shadows. Writing to this will not change the position of the fragment.
in int VIEW_INDEX	The view that we are rendering. Used to distinguish between views in multiview/stereo rendering. VIEW_MONO_LEFT (0) for Mono (not multiview) or left eye, VIEW_RIGHT (1) for right eye.
in int VIEW_MONO_LEFT	Constant for Mono or left eye, always 0.
in int VIEW_RIGHT	Constant for right eye, always 1.
in vec3 EYE_OFFSET	Position offset for the eye being rendered, in view space. Only applicable for multiview rendering.
sampler2D SCREEN_TEXTURE	Removed in Godot 4. Use a sampler2D with hint_screen_texture instead.
in vec2 SCREEN_UV	Screen UV coordinate for the current pixel.
sampler2D DEPTH_TEXTURE	Removed in Godot 4. Use a sampler2D with hint_depth_texture instead.
out real DEPTH	Custom depth value (range [0.0, 1.0]). If DEPTH is written to in any shader branch, then you are responsible for setting DEPTH for all other branches. Otherwise, the graphics API will leave them uninitialized.
inout vec3 NORMAL	Normal that comes from the vertex() function, in view space. If skip_vertex_transform is enabled, it may not be in view space.
inout vec3 TANGENT	Tangent that comes from the vertex() function, in view space. If skip_vertex_transform is enabled, it may not be in view space.
inout vec3 BINORMAL	Binormal that comes from the vertex() function, in view space. If skip_vertex_transform is enabled, it may not be in view space.
out vec3 NORMAL_MAP	Set normal here if reading normal from a texture instead of NORMAL.
out float NORMAL_MAP_DEPTH	Depth from NORMAL_MAP. Defaults to 1.0.
out vec3 ALBEDO	Albedo (default white). Base color.
out real ALPHA	Alpha (range [0.0, 1.0]). If read from or written to, the material will go to the transparent pipeline.
out float ALPHA_SCISSOR_THRESHOLD	Si se escribe, se descartan los valores inferiores a una cierta cantidad de alfa.
out float ALPHA_HASH_SCALE	Alpha hash scale when using the alpha hash transparency mode. Defaults to 1.0. Higher values result in more visible pixels in the dithering pattern.
out float ALPHA_ANTIALIASING_EDGE	The threshold below which alpha to coverage antialiasing should be used. Defaults to 0.0. Requires the alpha_to_coverage render mode. Should be set to a value lower than ALPHA_SCISSOR_THRESHOLD to be effective.
out vec2 ALPHA_TEXTURE_COORDINATE	The texture coordinate to use for alpha-to-coverge antialiasing. Requires the alpha_to_coverage render mode. Typically set to UV * vec2(albedo_texture_size) where albedo_texture_size is the size of the albedo texture in pixels.
out float PREMUL_ALPHA_FACTOR	Premultiplied alpha factor. Only effective if render_mode blend_premul_alpha; is used. This should be written to when using a shaded material with premultiplied alpha blending for interaction with lighting. This is not required for unshaded materials.
out float METALLIC	Metallic (range [0.0, 1.0]).
out float SPECULAR	Specular (not physically accurate to change). Defaults to 0.5. 0.0 disables reflections.
out float ROUGHNESS	Roughness (range [0.0, 1.0]).
out real RIM	Rim (range [0.0, 1.0]). If used, Godot calculates rim lighting. Rim size depends on ROUGHNESS.
out real RIM_TINT	Rim Tint, range from 0.0 (white) to 1.0 (albedo). If used, Godot calculates rim lighting.
out real CLEARCOAT	Small specular blob added on top of the existing one. If used, Godot calculates clearcoat.
out real CLEARCOAT_GLOSS	Gloss of clearcoat. If used, Godot calculates clearcoat.
out real ANISOTROPY	Para distorsionar la mancha especular según el espacio tangencial.
out vec2 ANISOTROPY_FLOW	Dirección de la distorsión, uso con flowmaps.
out real SSS_STRENGTH	Strength of subsurface scattering. If used, subsurface scattering will be applied to the object.
out vec4 SSS_TRANSMITTANCE_COLOR	Color of subsurface scattering transmittance. If used, subsurface scattering transmittance will be applied to the object.
out float SSS_TRANSMITTANCE_DEPTH	Depth of subsurface scattering transmittance. Higher values allow the effect to reach deeper into the object.
out float SSS_TRANSMITTANCE_BOOST	Boosts the subsurface scattering transmittance if set above 0.0. This makes the effect show up even on directly lit surfaces
inout vec3 BACKLIGHT	Color of backlighting (works like direct light, but it's received even if the normal is slightly facing away from the light). If used, backlighting will be applied to the object. Can be used as a cheaper approximation of subsurface scattering.
out real AO	Strength of ambient occlusion. For use with pre-baked AO.
out real AO_LIGHT_AFFECT	How much ambient occlusion affects direct light (range [0.0, 1.0], default 0.0).
out vec3 EMISSION	Emission color (can go over (1.0, 1.0, 1.0) for HDR).
out vec4 FOG	If written to, blends final pixel color with FOG.rgb based on FOG.a.
out vec4 RADIANCE	If written to, blends environment map radiance with RADIANCE.rgb based on RADIANCE.a.
out vec4 IRRADIANCE	If written to, blends environment map irradiance with IRRADIANCE.rgb based on IRRADIANCE.a.

Nota

Los shaders que pasan por la tubería de transparencia cuando se escribe en ALPHA pueden presentar problemas de ordenación de transparencia. Lee la sección de ordenación de transparencia en la página de limitaciones de renderizado 3D para obtener más información y formas de evitar problemas.

Incorporados en Light

Writing light processor functions is completely optional. You can skip the light() function by using the unshaded render mode. If no light function is written, Godot will use the material properties written to in the fragment() function to calculate the lighting for you (subject to the render mode).

The light() function is called for every light in every pixel. It is called within a loop for each light type.

Below is an example of a custom light() function using a Lambertian lighting model:

void light() {
    DIFFUSE_LIGHT += clamp(dot(NORMAL, LIGHT), 0.0, 1.0) * ATTENUATION * LIGHT_COLOR / PI;
}

Si quieres que las luces se sumen, agrega la contribución de la luz a DIFUSE_LIGHT usando +=, en lugar de sobrescribirla.

Advertencia

The light() function won't be run if the vertex_lighting render mode is enabled, or if Rendering > Quality > Shading > Force Vertex Shading is enabled in the Project Settings. (It's enabled by default on mobile platforms.)

Integrado	Descripción
en vec2 VIEWPORT_SIZE	Tamaño del viewport (en píxeles).
in vec4 FRAGCOORD	La coordenada del centro del píxel en el espacio de la pantalla. xy especifica la posición en la ventana, z especifica la profundidad del fragmento si no se usa DEPTH. El origen es abajo a la izquierda.
in mat4 MODEL_MATRIX	Model/local space to world space transform.
in mat4 INV_VIEW_MATRIX	Transform de espacio de vista a espacio de mundo.
in mat4 VIEW_MATRIX	El espacio mundial para ver la transformada del espacio.
in mat4 PROJECTION_MATRIX	Ver el espacio para recortar la transformación del espacio.
in mat4 INV_PROJECTION_MATRIX	Recortar el espacio para ver la transformada del espacio.
in vec3 NORMAL	Vector normal, en el espacio de visión.
in vec2 SCREEN_UV	Screen UV coordinate for the current pixel.
in vec2 UV	UV that comes from the vertex() function.
in vec2 UV2	UV2 that comes from the vertex() function.
in vec3 VIEW	Vector de vista, en el espacio de vista.
in vec3 LIGHT	Light vector, in view space.
in vec3 LIGHT_COLOR	Light color multiplied by light energy multiplied by PI. The PI multiplication is present because physically-based lighting models include a division by PI.
in float SPECULAR_AMOUNT	For OmniLight3D and SpotLight3D, 2.0 multiplied by light_specular. For DirectionalLight3D, 1.0.
in bool LIGHT_IS_DIRECTIONAL	true if this pass is a DirectionalLight3D.
in float ATTENUATION	Atenuación basada en la distancia o en la sombra.
in vec3 ALBEDO	Albedo de la base.
in vec3 BACKLIGHT
in float METALLIC	Metálico.
in real ROUGHNESS	Rugosidad.
out vec3 DIFFUSE_LIGHT	Resultado de luz difusa.
out vec3 SPECULAR_LIGHT	Resultado de la luz especular.
out real ALPHA	Alpha (range [0.0, 1.0]). If written to, the material will go to the transparent pipeline.

Nota

Los shaders que pasan por la tubería de transparencia cuando se escribe en ALPHA pueden presentar problemas de ordenación de transparencia. Lee la sección de ordenación de transparencia en la página de limitaciones de renderizado 3D para obtener más información y formas de evitar problemas.

Transparent materials also cannot cast shadows or appear in hint_screen_texture and hint_depth_texture uniforms. This in turn prevents those materials from appearing in screen-space reflections or refraction. SDFGI sharp reflections are not visible on transparent materials (only rough reflections are visible on transparent materials).