Шейдеры Spatial

Пространственные шейдеры используются для затенения 3D-объектов. Это самый сложный тип шейдеров, который предлагает Godot. Пространственные шейдеры очень хорошо настраиваются, в них можно использовать различные режимы рендеринга и различные опции рендеринга (например, Subsurface Scattering, Transmission, Ambient Occlusion, Rim lighting и т. д.). Пользователи могут писать функции вершинного, фрагментного и светового процессоров, чтобы влиять на отрисовку объектов.

Режимы визуализации

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

Режим рендеринга	Описание
blеnd_mix	Режим смешивания (альфа как прозрачность), по умолчанию.
blеnd_add	Аддитивный режим наложения.
blеnd_sub	Режим наложения с вычитанием.
blеnd_mul	Режим наложения с умножением.
blеnd_premul_alpha	Premultiplied alpha blend mode (fully transparent = add, fully opaque = mix).
dеpth_draw_opaque	Прорисовка глубины только для непрозрачной геометрии.
dеpth_draw_always	Постоянная отрисовка глубины (непрозрачная и прозрачная).
dеpth_draw_never	Никогда не отрисовывать глубину.
depth_prepass_alpha	Выполнение предварительного прохождения непрозрачной глубины для прозрачной геометрии.
depth_test_disabled	Отключение проверки глубины.
sss_mode_skin	Subsurface Scattering mode for skin (optimizes visuals for human skin, e.g. boosted red channel).
cull_baсk	Обрезка задних поверхностей (по-умолчанию).
cull_frоnt	Обрезка передних поверхностей.
cull_disablеd	Выключение обрезки (двойная сторона).
unshadеd	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_burleу	Burley (Disney PBS) для диффузного (по умолчанию).
diffusе_lambert	Затенение Ламберта для диффузии.
diffusе_lambert_wrap	Lambert-wrap shading (roughness-dependent) for diffuse.
diffuse_toоn	Toon-затенение для диффузного.
specular_schlick_ggх	Schlick-GGX for direct light specular lobes (default).
spеcular_toon	Toon for direct light specular lobes.
speculаr_disabled	Disable direct light specular lobes. Doesn't affect reflected light (use SPECULAR = 0.0 instead).
skіp_vertex_transform	VERTEX, NORMAL, TANGENT, and BITANGENT need to be transformed manually in the vertex() function.
wоrld_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.
Свет_окружения_отключен	Disable contribution from ambient light and radiance map.
Тень_непрозрачна	Освещение изменяет альфа-канал так, что затененные области становятся непрозрачными, а незатененные - прозрачными. Полезно для наложения теней на камеру в AR.
vеrtex_lighting	Use vertex-based lighting instead of per-pixel lighting.
particle_trails	Enables the trails when used on particles geometry.
alpha_to_coverage	Alpha antialiasing mode, see here for more.
alpha_to_coverage_and_one	Alpha antialiasing mode, see here for more.
fog_disabled	Disable receiving depth-based or volumetric fog. Useful for blend_add materials like particles.

Встроенные функции

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.

Глобальные встроенные функции

Глобальные встроенные модули доступны везде, включая пользовательские функции.

Встроенный	Описание
in float 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). A ratio of a circle's circumference to its diameter and amount of radians in half turn.
in float TAU	Константа TAU (6.283185). Эквивалент PI * 2 и количество радианов в полном обороте.
in float E	An E constant (2.718281). Euler's number and a base of the natural logarithm.
in bool OUTPUT_IS_SRGB	true when output is in sRGB color space (this is true in the Compatibility renderer, false in Forward+ and Mobile).
in float CLIP_SPACE_FAR	Clip space far z value. In the Forward+ or Mobile renderers, it's 0.0. In the Compatibility renderer, it's -1.0.

Вершинные встроенные константы

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.

Пользователи могут отключить встроенное преобразование modelview (проекция всё равно произойдет позже) и сделать это вручную с помощью следующего кода:

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: Угол поворота в радианах.

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

• z: Кадр анимации.

Это позволяет легко настроить шейдер на систему частиц, использующую материал частиц по умолчанию. При написании собственного шейдера частиц это значение можно использовать по своему усмотрению.

Встроенный	Описание
in vec2 VIEWPORT_SIZE	Размер области просмотра (в пикселях).
in mat4 VIEW_MATRIX	Мировое пространство для просмотра трансформации пространства.
in mat4 INV_VIEW_MATRIX	View space to world space transform.
in mat4 MAIN_CAM_INV_VIEW_MATRIX	View space to world space transform of camera used to draw the current viewport.
in mat4 INV_PROJECTION_MATRIX	Clip space to view space transform.
in vec3 NODE_POSITION_WORLD	Положение узла в мировом пространстве.
in vec3 NODE_POSITION_VIEW	Положение узла в пространстве обзора.
in vec3 CAMERA_POSITION_WORLD	Положение камеры в мировом пространстве.
in vec3 CAMERA_DIRECTION_WORLD	Направление камеры в мировом пространстве.
in uint CAMERA_VISIBLE_LAYERS	Cull layers of the camera rendering the current pass.
in int INSTANCE_ID	Instance ID for instancing.
in vec4 INSTANCE_CUSTOM	Instance custom data (for particles, mostly).
in int VIEW_INDEX	Вид, который мы рендерим. VIEW_MONO_LEFT (0) для Mono (не мультиракурс) или левого глаза, VIEW_RIGHT (1) для правого глаза.
in int VIEW_MONO_LEFT	Постоянная для Mono или левого глаза, всегда 0.
in int VIEW_RIGHT	Константа для правого глаза, всегда 1.
in vec3 EYE_OFFSET	Смещение позиции для отрисовываемого глаза. Применяется только для многоракурсного рендеринга.
inout vec3 VERTEX	Position of the vertex, in model space. In world space if world_vertex_coords is used.
in int VERTEX_ID	Индекс текущей вершины в буфере вершин.
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	UV main channel.
inout vec2 UV2	UV secondary channel.
inout vec4 COLOR	Цвет из вершин.
out float ROUGHNESS	Шероховатость для вершинного освещения.
inout float POINT_SIZE	Размер точки для рендеринга точек.
inout mat4 MODELVIEW_MATRIX	Model/local space to view space transform (use if possible).
inout mat3 MODELVIEW_NORMAL_MATRIX
mat4 MODEL_MATRIX	Model/local space to world space transform.
mat3 MODEL_NORMAL_MATRIX
inout mat4 PROJECTION_MATRIX	Преобразование пространства просмотра для обрезки пространства.
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.

Примечание

MODELVIEW_MATRIX объединяет в себе MODEL_MATRIX и VIEW_MATRIX и лучше подходит для тех случаев, когда могут возникнуть проблемы с плавающей точкой. Например, если объект находится очень далеко от начала мира, то при использовании раздельных MODEL_MATRIX и VIEW_MATRIX могут возникнуть проблемы с плавающей точкой.

Примечание

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.

Фрагментные встроенные константы

По умолчанию функция обработчика фрагментов Godot используется для настройки свойств материала вашего объекта и для того, чтобы встроенный рендерер выполнил финальное затенение. Однако вы не обязаны использовать все эти свойства, и если вы не будете записывать в них, Godot оптимизирует соответствующую функциональность.

Встроенный	Описание
in vec2 VIEWPORT_SIZE	Размер области просмотра (в пикселях).
vec4 FRAGCOORD	Coordinate of pixel center in screen space. xy specifies position in window. Origin is lower left. z specifies fragment depth. It is also used as the output value for the fragment depth unless DEPTH is written to.
bool FRONT_FACING	true if current face is front facing, false otherwise.
vec3 VIEW	Normalized vector from fragment position to camera (in view space). This is the same for both perspective and orthogonal cameras.
vec2 UV	UV that comes from the vertex() function.
vec2 UV2	UV2 that comes from the vertex() function.
vec4 COLOR	COLOR that comes from the vertex() function.
vec2 POINT_COORD	Point coordinate for drawing points with POINT_SIZE.
mat4 MODEL_MATRIX	Model/local space to world space transform.
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	Мировое пространство для просмотра трансформации пространства.
in mat4 INV_VIEW_MATRIX	View space to world space transform.
mat4 PROJECTION_MATRIX	Преобразование пространства просмотра для обрезки пространства.
in mat4 INV_PROJECTION_MATRIX	Clip space to view space transform.
in vec3 NODE_POSITION_WORLD	Положение узла в мировом пространстве.
in vec3 NODE_POSITION_VIEW	Положение узла в пространстве обзора.
in vec3 CAMERA_POSITION_WORLD	Положение камеры в мировом пространстве.
in vec3 CAMERA_DIRECTION_WORLD	Направление камеры в мировом пространстве.
in uint CAMERA_VISIBLE_LAYERS	Cull layers of the camera rendering the current pass.
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	Постоянная для Mono или левого глаза, всегда 0.
in int VIEW_RIGHT	Константа для правого глаза, всегда 1.
in vec3 EYE_OFFSET	Смещение позиции для отрисовываемого глаза. Применяется только для многоракурсного рендеринга.
sampler2D SCREEN_TEXTURE	Убрано в Godot 4. Вместо этого используйте sampler2D с hint_screen_texture.
vec2 SCREEN_UV	Экранная UV-координата для текущего пикселя.
sampler2D DEPTH_TEXTURE	Убрано в Godot 4. Вместо этого используйте sampler2D` с ``hint_depth_texture.
out float DEPTH	Custom depth value (range of [0.0, 1.0]). If DEPTH is being written to in any shader branch, then you are responsible for setting the 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 float ALPHA	Alpha (range of [0.0, 1.0]). If read from or written to, the material will go to the transparent pipeline.
out float ALPHA_SCISSOR_THRESHOLD	При записи значения ниже определенного количества альфа отбрасываются.
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 of [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 of [0.0, 1.0]).
out float RIM	Rim (range of [0.0, 1.0]). If used, Godot calculates rim lighting. Rim size depends on ROUGHNESS.
out float RIM_TINT	Rim Tint, range of 0.0 (white) to 1.0 (albedo). If used, Godot calculates rim lighting.
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	For distorting the specular blob according to tangent space.
out vec2 ANISOTROPY_FLOW	Направление искажения, используйте с flowmaps.
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 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 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 of [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.

Примечание

Шейдеры, проходящие через конвейер прозрачности при записи ALPHA, могут иметь проблемы с сортировкой прозрачности. Прочитайте раздел сортировка прозрачности на странице ограничений 3D-рендеринга для получения дополнительной информации и способов избежать проблем.

Встроенные константы шейдеров света

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;
}

Если вы хотите, чтобы освещение суммировалось, добавьте вклад освещения в DIFFUSE_LIGHT, используя +=, а не перезаписывайте его.

Предупреждение

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.)

Встроенный	Описание
in vec2 VIEWPORT_SIZE	Размер области просмотра (в пикселях).
vec4 FRAGCOORD	Координата центра пикселя в пространстве экрана. xy задаёт позицию в окне, z задает глубину фрагмента, если DEPTH не используется. Ориентир - левый нижний угол.
mat4 MODEL_MATRIX	Model/local space to world space transform.
in mat4 INV_VIEW_MATRIX	View space to world space transform.
in mat4 VIEW_MATRIX	Мировое пространство для просмотра трансформации пространства.
mat4 PROJECTION_MATRIX	Преобразование пространства просмотра для обрезки пространства.
in mat4 INV_PROJECTION_MATRIX	Clip space to view space transform.
in vec3 NORMAL	Normal vector, in view space.
vec2 SCREEN_UV	Экранная UV-координата для текущего пикселя.
vec2 UV	UV that comes from the vertex() function.
vec2 UV2	UV2 that comes from the vertex() function.
vec3 VIEW	View vector, in view space.
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	Attenuation based on distance or shadow.
in vec3 ALBEDO	Base albedo.
in vec3 BACKLIGHT
in float METALLIC	Metallic.
in float ROUGHNESS	Шероховатость.
out vec3 DIFFUSE_LIGHT	Diffuse light result.
out vec3 SPECULAR_LIGHT	Specular light result.
out float ALPHA	Alpha (range of [0.0, 1.0]). If written to, the material will go to the transparent pipeline.

Примечание

Шейдеры, проходящие через конвейер прозрачности при записи ALPHA, могут иметь проблемы с сортировкой прозрачности. Прочитайте раздел сортировка прозрачности на странице ограничений 3D-рендеринга для получения дополнительной информации и способов избежать проблем.

Прозрачные материалы также не могут отбрасывать тени или появляться в uniform-переменных hint_screen_texture и hint_depth_texture. Это, в свою очередь, не позволяет этим материалам появляться в отражениях или преломлениях в экранном пространстве. SDFGI резкие отражения не видны на прозрачных материалах (на прозрачных материалах видны только грубые отражения).