Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Spatial-Shader
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.
Render-Modi
For visual examples of these render modes, see Standard Material 3D and ORM Material 3D.
Rendermodus |
Beschreibung |
|---|---|
blend_mix |
Mix-Blending-Modus (Alpha ist Transparenz), Default. |
blend_add |
Additiver Blending-Modus. |
blend_sub |
Subtraktiver Blending-Modus. |
blend_mul |
Multiplikativer Blending-Modus. |
blend_premul_alpha |
Premultiplied alpha blend mode (fully transparent = add, fully opaque = mix). |
depth_draw_opaque |
Tiefe nur für undurchsichtige Geometrie (nicht transparent) zeichnen. |
depth_draw_always |
Tiefe immer zeichnen (undurchsichtig und transparent). |
depth_draw_never |
Tiefe niemals zeichnen. |
depth_prepass_alpha |
Für transparente Geometrie einen undurchsichtig-Tiefenvorlauf ausführen. |
depth_test_disabled |
Tiefenprüfung Deaktivieren. |
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 |
Backface-Culling durchführen (Default). |
cull_front |
Frontface-Culling durchführen. |
cull_disabled |
Culling deaktiviert (beidseitig). |
unshaded |
Result is just albedo. No lighting/shading happens in material, making it faster to render. |
wireframe |
Geometry draws using lines (useful for troubleshooting).
When using the Compatibility renderer, you must call
|
debug_shadow_splits |
Directional shadows are drawn using different colors for each split (useful for troubleshooting). |
diffuse_burley |
Burley (Disney PBS) für diffuses Licht (Default). |
diffuse_lambert |
Lambert-Schattierung für diffuses Licht. |
diffuse_lambert_wrap |
Lambert-wrap shading (roughness-dependent) for diffuse. |
diffuse_toon |
Toon-Shading für diffuses Licht. |
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 |
skip_vertex_transform |
|
world_vertex_coords |
|
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 |
Deaktivieren des Beitrags von Umgebungslicht und der Radiance Map. |
shadow_to_opacity |
Durch die Beleuchtung wird das Alpha so geändert, dass schattierte Bereiche undurchsichtig und nicht schattierte Bereiche transparent sind. Nützlich zum Überlagern von Schatten auf einen Kamera-Feed in 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 |
Alpha-Antialiasing-Modus, siehe hier für mehr. |
alpha_to_coverage_and_one |
Alpha-Antialiasing-Modus, siehe hier für mehr. |
fog_disabled |
Disable receiving depth-based or volumetric fog. Useful for |
Stencil modes
Bemerkung
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.
Bemerkung
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 |
Beschreibung |
|---|---|
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. |
Built-ins
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.
Globale Built-ins
Globale Built-ins sind überall verfügbar, einschließlich benutzerdefinierter Funktionen.
Built-in |
Beschreibung |
|---|---|
in float TIME |
Global time since the engine has started, in seconds. It repeats after every |
in float PI |
A |
in float TAU |
A |
in float E |
An |
in bool OUTPUT_IS_SRGB |
|
in float CLIP_SPACE_FAR |
Clip space far |
in bool IS_MULTIVIEW |
|
in bool IN_SHADOW_PASS |
|
Vertex-Built-ins
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.
Benutzer können die Built-in-Modellansichtstransformation deaktivieren (die Projektion wird später immer noch durchgeführt) und sie mit dem folgenden Code manuell durchführen:
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.
Der Benutzer kann die Modellansicht und die Projektionstransformationen mit Hilfe der eingebauten POSITION überschreiben. Wenn POSITION irgendwo in den Shader geschrieben wird, wird es immer benutzt, so dass der Benutzer dafür verantwortlich ist, dass es immer einen akzeptablen Wert hat. Wenn POSITION verwendet wird, wird der Wert von VERTEX ignoriert und es findet keine Projektion statt. Der Wert, der an den Fragment-Shader übergeben wird, stammt jedoch immer noch von VERTEX.
For instancing, the INSTANCE_CUSTOM variable contains the instance custom data. When using particles, this information
is usually:
x: Rotationswinkel in Bogenmaß.
y: Phase during lifetime (
0.0to1.0).z: Animations-Frame.
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.
Built-in |
Beschreibung |
|---|---|
in vec2 VIEWPORT_SIZE |
Größe des Viewports (in Pixeln). |
in mat4 VIEW_MATRIX |
Transformation von World-Space nach View-Space. |
in mat4 INV_VIEW_MATRIX |
Transformation von View-Space nach World-Space. |
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 |
Transformation von Clip-Space nach View-Space. |
in vec3 NODE_POSITION_WORLD |
Node-Position im World-Space. |
in vec3 NODE_POSITION_VIEW |
Node-Position im 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 |
Kamera-Richtung im World-Space. |
in uint CAMERA_VISIBLE_LAYERS |
Ebenen der Kamera beim Rendern des aktuellen Durchlaufs cullen. |
in int INSTANCE_ID |
Instanz-ID zum Instanziieren. |
in vec4 INSTANCE_CUSTOM |
Benutzerdefinierte Instanzdaten (meistens für Partikel). |
in int VIEW_INDEX |
Die Ansicht, die gerendert wird. |
in int VIEW_MONO_LEFT |
Konstante für Mono oder linkes Auge, immer |
in int VIEW_RIGHT |
Konstante für das rechte Auge, immer |
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 |
in int VERTEX_ID |
Der Index des aktuellen Vertex im Vertex-Puffer. |
inout vec3 NORMAL |
Normal in model space.
In world space if |
inout vec3 TANGENT |
Tangent in model space.
In world space if |
inout vec3 BINORMAL |
Binormal in model space.
In world space if |
out vec4 POSITION |
If written to on any branch, overrides final vertex position in clip space. |
inout vec2 UV |
UV Hauptkanal. |
inout vec2 UV2 |
UV Sekundärkanal. |
inout vec4 COLOR |
Color from vertices. Limited to values between |
out float ROUGHNESS |
Rauheit für Vertex-Beleuchtung. |
inout float POINT_SIZE |
Punktgröße für Punkt-Rendering. |
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 |
Transformation von View-Space nach Clip-Space. |
in uvec4 BONE_INDICES |
|
in vec4 BONE_WEIGHTS |
|
in vec4 CUSTOM0 |
Custom value from vertex primitive. When using extra
UVs, |
in vec4 CUSTOM1 |
Custom value from vertex primitive. When using extra
UVs, |
in vec4 CUSTOM2 |
Custom value from vertex primitive. When using extra
UVs, |
in vec4 CUSTOM3 |
Benutzerdefinierter Wert vom Scheitelpunktprimitiv. |
out float Z_CLIP_SCALE |
If written to on any branch, 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 |
Bemerkung
MODELVIEW_MATRIX kombiniert sowohl MODEL_MATRIX als auch VIEW_MATRIX und ist besser geeignet, wenn Float-Probleme auftreten können. Wenn zum Beispiel das Objekt sehr weit vom Weltursprung entfernt ist, kann es bei der Verwendung des getrennten MODEL_MATRIX und VIEW_MATRIX zu Float-Problemen kommen.
Bemerkung
INV_VIEW_MATRIX ist die Matrix, die zum Rendern des Objekts in diesem Durchgang verwendet wird, nicht wie MAIN_CAM_INV_VIEW_MATRIX, welche die Matrix der Kamera in der Szene ist. Im Schattendurchgang basiert die Ansicht von INV_VIEW_MATRIX auf der Kamera, die sich an der Position des Lichts befindet.
Fragment-Built-ins
Die Standardverwendung einer Godot-Fragmentprozessorfunktion besteht darin, die Materialeigenschaften Ihres Objekts einzurichten und den Built-in-Renderer die endgültige Schattierung vornehmen zu lassen. Sie müssen jedoch nicht alle diese Propertys verwenden, und wenn Sie sie nicht befüllen, wird Godot die entsprechenden Funktionalitäten wegoptimieren.
Built-in |
Beschreibung |
|---|---|
in vec2 VIEWPORT_SIZE |
Größe des Viewports (in Pixeln). |
in vec4 FRAGCOORD |
Coordinate of pixel center in screen space. |
in bool FRONT_FACING |
|
in vec3 VIEW |
Normalisierter Vektor von der Fragmentposition zur Kamera (im View-Space). Dies gilt sowohl für perspektivische als auch für orthogonale Kameras. |
in vec2 UV |
UV that comes from the |
in vec2 UV2 |
UV2 that comes from the |
in vec4 COLOR |
COLOR that comes from the |
in vec2 POINT_COORD |
Point coordinate for drawing points with |
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 |
in mat4 VIEW_MATRIX |
Transformation von World-Space nach View-Space. |
in mat4 INV_VIEW_MATRIX |
Transformation von View-Space nach World-Space. |
in mat4 PROJECTION_MATRIX |
Transformation von View-Space nach Clip-Space. |
in mat4 INV_PROJECTION_MATRIX |
Transformation von Clip-Space nach View-Space. |
in vec3 NODE_POSITION_WORLD |
Node-Position im World-Space. |
in vec3 NODE_POSITION_VIEW |
Node-Position im 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 |
Kamera-Richtung im World-Space. |
in uint CAMERA_VISIBLE_LAYERS |
Ebenen der Kamera beim Rendern des aktuellen Durchlaufs cullen. |
in vec3 VERTEX |
Position of the fragment (pixel), in view space. It is the |
inout vec3 LIGHT_VERTEX |
Eine beschreibbare Version von |
in int VIEW_INDEX |
The view that we are rendering. Used to distinguish between views in multiview/stereo rendering.
|
in int VIEW_MONO_LEFT |
Konstante für Mono oder linkes Auge, immer |
in int VIEW_RIGHT |
Konstante für das rechte Auge, immer |
in vec3 EYE_OFFSET |
Position offset for the eye being rendered, in view space. Only applicable for multiview rendering. |
sampler2D SCREEN_TEXTURE |
Entfernt in Godot 4. Verwenden Sie stattdessen ein |
in vec2 SCREEN_UV |
Screen UV coordinate for the current pixel. |
sampler2D DEPTH_TEXTURE |
Entfernt in Godot 4. Verwenden Sie stattdessen ein |
out float DEPTH |
Custom depth value (range |
inout vec3 NORMAL |
Normal that comes from the |
inout vec3 TANGENT |
Tangent that comes from the |
inout vec3 BINORMAL |
Binormal that comes from the |
out vec3 NORMAL_MAP |
Set normal here in tangent space if reading normal from a texture instead of |
out float NORMAL_MAP_DEPTH |
Depth from |
out vec3 BENT_NORMAL_MAP |
Set bent normal map here in tangent space to enable bent normals. This is used to improve specular occlusion, and requires a specially authored bent normal map. The blue channel is ignored, as it's reconstructed in the engine instead. This allows bent normal maps with RGTC compression to work. |
out vec3 ALBEDO |
Albedo (default white). Base color. |
out float ALPHA |
Alpha (range |
out float ALPHA_SCISSOR_THRESHOLD |
If written to on any branch, values below a certain amount of alpha are discarded. |
out float ALPHA_HASH_SCALE |
Alpha hash scale when using the alpha hash transparency mode. Defaults to |
out float ALPHA_ANTIALIASING_EDGE |
The threshold below which alpha to coverage antialiasing should be used. Defaults to |
out vec2 ALPHA_TEXTURE_COORDINATE |
The texture coordinate to use for alpha-to-coverge antialiasing. Requires the
|
out float PREMUL_ALPHA_FACTOR |
Premultiplied alpha factor. Only effective if |
out float METALLIC |
Metallic (range |
out float SPECULAR |
Specular (not physically accurate to change). Defaults to |
out float ROUGHNESS |
Roughness (range |
out float RIM |
Rim (range |
out float RIM_TINT |
Rim Tint, range from |
out float CLEARCOAT |
Small specular blob added on top of the existing one. If used, Godot calculates clearcoat. |
out float CLEARCOAT_GLOSS |
Gloss of clearcoat. If used, Godot calculates clearcoat. |
out float ANISOTROPY |
Zum Verzerren des Spiegelkleckses entsprechend des Tangentenraums. |
out vec2 ANISOTROPY_FLOW |
Verzerrungsrichtung, mit Flowmaps verwenden. |
out float 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 |
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 float AO |
Strength of ambient occlusion. For use with pre-baked AO. |
out float AO_LIGHT_AFFECT |
How much ambient occlusion affects direct light (range |
out vec3 EMISSION |
Emission color (can go over |
out vec4 FOG |
If written to on any branch, blends final pixel color with |
out vec4 RADIANCE |
If written to on any branch, blends environment map radiance with |
out vec4 IRRADIANCE |
If written to on any branch, blends environment map irradiance with |
Bemerkung
Shader, welche die transparente Pipeline durchlaufen, wenn in ALPHA geschrieben wird, können Probleme mit der Transparenzsortierung aufweisen. Lesen Sie den Abschnitt Transparenzsortierung in der "3D-Rendering-Beschränkungen"-Seite für weitere Informationen und Möglichkeiten zur Vermeidung von Problemen.
Licht-Built-ins
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() {
if (LIGHT_IS_AREA) {
// Area light GGX shading.
DIFFUSE_LIGHT += LIGHT_AREA_DIFFUSE_MULTIPLIER * ATTENUATION * LIGHT_COLOR;
SPECULAR_LIGHT += LIGHT_AREA_SPECULAR_MULTIPLIER * ATTENUATION * LIGHT_COLOR * SPECULAR_AMOUNT;
} else {
// Used for all other light types (directional, omni, spot).
DIFFUSE_LIGHT += clamp(dot(NORMAL, LIGHT), 0.0, 1.0) * ATTENUATION * LIGHT_COLOR / PI;
}
}
Wenn mehrere Lichter addiert werden sollen, fügen Sie den Lichtanteil zu DIFFUSE_LIGHT mittels += hinzu, anstatt ihn zu überschreiben.
Warnung
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.)
Built-in |
Beschreibung |
|---|---|
in vec2 VIEWPORT_SIZE |
Größe des Viewports (in Pixeln). |
in vec4 FRAGCOORD |
Coordinate of pixel center in screen space. |
in mat4 MODEL_MATRIX |
Model/local space to world space transform. |
in mat4 INV_VIEW_MATRIX |
Transformation von View-Space nach World-Space. |
in mat4 VIEW_MATRIX |
Transformation von World-Space nach View-Space. |
in mat4 PROJECTION_MATRIX |
Transformation von View-Space nach Clip-Space. |
in mat4 INV_PROJECTION_MATRIX |
Transformation von Clip-Space nach View-Space. |
in vec3 NORMAL |
Normalvektor im View-Space. |
in vec2 SCREEN_UV |
Screen UV coordinate for the current pixel. |
in vec2 UV |
UV that comes from the |
in vec2 UV2 |
UV2 that comes from the |
in vec3 VIEW |
View-Vektor im View-Space. |
in vec3 LIGHT |
Light vector, in view space. |
in vec3 LIGHT_COLOR |
Light color multiplied by
light energy multiplied by
|
in float SPECULAR_AMOUNT |
For OmniLight3D and SpotLight3D,
|
in bool LIGHT_IS_DIRECTIONAL |
|
in float ATTENUATION |
Dämpfung basierend auf Entfernung oder Schatten. |
in vec3 ALBEDO |
Basis-Albedo. |
in vec3 BACKLIGHT |
|
in float METALLIC |
Metallisch. |
in float ROUGHNESS |
Rauheit. |
out vec3 DIFFUSE_LIGHT |
Diffuses Licht-Ergebnis. |
out vec3 SPECULAR_LIGHT |
Specular Licht-Ergebnis. |
out float ALPHA |
Alpha (range |
Bemerkung
Shader, welche die transparente Pipeline durchlaufen, wenn in ALPHA geschrieben wird, können Probleme mit der Transparenzsortierung aufweisen. Lesen Sie den Abschnitt Transparenzsortierung in der "3D-Rendering-Beschränkungen"-Seite für weitere Informationen und Möglichkeiten zur Vermeidung von Problemen.
Transparente Materialien können auch keine Schatten werfen oder in hint_screen_texture und hint_depth_texture Uniforms erscheinen. Dies wiederum verhindert, dass diese Materialien in Screen-Space-Reflexionen oder Brechung erscheinen. SDFGI scharfe Reflexionen sind auf transparenten Materialien nicht sichtbar (nur grobe Reflexionen sind auf transparenten Materialien sichtbar).