Table of Contents

Class CanvasLayer

A node used for independent rendering of objects within a 2D scene.

Inheritance
CanvasLayer
Derived

Remarks

CanvasItem-derived nodes that are direct or indirect children of a CanvasLayer will be drawn in that layer. The layer is a numeric index that defines the draw order. The default 2D scene renders with index 0, so a CanvasLayer with index -1 will be drawn below, and a CanvasLayer with index 1 will be drawn above. This order will hold regardless of the z_index of the nodes within each layer.

CanvasLayers can be hidden and they can also optionally follow the viewport. This makes them useful for HUDs like health bar overlays (on layers 1 and higher) or backgrounds (on layers -1 and lower).

Note: Embedded Windows are placed on layer 1024. CanvasItems on layers 1025 and higher appear in front of embedded windows.

Note: Each CanvasLayer is drawn on one specific Viewport and cannot be shared between multiple Viewports, see custom_viewport. When using multiple Viewports, for example in a split-screen game, you need create an individual CanvasLayer for each Viewport you want it to be drawn on.

See Also

Viewport and canvas transforms
Canvas layers
2D Dodge The Creeps Demo

Properties

custom_viewport

The custom Viewport node assigned to the CanvasLayer. If null, uses the default viewport instead.

var custom_viewport : Node

Property Value

Node

Remarks

  • void set_custom_viewport(Node value)
  • Node get_custom_viewport

follow_viewport_enabled

If enabled, the CanvasLayer stays in a fixed position on the screen. If disabled, the CanvasLayer maintains its position in world space.

Together with follow_viewport_scale, this can be used for a pseudo-3D effect.

var follow_viewport_enabled : bool = false

Property Value

bool

Remarks

  • void set_follow_viewport(bool value)
  • bool is_following_viewport

follow_viewport_scale

Scales the layer when using follow_viewport_enabled. Layers moving into the foreground should have increasing scales, while layers moving into the background should have decreasing scales.

var follow_viewport_scale : float = 1.0

Property Value

float

Remarks

  • void set_follow_viewport_scale(float value)
  • float get_follow_viewport_scale

layer

Layer index for draw order. Lower values are drawn behind higher values.

Note: If multiple CanvasLayers have the same layer index, CanvasItem children of one CanvasLayer are drawn behind the CanvasItem children of the other CanvasLayer. Which CanvasLayer is drawn in front is non-deterministic.

var layer : int = 1

Property Value

int

Remarks

  • void set_layer(int value)
  • int get_layer

offset

The layer's base offset.

var offset : Vector2 = Vector2(0, 0)

Property Value

Vector2

Remarks

rotation

The layer's rotation in radians.

var rotation : float = 0.0

Property Value

float

Remarks

  • void set_rotation(float value)
  • float get_rotation

scale

The layer's scale.

var scale : Vector2 = Vector2(1, 1)

Property Value

Vector2

Remarks

transform

The layer's transform.

var transform : Transform2D = Transform2D(1, 0, 0, 1, 0, 0)

Property Value

Transform2D

Remarks

visible

If false, any CanvasItem under this CanvasLayer will be hidden.

Unlike visible, visibility of a CanvasLayer isn't propagated to underlying layers.

var visible : bool = true

Property Value

bool

Remarks

  • void set_visible(bool value)
  • bool is_visible

Methods

get_canvas

Qualifiers: const

Returns the RID of the canvas used by this layer.

RID get_canvas

get_final_transform

Qualifiers: const

Returns the transform from the CanvasLayers coordinate system to the Viewports coordinate system.

Transform2D get_final_transform

hide

Hides any CanvasItem under this CanvasLayer. This is equivalent to setting visible to false.

void hide

show

Shows any CanvasItem under this CanvasLayer. This is equivalent to setting visible to true.

void show

Events

visibility_changed

Emitted when visibility of the layer is changed. See visible.

signal visibility_changed