Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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 的生成会造成性能消耗，所以应在必要时才启用。