GeometryInstance3D

GeometryInstance3D

继承： VisualInstance3D < Node3D < Node < Object

派生： CPUParticles3D, CSGShape3D, GPUParticles3D, Label3D, MeshInstance3D, MultiMeshInstance3D, SpriteBase3D

基于几何图形的视觉实例的基础节点。

描述

基于几何图形的视觉实例的基础节点。分享一些共同的机制，如可见性和自定义材质。

教程

可见范围（HLOD）

属性

ShadowCastingSetting	cast_shadow	`1`
AABB	custom_aabb	`AABB(0, 0, 0, 0, 0, 0)`
float	extra_cull_margin	`0.0`
LightmapScale	gi_lightmap_scale	`0`
GIMode	gi_mode	`1`
bool	ignore_occlusion_culling	`false`
float	lod_bias	`1.0`
Material	material_overlay
Material	material_override
float	transparency	`0.0`
float	visibility_range_begin	`0.0`
float	visibility_range_begin_margin	`0.0`
float	visibility_range_end	`0.0`
float	visibility_range_end_margin	`0.0`
VisibilityRangeFadeMode	visibility_range_fade_mode	`0`

方法

Variant	get_instance_shader_parameter(name: StringName) const
void	set_instance_shader_parameter(name: StringName, value: Variant)

枚举

enum ShadowCastingSetting: 🔗

ShadowCastingSetting SHADOW_CASTING_SETTING_OFF = 0

不会投射任何阴影。使用该选项，可提高不太可能投射明显阴影的小型几何体（例如碎片）的性能。

ShadowCastingSetting SHADOW_CASTING_SETTING_ON = 1

将从 GeometryInstance3D 中的所有可见面投射阴影。

将考虑剔除，因此在阴影投射时，不会考虑那些不会被渲染的面。

ShadowCastingSetting SHADOW_CASTING_SETTING_DOUBLE_SIDED = 2

将从 GeometryInstance3D 中的所有可见面投射阴影。

不会考虑剔除，因此在阴影投射时，将考虑所有面。

ShadowCastingSetting SHADOW_CASTING_SETTING_SHADOWS_ONLY = 3

只显示从这个物体投射出来的阴影。

换句话说，实际的网格将不可见，只有网格投影可见。

enum GIMode: 🔗

GIMode GI_MODE_DISABLED = 0

禁用全局照明模式。用于对全局照明没有贡献的动态对象（例如角色）。使用 VoxelGI 和 SDFGI 时，几何体将接收间接照明和反射，但在 GI 烘焙中不会考虑几何体。

GIMode GI_MODE_STATIC = 1

烘焙全局照明模式。用于有助于全局照明的静态对象（例如关卡几何体）。该 GI 模式在使用 VoxelGI、SDFGI 和 LightmapGI 时有效。

GIMode GI_MODE_DYNAMIC = 2

动态全局照明模式。用于有助于全局照明的动态对象。这种 GI 模式只有在使用 VoxelGI 时才有效，但它对性能的影响，比 GI_MODE_STATIC 更高。当使用其他 GI 方法时，它的作用与 GI_MODE_DISABLED 相同。使用 LightmapGI 时，对象将使用光照贴图探针接收间接光照，而不是使用烘焙的光照贴图纹理。

enum LightmapScale: 🔗

LightmapScale LIGHTMAP_SCALE_1X = 0

使用 LightmapGI 进行光照贴图的标准纹素密度。

LightmapScale LIGHTMAP_SCALE_2X = 1

使用 LightmapGI 进行光照贴图时，将纹素密度乘以 2 倍。为确保纹素密度的一致性，请在按 1.5 到 3.0 之间的系数缩放网格时，使用该选项。

LightmapScale LIGHTMAP_SCALE_4X = 2

使用 LightmapGI 进行光照贴图时，将纹素密度乘以 4 倍。为确保纹素密度的一致性，请在按 3.0 到 6.0 之间的系数缩放网格时，使用该选项。

LightmapScale LIGHTMAP_SCALE_8X = 3

使用 LightmapGI 进行光照贴图时，将纹素密度乘以 8 倍。为确保纹素密度的一致性，请在以大于 6.0 的系数缩放网格时，使用该选项。

LightmapScale LIGHTMAP_SCALE_MAX = 4

代表 LightmapScale 枚举的大小。

enum VisibilityRangeFadeMode: 🔗

VisibilityRangeFadeMode VISIBILITY_RANGE_FADE_DISABLED = 0

不会自行淡化，也不会淡化其可见性依赖项，而是使用滞后。这是手动 LOD 的最快方法，但它可能会导致明显的 LOD 过渡，具体取决于 LOD 网格的创作方式。有关更多信息，请参阅 visibility_range_begin 和 Node3D.visibility_parent。

VisibilityRangeFadeMode VISIBILITY_RANGE_FADE_SELF = 1

当达到自身可见范围的极限时，会自行淡出。这比 VISIBILITY_RANGE_FADE_DISABLED 慢，但它可以提供更平滑的过渡。淡出范围由 visibility_range_begin_margin 和 visibility_range_end_margin 决定。

注意：仅支持使用 Forward+ 渲染方法。使用 Mobile 或 Compatibility 渲染方法时，该模式与 VISIBILITY_RANGE_FADE_DISABLED 类似，但会禁用迟滞。

VisibilityRangeFadeMode VISIBILITY_RANGE_FADE_DEPENDENCIES = 2

当达到其自身可见性范围的限制时，将淡入其可见性依赖项（见 Node3D.visibility_parent）。这比 VISIBILITY_RANGE_FADE_DISABLED 慢，但它可以提供更平滑的过渡。淡出范围由 visibility_range_begin_margin 和 visibility_range_end_margin 决定。

注意：仅支持使用 Forward+ 渲染方法。使用 Mobile 或 Compatibility 渲染方法时，该模式与 VISIBILITY_RANGE_FADE_DISABLED 类似，但会禁用迟滞。

属性说明

ShadowCastingSetting cast_shadow = 1 🔗

void set_cast_shadows_setting(value: ShadowCastingSetting)
ShadowCastingSetting get_cast_shadows_setting()

选择的阴影投射标志。可能的取值见 ShadowCastingSetting。

AABB custom_aabb = AABB(0, 0, 0, 0, 0, 0) 🔗

void set_custom_aabb(value: AABB)
AABB get_custom_aabb()

使用自定义边界框覆盖该节点的边界框。骨架使用 MeshInstance3D 时可以避免重新计算 AABB 节省性能，也可以用来对 MeshInstance3D 的边界框进行精确控制。要使用默认的 AABB，请将其设为所有字段均为 0.0 的 AABB。要避免视锥剔除，请将 custom_aabb 设为大到能够覆盖整个游戏世界的 AABB，例如 AABB(-10000, -10000, -10000, 20000, 20000, 20000)。要禁用所有形式的剔除（包括遮挡剔除），请使用该 GeometryInstance3D 的 RID 调用 RenderingServer.instance_set_ignore_culling。

float extra_cull_margin = 0.0 🔗

void set_extra_cull_margin(value: float)
float get_extra_cull_margin()

添加到 GeometryInstance3D 的边界框（AABB），以增加其剔除框的额外距离。

LightmapScale gi_lightmap_scale = 0 🔗

void set_lightmap_scale(value: LightmapScale)
LightmapScale get_lightmap_scale()

LightmapGI 中用于光照贴图的纹素密度。较大的缩放值可在光照贴图中提供更高的分辨率，这可以为同时烘焙了直接光和间接光的灯光，生成更清晰的阴影。但是，更大的缩放值也会增加光照贴图纹理中网格占用的空间，从而增加需要的内存、存储空间和烘焙时间。在不同缩放下使用单个网格时，请考虑调整该值，以保持光照贴图纹素密度在网格之间保持一致。

GIMode gi_mode = 1 🔗

void set_gi_mode(value: GIMode)
GIMode get_gi_mode()

用于整个几何体的全局照明模式。为避免结果不一致，请在游戏过程中，使用与网格用途相匹配的模式（静态/动态）。

注意：灯光的烘焙模式，也会影响全局照明渲染。请参阅 Light3D.light_bake_mode。

bool ignore_occlusion_culling = false 🔗

void set_ignore_occlusion_culling(value: bool)
bool is_ignoring_occlusion_culling()

如果为 true，则禁用这个实例的遮挡剔除。可用于即便开启遮挡剔除也必须渲染的小工具。

注意：ignore_occlusion_culling 不会影响视锥剔除（对象因为相机的角度而不可见时触发）。要避免视锥剔除，请将 custom_aabb 设置为很大的 AABB，覆盖住整个游戏世界，例如 AABB(-10000, -10000, -10000, 20000, 20000, 20000)。

float lod_bias = 1.0 🔗

void set_lod_bias(value: float)
float get_lod_bias()

改变网格过渡到较低细节级别的速度。值为 0 将强制网格达到最低细节级别，值为 1 将使用默认设置，更大的值将使网格在更远的距离处保持更高的细节级别。

对于测试编辑器中的细节级别的过渡很有用。

Material material_overlay 🔗

void set_material_overlay(value: Material)
Material get_material_overlay()

整个几何体的材质覆盖层。

如果一个材质被分配给这个属性，它将会被渲染在所有表面的任何其他活动材质之上。

Material material_override 🔗

void set_material_override(value: Material)
Material get_material_override()

整个几何体的材质覆盖。

如果一个材质被分配给这个属性，它将会被用来代替在网格的任何材质槽中设置的任何材质。

float transparency = 0.0 🔗

void set_transparency(value: float)
float get_transparency()

应用于整个几何体的透明度（作为材质现有透明度的乘数）。0.0 是完全不透明的，而 1.0 是完全透明的。大于 0.0（不含）的值将强制几何体的材质通过透明管道，这会导致渲染速度变慢，并且可能会因不正确的透明度排序而出现渲染问题。但是，与使用透明材质不同的是，将 transparency 设置为大于 0.0（不含）的值并不会禁用阴影渲染。

在空间着色器中，1.0 - transparency 被设置为内置 ALPHA 的默认值。

注意：transparency 被钳制在 0.0 和 1.0 之间，所以这个属性不能被用来使透明材质变得比原来更加不透明。

注意：仅在使用 Forward+ 渲染方法时受支持。使用 Mobile 或 Compatibility 渲染方法时，transparency 将被忽略并被视为始终为 0.0。

float visibility_range_begin = 0.0 🔗

void set_visibility_range_begin(value: float)
float get_visibility_range_begin()

GeometryInstance3D 可见的起始距离，同时考虑 visibility_range_begin_margin。默认值 0 用于禁用范围检查。

float visibility_range_begin_margin = 0.0 🔗

void set_visibility_range_begin_margin(value: float)
float get_visibility_range_begin_margin()

visibility_range_begin 阈值的边距。GeometryInstance3D 只有在超出或低于 visibility_range_begin 阈值达到这个量时，才会更改其可见性状态。

如果 visibility_range_fade_mode 为 VISIBILITY_RANGE_FADE_DISABLED，这将作为滞后距离。如果 visibility_range_fade_mode 为 VISIBILITY_RANGE_FADE_SELF 或 VISIBILITY_RANGE_FADE_DEPENDENCIES，这将作为淡入淡出过渡距离，并且必须被设置为大于 0.0 的值，才能使效果显眼。

float visibility_range_end = 0.0 🔗

void set_visibility_range_end(value: float)
float get_visibility_range_end()

GeometryInstance3D 将被隐藏的距离，同时考虑 visibility_range_end_margin。默认值 0 用于禁用范围检查。

float visibility_range_end_margin = 0.0 🔗

void set_visibility_range_end_margin(value: float)
float get_visibility_range_end_margin()

visibility_range_end 阈值的边距。GeometryInstance3D 只有在超出或低于 visibility_range_end 阈值达到这个量时，才会更改其可见性状态。

VisibilityRangeFadeMode visibility_range_fade_mode = 0 🔗

void set_visibility_range_fade_mode(value: VisibilityRangeFadeMode)
VisibilityRangeFadeMode get_visibility_range_fade_mode()

控制在接近可见范围的限制时，哪些实例将被淡化。有关可能的值，请参阅 VisibilityRangeFadeMode。

方法说明

Variant get_instance_shader_parameter(name: StringName) const 🔗

获取在该实例上设置的着色器参数值。

void set_instance_shader_parameter(name: StringName, value: Variant) 🔗

仅为该实例设置一个着色器 uniform 值（每实例 uniform）。另请参阅 ShaderMaterial.set_shader_parameter 以使用相同的 ShaderMaterial 在所有实例上分配一个 uniform。

注意：要在每个实例的基础上分配一个着色器 uniform，则必须在着色器代码中，使用 instance uniform ...，而不是 uniform ... 来定义。

注意：name 是区分大小写的，并且必须与代码中的 uniform 名称完全匹配（而不是检查器中大写的名称）。

注意：逐实例着色器 uniform 目前仅在 3D 中可用，因此没有该方法的 2D 等效方法。