CanvasGroup — C# API

class CanvasGroupReckfellSharpInherits Entity2D

Merges several 2D nodes into a single draw operation.

Child CanvasItem nodes of a CanvasGroup are drawn as a single object. It allows to e.g. draw overlapping translucent 2D nodes without causing the overlapping sections to be more opaque than intended (set the CanvasItem.SelfModulate property on the CanvasGroup to achieve this effect). Note: The CanvasGroup uses a custom shader to read from the backbuffer to draw its children. Assigning a Material to the CanvasGroup overrides the built-in shader. To duplicate the behavior of the built-in shader in a custom Shader, use the following:

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;
}

Note: Since CanvasGroup and CanvasItem.ClipChildren both utilize the backbuffer, children of a CanvasGroup who have their CanvasItem.ClipChildren set to anything other than CanvasItem.ClipChildrenMode.Disabled will not function correctly.

Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.

Constructors1

CanvasGroupConstructor

# CanvasGroup

C#
public CanvasGroup();

Properties3

ClearMarginProperty

# ClearMargin

C#
public float ClearMargin { get; set; }

Sets the size of the margin used to expand the clearing rect of this CanvasGroup. This expands the area of the backbuffer that will be used by the CanvasGroup. A smaller margin will reduce the area of the backbuffer used which can increase performance, however if CanvasGroup.UseMipmaps is enabled, a small margin may result in mipmap errors at the edge of the CanvasGroup. Accordingly, this should be left as small as possible, but should be increased if artifacts appear along the edges of the canvas group.

FitMarginProperty

# FitMargin

C#
public float FitMargin { get; set; }

Sets the size of a margin used to expand the drawable rect of this CanvasGroup. The size of the CanvasGroup is determined by fitting a rect around its children then expanding that rect by CanvasGroup.FitMargin. This increases both the backbuffer area used and the area covered by the CanvasGroup both of which can reduce performance. This should be kept as small as possible and should only be expanded when an increased size is needed (e.g. for custom shader effects).

UseMipmapsProperty

# UseMipmaps

C#
public bool UseMipmaps { get; set; }

If true, calculates mipmaps for the backbuffer before drawing the CanvasGroup so that mipmaps can be used in a custom ShaderMaterial attached to the CanvasGroup. Generating mipmaps has a performance cost so this should not be enabled unless required.

Methods6

GetClearMarginfloat

# GetClearMargin

C#
public float GetClearMargin();

Returns float

GetFitMarginfloat

# GetFitMargin

C#
public float GetFitMargin();

Returns float

IsUsingMipmapsbool

# IsUsingMipmaps

C#
public bool IsUsingMipmaps();

Returns bool

SetClearMarginvoid

# SetClearMargin

C#
public void SetClearMargin(float clearMargin);

Parameters
Name	Type	Default
`clearMargin`	`float`	—

SetFitMarginvoid

# SetFitMargin

C#
public void SetFitMargin(float fitMargin);

Parameters
Name	Type	Default
`fitMargin`	`float`	—

SetUseMipmapsvoid

# SetUseMipmaps

C#
public void SetUseMipmaps(bool useMipmaps);

Parameters
Name	Type	Default
`useMipmaps`	`bool`	—