SpriteBase3D

继承： GeometryInstance3D < VisualInstance3D < Node3D < Node < Object

派生： AnimatedSprite3D, Sprite3D

3D 环境中的 2D 精灵节点。

描述

在 3D 环境中显示 2D 纹理信息的节点。另请参阅 Sprite3D，其中定义了许多其他属性。

属性

float

alpha_antialiasing_edge

0.0

AlphaAntiAliasing

alpha_antialiasing_mode

0

AlphaCutMode

alpha_cut

0

float

alpha_hash_scale

1.0

float

alpha_scissor_threshold

0.5

Vector3.Axis

axis

2

BillboardMode

billboard

0

bool

centered

true

bool

double_sided

true

bool

fixed_size

false

bool

flip_h

false

bool

flip_v

false

Color

modulate

Color(1, 1, 1, 1)

bool

no_depth_test

false

Vector2

offset

Vector2(0, 0)

float

pixel_size

0.01

int

render_priority

0

bool

shaded

false

TextureFilter

texture_filter

3

bool

transparent

true

方法

TriangleMesh

generate_triangle_mesh() const

bool

get_draw_flag(flag: DrawFlags) const

Rect2

get_item_rect() const

void

set_draw_flag(flag: DrawFlags, enabled: bool)

枚举

enum DrawFlags: 🔗

DrawFlags FLAG_TRANSPARENT = 0

如果设置，纹理的透明度和不透明性用于使精灵的这些部分不可见。

DrawFlags FLAG_SHADED = 1

如果设置，环境中的灯光会影响精灵。

DrawFlags FLAG_DOUBLE_SIDED = 2

如果启用，则纹理也可以从背面看到。如果未启用，则纹理从后面查看时不可见。

DrawFlags FLAG_DISABLE_DEPTH_TEST = 3

禁用深度测试，所以这个对象被画在所有其他对象的上面。但是，在绘制顺序中，在它之后绘制的对象可能会覆盖它。

DrawFlags FLAG_FIXED_SIZE = 4

标签会根据深度进行缩放，从而在屏幕上始终以相同的大小显示。

DrawFlags FLAG_MAX = 5

代表 DrawFlags 枚举的大小。

enum AlphaCutMode: 🔗

AlphaCutMode ALPHA_CUT_DISABLED = 0

这个模式会进行标准的 Alpha 混合。可以显示半透明区域，但透明材质存在重叠时可能会暴露透明度排序问题。

AlphaCutMode ALPHA_CUT_DISCARD = 1

该模式仅允许完全透明或完全不透明的像素。除非启用了某种形式的屏幕空间抗锯齿（请参阅 ProjectSettings.rendering/anti_aliasing/quality/screen_space_aa），否则会看到粗糙的边缘。从好的方面来说，当多个透明材质重叠时，该模式不会出现透明度排序问题。这种模式也被称为 alpha 测试或 1 位透明度。

AlphaCutMode ALPHA_CUT_OPAQUE_PREPASS = 2

该模式在深度预渲染阶段绘制完全不透明的像素。这比 ALPHA_CUT_DISABLED 或 ALPHA_CUT_DISCARD 慢，但它允许在使用正确排序的同时显示半透明区域和平滑边缘。

AlphaCutMode ALPHA_CUT_HASH = 3

该模式绘制时会截断所有低于空间确定性阈值的值，其余值将保持不透明。

属性说明

float alpha_antialiasing_edge = 0.0 🔗

  • void set_alpha_antialiasing_edge(value: float)

  • float get_alpha_antialiasing_edge()

将在 Alpha 通道上应用抗锯齿的阈值。

AlphaAntiAliasing alpha_antialiasing_mode = 0 🔗

要应用的 Alpha 抗锯齿类型。见 AlphaAntiAliasing。

AlphaCutMode alpha_cut = 0 🔗

该精灵的 Alpha 裁剪模式。可能的取值见 AlphaCutMode。

float alpha_hash_scale = 1.0 🔗

  • void set_alpha_hash_scale(value: float)

  • float get_alpha_hash_scale()

Alpha Hash 的哈希比例。推荐 0 和 2 之间的值。

float alpha_scissor_threshold = 0.5 🔗

  • void set_alpha_scissor_threshold(value: float)

  • float get_alpha_scissor_threshold()

Alpha 裁剪丢弃数值的阈值。

Vector3.Axis axis = 2 🔗

  • void set_axis(value: Vector3.Axis)

  • Vector3.Axis get_axis()

纹理正面朝向的方向。

BillboardMode billboard = 0 🔗

精灵的公告板模式。可能的取值见 BillboardMode。

注意：如果启用了公告板并且材质能够投射阴影，那么渲染阴影时公告板面向的是场景中的相机。如果场景中存在多个相机，则无法确定阴影，会导致未定义的行为。详见 GitHub Pull Request #72638。

bool centered = true 🔗

  • void set_centered(value: bool)

  • bool is_centered()

如果为 true，纹理将被居中。

bool double_sided = true 🔗

如果为 true，则从后面也可以看到纹理，如果为 false，则从后面看它是不可见的。

bool fixed_size = false 🔗

如果为 true，则无论距离远近，标签都以相同的尺寸呈现。

bool flip_h = false 🔗

  • void set_flip_h(value: bool)

  • bool is_flipped_h()

如果为 true，纹理将被水平翻转。

bool flip_v = false 🔗

  • void set_flip_v(value: bool)

  • bool is_flipped_v()

如果为 true，纹理将被垂直翻转。

Color modulate = Color(1, 1, 1, 1) 🔗

  • void set_modulate(value: Color)

  • Color get_modulate()

用于乘以纹理颜色的颜色值。可用于氛围着色或模拟环境光的颜色。

注意：与 2D 的 CanvasItem.modulate 不同，不支持大于 1.0 的颜色值（过亮）。

注意：如果在 SpriteBase3D 上定义了 GeometryInstance3D.material_override，则必须配置该材质，让它的反照率考虑顶点颜色。否则 modulate 中定义的颜色将被忽略。对于 BaseMaterial3D，BaseMaterial3D.vertex_color_use_as_albedo 必须为 true。对于 ShaderMaterial，必须将 ALBEDO *= COLOR.rgb;，插入到着色器的 fragment() 函数中。

bool no_depth_test = false 🔗

如果为 true，深度测试被禁用，对象将按渲染顺序绘制。

Vector2 offset = Vector2(0, 0) 🔗

纹理的绘图偏移量。

float pixel_size = 0.01 🔗

  • void set_pixel_size(value: float)

  • float get_pixel_size()

精灵上一个像素宽度的大小，以 3D 缩放。

int render_priority = 0 🔗

  • void set_render_priority(value: int)

  • int get_render_priority()

设置该精灵的渲染优先级。优先级高的物体将被排序在优先级低的物体前面。

注意：仅在 alpha_cut 为 ALPHA_CUT_DISABLED（默认值）时适用。

注意：仅适用于透明物体的排序。这不会影响透明物体相对于不透明物体的排序方式。这是因为不透明对象不被排序，而透明对象则从后往前排序（取决于优先级）。

bool shaded = false 🔗

如果为 true，则 Environment 中的 Light3D 对该精灵有影响。

TextureFilter texture_filter = 3 🔗

纹理过滤标志。可选项见 TextureFilter。

注意：线性过滤可能导致边缘的显示问题，对不透明纹理尤为明显。要避免这个问题，请使用具有透明边缘或边缘颜色一致的纹理。

bool transparent = true 🔗

如果为 true，纹理的透明度和不透明度用于使精灵的这些部分不可见。

方法说明

TriangleMesh generate_triangle_mesh() const 🔗

返回一个 TriangleMesh，其中精灵的顶点遵循它的当前配置（例如它的 axis 和 pixel_size）。

bool get_draw_flag(flag: DrawFlags) const 🔗

返回指定标志的值。

Rect2 get_item_rect() const 🔗

返回表示此精灵的矩形。

void set_draw_flag(flag: DrawFlags, enabled: bool) 🔗

如果 true，则指定的标志将被启用。标志列表见 DrawFlags。