Up to date
This page is up to date for Godot 4.1
.
If you still find outdated information, please open an issue.
CanvasItem¶
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¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
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 |
|
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 |
|
get_canvas ( ) const |
|
get_canvas_item ( ) const |
|
get_canvas_transform ( ) const |
|
get_global_mouse_position ( ) const |
|
get_global_transform ( ) const |
|
get_global_transform_with_canvas ( ) const |
|
get_local_mouse_position ( ) const |
|
get_screen_transform ( ) const |
|
get_transform ( ) const |
|
get_viewport_rect ( ) const |
|
get_viewport_transform ( ) const |
|
get_visibility_layer_bit ( int layer ) const |
|
get_world_2d ( ) const |
|
void |
hide ( ) |
is_local_transform_notification_enabled ( ) const |
|
is_transform_notification_enabled ( ) const |
|
is_visible_in_tree ( ) const |
|
make_canvas_position_local ( Vector2 screen_point ) const |
|
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.
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.