godotengine · SlugFiller · Mar 10, 2023
@@ -5,24 +5,19 @@
 	</brief_description>
 	<description>
 		Child [CanvasItem] nodes of a [CanvasGroup] are drawn as a single object. It allows to e.g. draw overlapping translucent 2D nodes without blending (set [member CanvasItem.self_modulate] property of [CanvasGroup] to achieve this effect).
-		[b]Note:[/b] The [CanvasGroup] uses a custom shader to read from the backbuffer to draw its children. Assigning a [Material] to the [CanvasGroup] overrides the builtin shader. To duplicate the behavior of the builtin shader in a custom [Shader] use the following:
+		By default [CanvasGroup] multiplies its [member CanvasItem.self_modulate] with the color of its children. It is possible to set a custom blending for the children using a custom [Shader] with a [code]sampler2D[/code] with [code]hint_mask_texture[/code]. Doing so disables the default operation.
+		The following example only uses the alpha from the children, overriding their color:
 		[codeblock]
 		shader_type canvas_item;
-		render_mode unshaded;
 
-		uniform sampler2D screen_texture : hint_screen_texture, repeat_disable, filter_nearest;
+		uniform sampler2D mask_texture : hint_mask_texture, repeat_disable, filter_nearest;
 
 		void fragment() {
-		    vec4 c = textureLod(screen_texture, SCREEN_UV, 0.0);
+		    vec4 c = textureLod(mask_texture, SCREEN_UV, 0.0);
 
-		    if (c.a &gt; 0.0001) {
-		        c.rgb /= c.a;
-		    }
-
-		    COLOR *= c;
+		    COLOR.a *= c.a;
 		}
 		[/codeblock]
-		[b]Note:[/b] Since [CanvasGroup] and [member CanvasItem.clip_children] both utilize the backbuffer, children of a [CanvasGroup] who have their [member CanvasItem.clip_children] set to anything other than [constant CanvasItem.CLIP_CHILDREN_DISABLED] will not function correctly.
 	</description>
 	<tutorials>
 	</tutorials>

@@ -586,6 +586,21 @@
 	<members>
 		<member name="clip_children" type="int" setter="set_clip_children_mode" getter="get_clip_children_mode" enum="CanvasItem.ClipChildrenMode" default="0">
 			Allows the current node to clip child nodes, essentially acting as a mask.
+			When set to anything other than [constant CanvasItem.CLIP_CHILDREN_DISABLED] it is possible to set a custom blending for the masked children using a custom [Shader] with a [code]sampler2D[/code] with [code]hint_mask_texture[/code]. Doing so disables the default masking operation.
+			For example, the following multiplies the parent's color with that of its children:
+			[codeblock]
+			shader_type canvas_item;
+			render_mode blend_premul_alpha;
+
+			uniform sampler2D mask_texture : hint_mask_texture, repeat_disable, filter_nearest;
+
+			void fragment() {
+			    vec4 c = textureLod(mask_texture, SCREEN_UV, 0.0);
+
+			    COLOR.rgb *= COLOR.a;
+			    COLOR *= c;
+			}
+			[/codeblock]
 		</member>
 		<member name="light_mask" type="int" setter="set_light_mask" getter="get_light_mask" default="1">
 			The rendering layers in which this [CanvasItem] responds to [Light2D] nodes.
@@ -732,7 +747,10 @@
 		<constant name="CLIP_CHILDREN_AND_DRAW" value="2" enum="ClipChildrenMode">
 			Parent is used for clipping child, but parent is also drawn underneath child as normal before clipping child to its visible area.
 		</constant>
-		<constant name="CLIP_CHILDREN_MAX" value="3" enum="ClipChildrenMode">
+		<constant name="CLIP_CHILDREN_SUBTRACT" value="4" enum="ClipChildrenMode">
+			Child cuts hole into the parent, causing it to be transparent where the child is opaque. Child is not drawn.
+		</constant>
+		<constant name="CLIP_CHILDREN_MAX" value="5" enum="ClipChildrenMode">
 			Represents the size of the [enum ClipChildrenMode] enum.
 		</constant>
 	</constants>

@@ -5440,6 +5440,10 @@
 			Parent is used for clipping child, but parent is also drawn underneath child as normal before clipping child to its visible area.
 		</constant>
 		<constant name="CANVAS_GROUP_MODE_TRANSPARENT" value="3" enum="CanvasGroupMode">
+			The parent's color and alpha are multiplied with that of the child. An parent with no draw commands is interpreted as a fullscreen rectangle drawn in the self-modulation color.
+		</constant>
+		<constant name="CANVAS_GROUP_MODE_SUBTRACT" value="4" enum="CanvasGroupMode">
+			Child cuts hole into the parent, causing it to be transparent where the child is opaque. Child is not drawn.
 		</constant>
 		<constant name="CANVAS_LIGHT_MODE_POINT" value="0" enum="CanvasLightMode">
 			2D point light (see [PointLight2D]).

@@ -44,7 +44,10 @@
 		<constant name="SOURCE_ROUGHNESS" value="7" enum="Source">
 			Use the roughness buffer captured during the depth prepass. Only available when the normal-roughness buffer is available (i.e. in spatial shaders and in the forward_plus renderer).
 		</constant>
-		<constant name="SOURCE_MAX" value="8" enum="Source">
+		<constant name="SOURCE_MASK" value="8" enum="Source">
+			For [CanvasGroup] or [CanvasItem] with [member CanvasItem.clip_children] set to anything other than [constant CanvasItem.CLIP_CHILDREN_DISABLED], use a texture made from rendering all child items. If used, the default masking operation is disabled.
+		</constant>
+		<constant name="SOURCE_MAX" value="9" enum="Source">
 			Represents the size of the [enum Source] enum.
 		</constant>
 		<constant name="TYPE_DATA" value="0" enum="TextureType">

@@ -105,7 +105,10 @@
 		<constant name="SOURCE_NORMAL_ROUGHNESS" value="3" enum="TextureSource">
 			The texture source is the normal-roughness buffer from the depth prepass.
 		</constant>
-		<constant name="SOURCE_MAX" value="4" enum="TextureSource">
+		<constant name="SOURCE_MASK" value="4" enum="TextureSource">
+			For [CanvasGroup] or [CanvasItem] with [member CanvasItem.clip_children] set to anything other than [constant CanvasItem.CLIP_CHILDREN_DISABLED], the texture source is made from rendering all child items. If used, the default masking operation is disabled.
+		</constant>
+		<constant name="SOURCE_MAX" value="5" enum="TextureSource">
 			Represents the size of the [enum TextureSource] enum.
 		</constant>
 	</constants>