Up to date

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

CanvasGroup

继承： Node2D < CanvasItem < Node < Object

将若干 2D 节点合并至单次绘制操作。

描述

CanvasGroup 的所有子 CanvasItem 节点会作为一个单独的对象绘制。它允许在不混合的情况下绘制重叠的半透明 2D 节点（设置 CanvasGroup 的 CanvasItem.self_modulate 属性来实现这一效果）。

注意：CanvasGroup 使用一个自定义着色器从后台缓冲区读取以绘制其子节点。为 CanvasGroup 指定一个 Material 会覆盖内置着色器。要在自定义 Shader 中复制内置着色器的行为，请使用以下方法：

shader_type canvas_item;
render_mode unshaded;

uniform sampler2D screen_texture : hint_screen_texture, repeat_disable, filter_nearest;

void fragment() {
    vec4 c = textureLod(screen_texture, SCREEN_UV, 0.0);

    if (c.a > 0.0001) {
        c.rgb /= c.a;
    }

    COLOR *= c;
}

注意：由于 CanvasGroup 和 CanvasItem.clip_children 都使用后台缓冲区，因此 CanvasGroup 的子级如果将其 CanvasItem.clip_children 设置为 CanvasItem.CLIP_CHILDREN_DISABLED 以外的其他值将无法正常工作。

属性

float	clear_margin	10.0
float	fit_margin	10.0
bool	use_mipmaps	false

---

属性说明

float clear_margin = 10.0

• void set_clear_margin ( float value )

• float get_clear_margin ( )

设置用于扩展该 CanvasGroup 清除矩形的边距大小。会对该 CanvasGroup 所使用的后台缓冲的区域进行扩展。边距较小时可以减少后台缓冲的区域大小，从而提升性能，但如果启用了 use_mipmaps，较小的边距可能在该 CanvasGroup 边缘造成 mipmap 错误。因此，这个值应该尽量调小，但是如果画布组的边缘出现问题，就应该将其调大。

---

float fit_margin = 10.0

• void set_fit_margin ( float value )

• float get_fit_margin ( )

设置用于扩展该 CanvasGroup 绘图矩形的边距大小。确定该 CanvasGroup 大小的方法是：首先框定子节点的矩形区域，然后将该矩形按照 fit_margin 进行扩展。会增大该 CanvasGroup 所使用的后台缓冲的区域，也会增大该 CanvasGroup 所覆盖的面积，两者都会降低性能。这个值应该尽量调小，仅在需要时调大（例如自定义着色器效果）。

---

bool use_mipmaps = false

• void set_use_mipmaps ( bool value )

• bool is_using_mipmaps ( )

如果为 true，则会在绘制该 CanvasGroup 之前为其后台缓冲计算 mipmap，附加到该 CanvasGroup 的自定义 ShaderMaterial 就可以使用 mipmap。Mipmap 的生成会造成性能消耗，所以应在必要时才启用。