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

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. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled).

TextureFilter TEXTURE_FILTER_LINEAR = 2

The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled).

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 3

The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter is true). This makes the texture look pixelated from up close, and smooth from a distance.

Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to Camera2D zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels.

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 4

The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter is true). This makes the texture look smooth from up close, and smooth from a distance.

Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to Camera2D zoom or sprite scaling), 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 and blends between 2 mipmaps (or uses the nearest mipmap if ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter is true) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. 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 in this case.

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC = 6

The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter is true) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. 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 in this case.

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.