Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

BaseMaterial3D

继承: Material < Resource < RefCounted < Object

派生: ORMMaterial3D, StandardMaterial3D

用于定义网格 3D 渲染属性的抽象基类。

描述

这个类提供了默认的材质,具有多种渲染功能和属性,无需编写着色器代码。详情见下面的教程。

教程

属性

Color

albedo_color

Color(1, 1, 1, 1)

Texture2D

albedo_texture

bool

albedo_texture_force_srgb

false

bool

albedo_texture_msdf

false

float

alpha_antialiasing_edge

AlphaAntiAliasing

alpha_antialiasing_mode

float

alpha_hash_scale

float

alpha_scissor_threshold

float

anisotropy

0.0

bool

anisotropy_enabled

false

Texture2D

anisotropy_flowmap

bool

ao_enabled

false

float

ao_light_affect

0.0

bool

ao_on_uv2

false

Texture2D

ao_texture

TextureChannel

ao_texture_channel

0

Color

backlight

Color(0, 0, 0, 1)

bool

backlight_enabled

false

Texture2D

backlight_texture

bool

billboard_keep_scale

false

BillboardMode

billboard_mode

0

BlendMode

blend_mode

0

float

clearcoat

1.0

bool

clearcoat_enabled

false

float

clearcoat_roughness

0.5

Texture2D

clearcoat_texture

CullMode

cull_mode

0

DepthDrawMode

depth_draw_mode

0

Texture2D

detail_albedo

BlendMode

detail_blend_mode

0

bool

detail_enabled

false

Texture2D

detail_mask

Texture2D

detail_normal

DetailUV

detail_uv_layer

0

DiffuseMode

diffuse_mode

0

bool

disable_ambient_light

false

bool

disable_fog

false

bool

disable_receive_shadows

false

float

distance_fade_max_distance

10.0

float

distance_fade_min_distance

0.0

DistanceFadeMode

distance_fade_mode

0

Color

emission

Color(0, 0, 0, 1)

bool

emission_enabled

false

float

emission_energy_multiplier

1.0

float

emission_intensity

bool

emission_on_uv2

false

EmissionOperator

emission_operator

0

Texture2D

emission_texture

bool

fixed_size

false

bool

grow

false

float

grow_amount

0.0

bool

heightmap_deep_parallax

false

bool

heightmap_enabled

false

bool

heightmap_flip_binormal

false

bool

heightmap_flip_tangent

false

bool

heightmap_flip_texture

false

int

heightmap_max_layers

int

heightmap_min_layers

float

heightmap_scale

5.0

Texture2D

heightmap_texture

float

metallic

0.0

float

metallic_specular

0.5

Texture2D

metallic_texture

TextureChannel

metallic_texture_channel

0

float

msdf_outline_size

0.0

float

msdf_pixel_range

4.0

bool

no_depth_test

false

bool

normal_enabled

false

float

normal_scale

1.0

Texture2D

normal_texture

Texture2D

orm_texture

int

particles_anim_h_frames

bool

particles_anim_loop

int

particles_anim_v_frames

float

point_size

1.0

float

proximity_fade_distance

1.0

bool

proximity_fade_enabled

false

bool

refraction_enabled

false

float

refraction_scale

0.05

Texture2D

refraction_texture

TextureChannel

refraction_texture_channel

0

float

rim

1.0

bool

rim_enabled

false

Texture2D

rim_texture

float

rim_tint

0.5

float

roughness

1.0

Texture2D

roughness_texture

TextureChannel

roughness_texture_channel

0

ShadingMode

shading_mode

1

bool

shadow_to_opacity

false

SpecularMode

specular_mode

0

bool

subsurf_scatter_enabled

false

bool

subsurf_scatter_skin_mode

false

float

subsurf_scatter_strength

0.0

Texture2D

subsurf_scatter_texture

float

subsurf_scatter_transmittance_boost

0.0

Color

subsurf_scatter_transmittance_color

Color(1, 1, 1, 1)

float

subsurf_scatter_transmittance_depth

0.1

bool

subsurf_scatter_transmittance_enabled

false

Texture2D

subsurf_scatter_transmittance_texture

TextureFilter

texture_filter

3

bool

texture_repeat

true

Transparency

transparency

0

bool

use_particle_trails

false

bool

use_point_size

false

Vector3

uv1_offset

Vector3(0, 0, 0)

Vector3

uv1_scale

Vector3(1, 1, 1)

bool

uv1_triplanar

false

float

uv1_triplanar_sharpness

1.0

bool

uv1_world_triplanar

false

Vector3

uv2_offset

Vector3(0, 0, 0)

Vector3

uv2_scale

Vector3(1, 1, 1)

bool

uv2_triplanar

false

float

uv2_triplanar_sharpness

1.0

bool

uv2_world_triplanar

false

bool

vertex_color_is_srgb

false

bool

vertex_color_use_as_albedo

false

方法

bool

get_feature ( Feature feature ) const

bool

get_flag ( Flags flag ) const

Texture2D

get_texture ( TextureParam param ) const

void

set_feature ( Feature feature, bool enable )

void

set_flag ( Flags flag, bool enable )

void

set_texture ( TextureParam param, Texture2D texture )


枚举

enum TextureParam:

TextureParam TEXTURE_ALBEDO = 0

指定每个像素颜色的纹理。

TextureParam TEXTURE_METALLIC = 1

指定每个像素金属度值的纹理。

TextureParam TEXTURE_ROUGHNESS = 2

指定每个像素粗糙度值的纹理。

TextureParam TEXTURE_EMISSION = 3

指定每个像素自发光颜色的纹理。

TextureParam TEXTURE_NORMAL = 4

指定每个像素法向量的纹理。

TextureParam TEXTURE_RIM = 5

指定每个像素边缘值的纹理。

TextureParam TEXTURE_CLEARCOAT = 6

指定每个像素清漆值的纹理。

TextureParam TEXTURE_FLOWMAP = 7

指定每个像素流图方向的纹理,用于 anisotropy

TextureParam TEXTURE_AMBIENT_OCCLUSION = 8

指定每个像素环境光遮蔽的纹理。

TextureParam TEXTURE_HEIGHTMAP = 9

指定每个像素高度的纹理。

TextureParam TEXTURE_SUBSURFACE_SCATTERING = 10

指定每个像素次表面散射的纹理。

TextureParam TEXTURE_SUBSURFACE_TRANSMITTANCE = 11

指定每个像素用于次表面散射的透射率的纹理。

TextureParam TEXTURE_BACKLIGHT = 12

指定每个像素背光颜色的纹理。

TextureParam TEXTURE_REFRACTION = 13

指定每个像素折射强度的纹理。

TextureParam TEXTURE_DETAIL_MASK = 14

指定每个像素细节蒙版混合值的纹理。

TextureParam TEXTURE_DETAIL_ALBEDO = 15

指定每个像素细节颜色的纹理。

TextureParam TEXTURE_DETAIL_NORMAL = 16

指定每个像素细节法线的纹理。

TextureParam TEXTURE_ORM = 17

保存环境光遮蔽、粗糙度和金属度信息的纹理。

TextureParam TEXTURE_MAX = 18

代表 TextureParam 枚举的大小。


enum TextureFilter:

TextureFilter TEXTURE_FILTER_NEAREST = 0

纹理过滤仅从最近的像素读取。这使得纹理从近距离看是像素化的,从远处看是颗粒状的(由于多级渐远纹理没有被采样)。

TextureFilter TEXTURE_FILTER_LINEAR = 1

纹理过滤在最近的 4 个像素之间进行混合。这使得纹理从近处看起来很平滑,从远处看起来却有颗粒感(由于多级渐远纹理没有被采样)。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 2

纹理过滤从最近的像素读取并在最近的 2 个多级渐远纹理之间进行混合(或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filtertrue,则使用最近的多级渐远纹理)。这使得纹理从近处看起来像素化,从远处看起来平滑。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 3

纹理过滤在最近的 4 个像素和最近的 2 个多级渐远纹理之间进行混合(或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filtertrue,则使用最近的多级渐远纹理)。这使得纹理从近处看起来平滑,从远处看起来也平滑。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC = 4

纹理过滤从最近的像素读取并根据表面和相机视图之间的角度在 2 个多级渐远纹理之间进行混合(或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filtertrue,则使用最近的多级渐远纹理)。这使得纹理从近处看起来像素化,从远处看起来平滑。各向异性过滤提高了几乎与相机位于一条线上的表面上的纹理质量,但速度稍慢。各向异性过滤级别可以通过调整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 来改变。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC = 5

纹理过滤在最近的 4 个像素之间进行混合,并基于表面与相机视图之间的角度在 2 个多级渐远纹理之间进行混合 (或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filtertrue,则使用最近的多级渐远纹理)。这使得纹理从近处看起来平滑,从远处看起来也平滑。各向异性过滤提高了几乎与相机位于一条线的表面上的纹理质量,但速度稍慢。各向异性过滤级别可以通过调整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 来改变。

TextureFilter TEXTURE_FILTER_MAX = 6

代表 TextureFilter 枚举的大小。


enum DetailUV:

DetailUV DETAIL_UV_1 = 0

使用 UV 与细节纹理。

DetailUV DETAIL_UV_2 = 1

使用 UV2 与细节纹理。


enum Transparency:

Transparency TRANSPARENCY_DISABLED = 0

该材质将不使用透明度。渲染最快。

Transparency TRANSPARENCY_ALPHA = 1

该材质将使用纹理的 Alpha 值作为透明度。渲染最慢,且会禁用阴影投射。

Transparency TRANSPARENCY_ALPHA_SCISSOR = 2

该材质会将所有低于阈值的值截断,其余部分将保持不透明。不透明部分将在深度预通道中渲染。这比 Alpha 混合的渲染速度更快,但比不透明渲染慢。支持投射阴影。

Transparency TRANSPARENCY_ALPHA_HASH = 3

该材质会将所有低于空间确定性阈值的值截断,其余部分将保持不透明。这比 Alpha 混合的渲染速度更快,但比不透明渲染慢。支持投射阴影。Alpha 哈希适合毛发渲染。

Transparency TRANSPARENCY_ALPHA_DEPTH_PRE_PASS = 4

该材质将使用纹理的 Alpha 值作为透明度,但会在深度预通道阶段丢弃 Alpha 小于 0.99 的片段,并在阴影通道期间丢弃 Alpha 小于 0.1 的片段。支持投射阴影。

Transparency TRANSPARENCY_MAX = 5

代表 Transparency 枚举的大小。


enum ShadingMode:

ShadingMode SHADING_MODE_UNSHADED = 0

该对象不会接受阴影。渲染速度最快,但会禁用与灯光的所有交互。

ShadingMode SHADING_MODE_PER_PIXEL = 1

对象将逐像素进行着色。对于逼真的阴影效果很有用。

ShadingMode SHADING_MODE_PER_VERTEX = 2

对象将逐顶点进行着色。当想要更便宜的着色器并且不关心视觉质量时很有用。尚未实现(该模式的行为类似于 SHADING_MODE_PER_PIXEL)。

ShadingMode SHADING_MODE_MAX = 3

代表 ShadingMode 枚举的大小。


enum Feature:

Feature FEATURE_EMISSION = 0

用于设置 emission_enabled 的常量。

Feature FEATURE_NORMAL_MAPPING = 1

用于设置 normal_enabled 的常量。

Feature FEATURE_RIM = 2

用于设置 rim_enabled 的常量。

Feature FEATURE_CLEARCOAT = 3

用于设置 clearcoat_enabled 的常量。

Feature FEATURE_ANISOTROPY = 4

用于设置 anisotropy_enabled 的常量。

Feature FEATURE_AMBIENT_OCCLUSION = 5

用于设置 ao_enabled 的常量。

Feature FEATURE_HEIGHT_MAPPING = 6

用于设置 heightmap_enabled 的常量。

Feature FEATURE_SUBSURFACE_SCATTERING = 7

用于设置 subsurf_scatter_enabled 的常量。

Feature FEATURE_SUBSURFACE_TRANSMITTANCE = 8

用于设置 subsurf_scatter_transmittance_enabled 的常量。

Feature FEATURE_BACKLIGHT = 9

用于设置 backlight_enabled 的常量。

Feature FEATURE_REFRACTION = 10

用于设置 refraction_enabled 的常量。

Feature FEATURE_DETAIL = 11

用于设置 detail_enabled 的常量。

Feature FEATURE_MAX = 12

代表 Feature 枚举的大小。


enum BlendMode:

BlendMode BLEND_MODE_MIX = 0

默认的混合模式。根据对象的 Alpha 值,将对象的颜色混合到背景上。

BlendMode BLEND_MODE_ADD = 1

对象的颜色被加到背景中。

BlendMode BLEND_MODE_SUB = 2

从背景中减去对象的颜色。

BlendMode BLEND_MODE_MUL = 3

对象的颜色与背景相乘。


enum AlphaAntiAliasing:

AlphaAntiAliasing ALPHA_ANTIALIASING_OFF = 0

禁用该材质的 Alpha 抗锯齿。

AlphaAntiAliasing ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE = 1

启用 AlphaToCoverage。材质中的 Alpha 值会被传递到 AntiAliasing 采样遮罩。

AlphaAntiAliasing ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE_AND_TO_ONE = 2

启用 AlphaToCoverage 并将所有非零的 alpha 值强制设为 1。材质中的 Alpha 值会被传递到 AntiAliasing 采样遮罩。


enum DepthDrawMode:

DepthDrawMode DEPTH_DRAW_OPAQUE_ONLY = 0

默认的深度绘制模式。在不透明预通道(如果有)和不透明通道期间,仅为不透明对象绘制深度。

DepthDrawMode DEPTH_DRAW_ALWAYS = 1

在不透明和透明通道期间,对象将写入深度。靠近相机的透明物体可能会遮挡它们后面的其他透明物体。

注意:这不影响透明对象是否包含在深度预通道中。为此,请参阅 Transparency

DepthDrawMode DEPTH_DRAW_DISABLED = 2

对象不会将其深度写入深度缓冲区,即使在深度预通道期间(如果启用)也是如此。


enum CullMode:

CullMode CULL_BACK = 0

默认剔除模式。对象的背面在不可见时被剔除。面对相机时,背面三角形将被剔除。这导致仅绘制三角形的正面。对于封闭表面网格,这意味着只有网格的外部可见。

CullMode CULL_FRONT = 1

面对相机时,正面三角形将被剔除。这导致仅绘制三角形的背面。对于封闭表面网格,这意味着将绘制网格的内部而不是外部。

CullMode CULL_DISABLED = 2

不执行面剔除;正反面均可见。


enum Flags:

Flags FLAG_DISABLE_DEPTH_TEST = 0

禁用深度测试,所以这个对象将被绘制到在它之前绘制的所有其他对象之上。这会将对象置于透明绘制通道中,并根据到相机的距离对其进行排序。按照绘制顺序在它之后绘制的对象可能会覆盖它。会禁用深度写入。

Flags FLAG_ALBEDO_FROM_VERTEX_COLOR = 1

ALBEDO 设置为网格中指定的每顶点颜色。

Flags FLAG_SRGB_VERTEX_COLOR = 2

顶点颜色被认为使用 sRGB 颜色空间存储,并在渲染期间转换为线性颜色空间。另见 vertex_color_is_srgb

注意:仅在使用 Forward+ 和移动渲染方式时有效。

Flags FLAG_USE_POINT_SIZE = 3

使用点大小来改变图元点的大小。同时改变反射率纹理查找,使用 POINT_COORD 而不是 UV

Flags FLAG_FIXED_SIZE = 4

按深度缩放对象,使其在屏幕上显示的大小始终相同。

Flags FLAG_BILLBOARD_KEEP_SCALE = 5

着色器将保持网格的缩放设置。否则,在用作公告板时会丢失缩放。仅在 billboard_modeBILLBOARD_ENABLED 时适用。

Flags FLAG_UV1_USE_TRIPLANAR = 6

对所有通常会使用 UV 的纹理查找使用三平面纹理查找。

Flags FLAG_UV2_USE_TRIPLANAR = 7

对所有通常会使用 UV2 的纹理查找使用三平面纹理查找。

Flags FLAG_UV1_USE_WORLD_TRIPLANAR = 8

对所有通常会使用 UV 的纹理查找使用三平面纹理查找。

Flags FLAG_UV2_USE_WORLD_TRIPLANAR = 9

对所有通常会使用 UV2 的纹理查找使用三平面纹理查找。

Flags FLAG_AO_ON_UV2 = 10

使用 UV2 坐标从 ao_texture 中查找。

Flags FLAG_EMISSION_ON_UV2 = 11

使用 UV2 坐标从 emission_texture 中查找。

Flags FLAG_ALBEDO_TEXTURE_FORCE_SRGB = 12

强制着色器将反照率从 sRGB 空间转换为线性空间。另见 albedo_texture_force_srgb

Flags FLAG_DONT_RECEIVE_SHADOWS = 13

禁用从其他对象接收阴影。

Flags FLAG_DISABLE_AMBIENT_LIGHT = 14

禁用接收环境光。

Flags FLAG_USE_SHADOW_TO_OPACITY = 15

启用阴影到不透明度功能。

Flags FLAG_USE_TEXTURE_REPEAT = 16

当 UV 坐标超出 0-1 范围时,使纹理能够重复。如果使用其中一种线性过滤模式,则当采样器过滤纹理边缘时,这可能会导致纹理边缘出现伪影。

Flags FLAG_INVERT_HEIGHTMAP = 17

反转从深度纹理读取的值以将它们转换为高度值(高度图)。

Flags FLAG_SUBSURFACE_MODE_SKIN = 18

启用用于次表面散射的皮肤模式,该模式用于改善被用于人体皮肤时的次表面散射的外观。

Flags FLAG_PARTICLE_TRAILS_MODE = 19

启用使 GPUParticles3D 尾迹生效所需的部分着色器。这也需要使用具有适当蒙皮的网格,例如 RibbonTrailMeshTubeTrailMesh。在 GPUParticles3D 网格中使用的材质之外启用该功能将破坏材质的渲染。

Flags FLAG_ALBEDO_TEXTURE_MSDF = 20

启用多通道有符号距离场渲染着色器。

Flags FLAG_DISABLE_FOG = 21

禁用接收基于深度或体积雾。

Flags FLAG_MAX = 22

代表 Flags 枚举的大小。


enum DiffuseMode:

DiffuseMode DIFFUSE_BURLEY = 0

默认的漫反射散射算法。

DiffuseMode DIFFUSE_LAMBERT = 1

漫散射忽略了粗糙度。

DiffuseMode DIFFUSE_LAMBERT_WRAP = 2

当粗糙度增加时,将 Lambert 延伸到 90 度以上。

DiffuseMode DIFFUSE_TOON = 3

使用硬切口进行照明,平滑度受粗糙度影响。


enum SpecularMode:

SpecularMode SPECULAR_SCHLICK_GGX = 0

默认镜面反射斑点。

SpecularMode SPECULAR_TOON = 1

基于粗糙度更改大小的 Toon 斑点。

SpecularMode SPECULAR_DISABLED = 2

没有镜面反射斑点。这比其他镜面反射模式渲染速度稍快。


enum BillboardMode:

BillboardMode BILLBOARD_DISABLED = 0

公告板模式已禁用。

BillboardMode BILLBOARD_ENABLED = 1

对象的 Z 轴将始终面向相机。

BillboardMode BILLBOARD_FIXED_Y = 2

对象的 X 轴将始终面向相机。

BillboardMode BILLBOARD_PARTICLES = 3

分配给 GPUParticles3D