Up to date

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

CanvasItem

Inherits: Node < Object

Inherited By: Control, Node2D

Abstract base class for everything in 2D space.

Description

Abstract base class for everything in 2D space. Canvas items are laid out in a tree; children inherit and extend their parent's transform. CanvasItem is extended by Control for GUI-related nodes, and by Node2D for 2D game objects.

Any CanvasItem can draw. For this, queue_redraw is called by the engine, then NOTIFICATION_DRAW will be received on idle time to request a redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the CanvasItem are provided (see draw_* functions). However, they can only be used inside _draw, its corresponding Object._notification or methods connected to the draw signal.

Canvas items are drawn in tree order. By default, children are on top of their parents, so a root CanvasItem will be drawn behind everything. This behavior can be changed on a per-item basis.

A CanvasItem can be hidden, which will also hide its children. By adjusting various other properties of a CanvasItem, you can also modulate its color (via modulate or self_modulate), change its Z-index, blend mode, and more.

Tutorials

• Viewport and canvas transforms

• Custom drawing in 2D

• Audio Spectrum Demo

Properties

ClipChildrenMode	clip_children	0
int	light_mask	1
Material	material
Color	modulate	Color(1, 1, 1, 1)
Color	self_modulate	Color(1, 1, 1, 1)
bool	show_behind_parent	false
TextureFilter	texture_filter	0
TextureRepeat	texture_repeat	0
bool	top_level	false
bool	use_parent_material	false
int	visibility_layer	1
bool	visible	true
bool	y_sort_enabled	false
bool	z_as_relative	true
int	z_index	0

Methods

void	_draw ( ) virtual
void	draw_animation_slice ( float animation_length, float slice_begin, float slice_end, float offset=0.0 )
void	draw_arc ( Vector2 center, float radius, float start_angle, float end_angle, int point_count, Color color, float width=-1.0, bool antialiased=false )
void	draw_char ( Font font, Vector2 pos, String char, int font_size=16, Color modulate=Color(1, 1, 1, 1) ) const
void	draw_char_outline ( Font font, Vector2 pos, String char, int font_size=16, int size=-1, Color modulate=Color(1, 1, 1, 1) ) const
void	draw_circle ( Vector2 position, float radius, Color color )
void	draw_colored_polygon ( PackedVector2Array points, Color color, PackedVector2Array uvs=PackedVector2Array(), Texture2D texture=null )
void	draw_dashed_line ( Vector2 from, Vector2 to, Color color, float width=-1.0, float dash=2.0, bool aligned=true )
void	draw_end_animation ( )
void	draw_lcd_texture_rect_region ( Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate=Color(1, 1, 1, 1) )
void	draw_line ( Vector2 from, Vector2 to, Color color, float width=-1.0, bool antialiased=false )
void	draw_mesh ( Mesh mesh, Texture2D texture, Transform2D transform=Transform2D(1, 0, 0, 1, 0, 0), Color modulate=Color(1, 1, 1, 1) )
void	draw_msdf_texture_rect_region ( Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate=Color(1, 1, 1, 1), float outline=0.0, float pixel_range=4.0, float scale=1.0 )
void	draw_multiline ( PackedVector2Array points, Color color, float width=-1.0 )
void	draw_multiline_colors ( PackedVector2Array points, PackedColorArray colors, float width=-1.0 )
void	draw_multiline_string ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int max_lines=-1, Color modulate=Color(1, 1, 1, 1), BitField<LineBreakFlag> brk_flags=3, BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const
void	draw_multiline_string_outline ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int max_lines=-1, int size=1, Color modulate=Color(1, 1, 1, 1), BitField<LineBreakFlag> brk_flags=3, BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const
void	draw_multimesh ( MultiMesh multimesh, Texture2D texture )
void	draw_polygon ( PackedVector2Array points, PackedColorArray colors, PackedVector2Array uvs=PackedVector2Array(), Texture2D texture=null )
void	draw_polyline ( PackedVector2Array points, Color color, float width=-1.0, bool antialiased=false )
void	draw_polyline_colors ( PackedVector2Array points, PackedColorArray colors, float width=-1.0, bool antialiased=false )
void	draw_primitive ( PackedVector2Array points, PackedColorArray colors, PackedVector2Array uvs, Texture2D texture=null )
void	draw_rect ( Rect2 rect, Color color, bool filled=true, float width=-1.0 )
void	draw_set_transform ( Vector2 position, float rotation=0.0, Vector2 scale=Vector2(1, 1) )
void	draw_set_transform_matrix ( Transform2D xform )
void	draw_string ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, Color modulate=Color(1, 1, 1, 1), BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const
void	draw_string_outline ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int size=1, Color modulate=Color(1, 1, 1, 1), BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const
void	draw_style_box ( StyleBox style_box, Rect2 rect )
void	draw_texture ( Texture2D texture, Vector2 position, Color modulate=Color(1, 1, 1, 1) )
void	draw_texture_rect ( Texture2D texture, Rect2 rect, bool tile, Color modulate=Color(1, 1, 1, 1), bool transpose=false )
void	draw_texture_rect_region ( Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate=Color(1, 1, 1, 1), bool transpose=false, bool clip_uv=true )
void	force_update_transform ( )
RID	get_canvas ( ) const
RID	get_canvas_item ( ) const
Transform2D	get_canvas_transform ( ) const
Vector2	get_global_mouse_position ( ) const
Transform2D	get_global_transform ( ) const
Transform2D	get_global_transform_with_canvas ( ) const
Vector2	get_local_mouse_position ( ) const
Transform2D	get_screen_transform ( ) const
Transform2D	get_transform ( ) const
Rect2	get_viewport_rect ( ) const
Transform2D	get_viewport_transform ( ) const
bool	get_visibility_layer_bit ( int layer ) const
World2D	get_world_2d ( ) const
void	hide ( )
bool	is_local_transform_notification_enabled ( ) const
bool	is_transform_notification_enabled ( ) const
bool	is_visible_in_tree ( ) const
Vector2	make_canvas_position_local ( Vector2 screen_point ) const
InputEvent	make_input_local ( InputEvent event ) const
void	move_to_front ( )
void	queue_redraw ( )
void	set_notify_local_transform ( bool enable )
void	set_notify_transform ( bool enable )
void	set_visibility_layer_bit ( int layer, bool enabled )
void	show ( )

---

Signals

draw ( )

Emitted when the CanvasItem must redraw, after the related NOTIFICATION_DRAW notification, and before _draw is called.

Note: Deferred connections do not allow drawing through the draw_* methods.

---

hidden ( )

Emitted when becoming hidden.

---

item_rect_changed ( )

Emitted when the item's Rect2 boundaries (position or size) have changed, or when an action is taking place that may have impacted these boundaries (e.g. changing Sprite2D.texture).

---

visibility_changed ( )

Emitted when the visibility (hidden/visible) changes.

---

Enumerations

enum TextureFilter:

TextureFilter TEXTURE_FILTER_PARENT_NODE = 0

The CanvasItem will inherit the filter from its parent.

TextureFilter TEXTURE_FILTER_NEAREST = 1

The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering. Useful for pixel art.

TextureFilter TEXTURE_FILTER_LINEAR = 2

The texture filter blends between the nearest four pixels. Use this for most cases where you want to avoid a pixelated style.

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 3

The texture filter reads from the nearest pixel in the nearest mipmap. This is the fastest way to read from textures with mipmaps.

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 4

The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to Camera2D zoom), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels.

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC = 5

The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level.

Note: This texture filter is rarely useful in 2D projects. TEXTURE_FILTER_NEAREST_WITH_MIPMAPS is usually more appropriate.

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC = 6

The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level.

Note: This texture filter is rarely useful in 2D projects. TEXTURE_FILTER_LINEAR_WITH_MIPMAPS is usually more appropriate.

TextureFilter TEXTURE_FILTER_MAX = 7

Represents the size of the TextureFilter enum.

---

enum TextureRepeat:

TextureRepeat TEXTURE_REPEAT_PARENT_NODE = 0

The CanvasItem will inherit the filter from its parent.

TextureRepeat TEXTURE_REPEAT_DISABLED = 1

Texture will not repeat.

TextureRepeat TEXTURE_REPEAT_ENABLED = 2

Texture will repeat normally.

TextureRepeat TEXTURE_REPEAT_MIRROR = 3

Texture will repeat in a 2x2 tiled mode, where elements at even positions are mirrored.

TextureRepeat TEXTURE_REPEAT_MAX = 4

Represents the size of the TextureRepeat enum.

---

enum ClipChildrenMode:

ClipChildrenMode CLIP_CHILDREN_DISABLED = 0

Child draws over parent and is not clipped.

ClipChildrenMode CLIP_CHILDREN_ONLY = 1

Parent is used for the purposes of clipping only. Child is clipped to the parent's visible area, parent is not drawn.

ClipChildrenMode CLIP_CHILDREN_AND_DRAW = 2

Parent is used for clipping child, but parent is also drawn underneath child as normal before clipping child to its visible area.

ClipChildrenMode CLIP_CHILDREN_MAX = 3

Represents the size of the ClipChildrenMode enum.

---

Constants

NOTIFICATION_TRANSFORM_CHANGED = 2000

The CanvasItem's global transform has changed. This notification is only received if enabled by set_notify_transform.

NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 35

The CanvasItem's local transform has changed. This notification is only received if enabled by set_notify_local_transform.

NOTIFICATION_DRAW = 30

The CanvasItem is requested to draw (see _draw).

NOTIFICATION_VISIBILITY_CHANGED = 31

The CanvasItem's visibility has changed.

NOTIFICATION_ENTER_CANVAS = 32

The CanvasItem has entered the canvas.

NOTIFICATION_EXIT_CANVAS = 33

The CanvasItem has exited the canvas.

NOTIFICATION_WORLD_2D_CHANGED = 36

The CanvasItem's active World2D changed.

---

Property Descriptions

ClipChildrenMode clip_children = 0

• void set_clip_children_mode ( ClipChildrenMode value )

• ClipChildrenMode get_clip_children_mode ( )

Allows the current node to clip children nodes, essentially acting as a mask.

---

int light_mask = 1

• void set_light_mask (