Work in progress
Godot documentation is being updated to reflect the latest changes in version
4.0
. Some documentation pages may
still state outdated information. This banner will tell you if you're reading one of such pages.
The contents of this page are up to date. If you can still find outdated information, please open an issue.
BaseMaterial3D¶
Inherits: Material < Resource < RefCounted < Object
Inherited By: ORMMaterial3D, StandardMaterial3D
Default 3D rendering material.
Description¶
This provides a default material with a wide variety of rendering features and properties without the need to write shader code. See the tutorial below for details.
Tutorials¶
Properties¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Methods¶
get_feature ( Feature feature ) const |
|
get_texture ( TextureParam param ) const |
|
void |
set_feature ( Feature feature, bool enable ) |
void |
|
void |
set_texture ( TextureParam param, Texture2D texture ) |
Enumerations¶
enum TextureParam:
TextureParam TEXTURE_ALBEDO = 0
Texture specifying per-pixel color.
TextureParam TEXTURE_METALLIC = 1
Texture specifying per-pixel metallic value.
TextureParam TEXTURE_ROUGHNESS = 2
Texture specifying per-pixel roughness value.
TextureParam TEXTURE_EMISSION = 3
Texture specifying per-pixel emission color.
TextureParam TEXTURE_NORMAL = 4
Texture specifying per-pixel normal vector.
TextureParam TEXTURE_RIM = 5
Texture specifying per-pixel rim value.
TextureParam TEXTURE_CLEARCOAT = 6
Texture specifying per-pixel clearcoat value.
TextureParam TEXTURE_FLOWMAP = 7
Texture specifying per-pixel flowmap direction for use with anisotropy.
TextureParam TEXTURE_AMBIENT_OCCLUSION = 8
Texture specifying per-pixel ambient occlusion value.
TextureParam TEXTURE_HEIGHTMAP = 9
Texture specifying per-pixel height.
TextureParam TEXTURE_SUBSURFACE_SCATTERING = 10
Texture specifying per-pixel subsurface scattering.
TextureParam TEXTURE_SUBSURFACE_TRANSMITTANCE = 11
Texture specifying per-pixel transmittance for subsurface scattering.
TextureParam TEXTURE_BACKLIGHT = 12
Texture specifying per-pixel backlight color.
TextureParam TEXTURE_REFRACTION = 13
Texture specifying per-pixel refraction strength.
TextureParam TEXTURE_DETAIL_MASK = 14
Texture specifying per-pixel detail mask blending value.
TextureParam TEXTURE_DETAIL_ALBEDO = 15
Texture specifying per-pixel detail color.
TextureParam TEXTURE_DETAIL_NORMAL = 16
Texture specifying per-pixel detail normal.
TextureParam TEXTURE_ORM = 17
Texture holding ambient occlusion, roughness, and metallic.
TextureParam TEXTURE_MAX = 18
Represents the size of the TextureParam enum.
enum TextureFilter:
TextureFilter TEXTURE_FILTER_NEAREST = 0
The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized.
TextureFilter TEXTURE_FILTER_LINEAR = 1
The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps.
TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 2
The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps.
TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 3
The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for most cases as mipmaps are important to smooth out pixels that are far from the camera.
TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC = 4
The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level.
TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC = 5
The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level.
TextureFilter TEXTURE_FILTER_MAX = 6
Represents the size of the TextureFilter enum.
enum DetailUV:
DetailUV DETAIL_UV_1 = 0
Use UV
with the detail texture.
DetailUV DETAIL_UV_2 = 1
Use UV2
with the detail texture.
enum Transparency:
Transparency TRANSPARENCY_DISABLED = 0
The material will not use transparency. This is the fastest to render.
Transparency TRANSPARENCY_ALPHA = 1
The material will use the texture's alpha values for transparency. This is the slowest to render, and disables shadow casting.
Transparency TRANSPARENCY_ALPHA_SCISSOR = 2
The material will cut off all values below a threshold, the rest will remain opaque. The opaque portions will be rendered in the depth prepass. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows.
Transparency TRANSPARENCY_ALPHA_HASH = 3
The material will cut off all values below a spatially-deterministic threshold, the rest will remain opaque. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows. Alpha hashing is suited for hair rendering.
Transparency TRANSPARENCY_ALPHA_DEPTH_PRE_PASS = 4
The material will use the texture's alpha value for transparency, but will discard fragments with an alpha of less than 0.99 during the depth prepass and fragments with an alpha less than 0.1 during the shadow pass. This also supports casting shadows.
Transparency TRANSPARENCY_MAX = 5
Represents the size of the Transparency enum.
enum ShadingMode:
ShadingMode SHADING_MODE_UNSHADED = 0
The object will not receive shadows. This is the fastest to render, but it disables all interactions with lights.
ShadingMode SHADING_MODE_PER_PIXEL = 1
The object will be shaded per pixel. Useful for realistic shading effects.
ShadingMode SHADING_MODE_PER_VERTEX = 2
The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. Not implemented yet (this mode will act like SHADING_MODE_PER_PIXEL).
ShadingMode SHADING_MODE_MAX = 3
Represents the size of the ShadingMode enum.
enum Feature:
Feature FEATURE_EMISSION = 0
Constant for setting emission_enabled.
Feature FEATURE_NORMAL_MAPPING = 1
Constant for setting normal_enabled.
Feature FEATURE_RIM = 2
Constant for setting rim_enabled.
Feature FEATURE_CLEARCOAT = 3
Constant for setting clearcoat_enabled.
Feature FEATURE_ANISOTROPY = 4
Constant for setting anisotropy_enabled.
Feature FEATURE_AMBIENT_OCCLUSION = 5
Constant for setting ao_enabled.
Feature FEATURE_HEIGHT_MAPPING = 6
Constant for setting heightmap_enabled.
Feature FEATURE_SUBSURFACE_SCATTERING = 7
Constant for setting subsurf_scatter_enabled.
Feature FEATURE_SUBSURFACE_TRANSMITTANCE = 8
Constant for setting subsurf_scatter_transmittance_enabled.
Feature FEATURE_BACKLIGHT = 9
Constant for setting backlight_enabled.
Feature FEATURE_REFRACTION = 10
Constant for setting refraction_enabled.
Feature FEATURE_DETAIL = 11
Constant for setting detail_enabled.
Feature FEATURE_MAX = 12
Represents the size of the Feature enum.
enum BlendMode:
BlendMode BLEND_MODE_MIX = 0
Default blend mode. The color of the object is blended over the background based on the object's alpha value.
BlendMode BLEND_MODE_ADD = 1
The color of the object is added to the background.
BlendMode BLEND_MODE_SUB = 2
The color of the object is subtracted from the background.
BlendMode BLEND_MODE_MUL = 3
The color of the object is multiplied by the background.
enum AlphaAntiAliasing:
AlphaAntiAliasing ALPHA_ANTIALIASING_OFF = 0
Disables Alpha AntiAliasing for the material.
AlphaAntiAliasing ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE = 1
Enables AlphaToCoverage. Alpha values in the material are passed to the AntiAliasing sample mask.
AlphaAntiAliasing ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE_AND_TO_ONE = 2
Enables AlphaToCoverage and forces all non-zero alpha values to 1
. Alpha values in the material are passed to the AntiAliasing sample mask.
enum DepthDrawMode:
DepthDrawMode DEPTH_DRAW_OPAQUE_ONLY = 0
Default depth draw mode. Depth is drawn only for opaque objects during the opaque prepass (if any) and during the opaque pass.
DepthDrawMode DEPTH_DRAW_ALWAYS = 1
Objects will write to depth during the opaque and the transparent passes. Transparent objects that are close to the camera may obscure other transparent objects behind them.
Note: This does not influence whether transparent objects are included in the depth prepass or not. For that, see Transparency.
DepthDrawMode DEPTH_DRAW_DISABLED = 2
Objects will not write their depth to the depth buffer, even during the depth prepass (if enabled).
enum CullMode:
CullMode CULL_BACK = 0
Default cull mode. The back of the object is culled when not visible. Back face triangles will be culled when facing the camera. This results in only the front side of triangles being drawn. For closed-surface meshes, this means that only the exterior of the mesh will be visible.
CullMode CULL_FRONT = 1
Front face triangles will be culled when facing the camera. This results in only the back side of triangles being drawn. For closed-surface meshes, this means that the interior of the mesh will be drawn instead of the exterior.
CullMode CULL_DISABLED = 2
No face culling is performed; both the front face and back face will be visible.
enum Flags:
Flags FLAG_DISABLE_DEPTH_TEST = 0
Disables the depth test, so this object is drawn on top of all others drawn before it. This puts the object in the transparent draw pass where it is sorted based on distance to camera. Objects drawn after it in the draw order may cover it. This also disables writing to depth.
Flags FLAG_ALBEDO_FROM_VERTEX_COLOR = 1
Set ALBEDO
to the per-vertex color specified in the mesh.
Flags FLAG_SRGB_VERTEX_COLOR = 2
Vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. See also vertex_color_is_srgb.
Note: Only effective when using the Forward+ and Mobile rendering methods.
Flags FLAG_USE_POINT_SIZE = 3
Uses point size to alter the size of primitive points. Also changes the albedo texture lookup to use POINT_COORD
instead of UV
.
Flags FLAG_FIXED_SIZE = 4
Object is scaled by depth so that it always appears the same size on screen.
Flags FLAG_BILLBOARD_KEEP_SCALE = 5
Shader will keep the scale set for the mesh. Otherwise the scale is lost when billboarding. Only applies when billboard_mode is BILLBOARD_ENABLED.
Flags FLAG_UV1_USE_TRIPLANAR = 6
Use triplanar texture lookup for all texture lookups that would normally use UV
.
Flags FLAG_UV2_USE_TRIPLANAR = 7
Use triplanar texture lookup for all texture lookups that would normally use UV2
.
Flags FLAG_UV1_USE_WORLD_TRIPLANAR = 8
Use triplanar texture lookup for all texture lookups that would normally use UV
.
Flags FLAG_UV2_USE_WORLD_TRIPLANAR = 9
Use triplanar texture lookup for all texture lookups that would normally use UV2
.
Flags FLAG_AO_ON_UV2 = 10
Use UV2
coordinates to look up from the ao_texture.
Flags FLAG_EMISSION_ON_UV2 = 11
Use UV2
coordinates to look up from the emission_texture.
Flags FLAG_ALBEDO_TEXTURE_FORCE_SRGB = 12
Forces the shader to convert albedo from sRGB space to linear space. See also albedo_texture_force_srgb.
Flags FLAG_DONT_RECEIVE_SHADOWS = 13
Disables receiving shadows from other objects.
Flags FLAG_DISABLE_AMBIENT_LIGHT = 14
Disables receiving ambient light.
Flags FLAG_USE_SHADOW_TO_OPACITY = 15
Enables the shadow to opacity feature.
Flags FLAG_USE_TEXTURE_REPEAT = 16
Enables the texture to repeat when UV coordinates are outside the 0-1 range. If using one of the linear filtering modes, this can result in artifacts at the edges of a texture when the sampler filters across the edges of the texture.
Flags FLAG_INVERT_HEIGHTMAP = 17
Invert values read from a depth texture to convert them to height values (heightmap).
Flags FLAG_SUBSURFACE_MODE_SKIN = 18
Enables the skin mode for subsurface scattering which is used to improve the look of subsurface scattering when used for human skin.
Flags FLAG_PARTICLE_TRAILS_MODE = 19
Enables parts of the shader required for GPUParticles3D trails to function. This also requires using a mesh with appropriate skinning, such as RibbonTrailMesh or TubeTrailMesh. Enabling this feature outside of materials used in GPUParticles3D meshes will break material rendering.
Flags FLAG_ALBEDO_TEXTURE_MSDF = 20
Enables multichannel signed distance field rendering shader.
Flags FLAG_MAX = 21
Represents the size of the Flags enum.
enum DiffuseMode:
DiffuseMode DIFFUSE_BURLEY = 0
Default diffuse scattering algorithm.
DiffuseMode DIFFUSE_LAMBERT = 1
Diffuse scattering ignores roughness.
DiffuseMode DIFFUSE_LAMBERT_WRAP = 2
Extends Lambert to cover more than 90 degrees when roughness increases.
DiffuseMode DIFFUSE_TOON = 3
Uses a hard cut for lighting, with smoothing affected by roughness.
enum SpecularMode:
SpecularMode SPECULAR_SCHLICK_GGX = 0
Default specular blob.
SpecularMode SPECULAR_TOON = 1
Toon blob which changes size based on roughness.
SpecularMode SPECULAR_DISABLED = 2
No specular blob. This is slightly faster to render than other specular modes.
enum BillboardMode:
BillboardMode BILLBOARD_DISABLED = 0
Billboard mode is disabled.