Work in progress
Godot documentation is being updated to reflect the latest changes in version
4.0
. Some documentation pages may
still state outdated information. This banner will tell you if you're reading one of such pages.
The contents of this page are up to date. If you can still find outdated information, please open an issue.
CanvasItem¶
Base class of anything 2D.
Description¶
Base class of anything 2D. Canvas items are laid out in a tree; children inherit and extend their parent's transform. CanvasItem is extended by Control for anything GUI-related, and by Node2D for anything related to the 2D engine.
Any CanvasItem can draw. For this, queue_redraw is called by the engine, then NOTIFICATION_DRAW will be received on idle time to request 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 also be hidden, which will also hide its children. It provides many ways to change parameters such as modulation (for itself and its children) and self modulation (only for itself), as well as its blend mode.
Ultimately, a transform notification can be requested, which will notify the node that its global position changed in case the parent tree changed.
Note: Unless otherwise specified, all methods that have angle parameters must have angles specified as radians. To convert degrees to radians, use @GlobalScope.deg_to_rad.
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), LineBreakFlag brk_flags=3, JustificationFlag jst_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), LineBreakFlag brk_flags=3, JustificationFlag jst_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), JustificationFlag jst_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), JustificationFlag jst_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. 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.
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
The rendering layers in which this CanvasItem responds to Light2D nodes.
Material material
The material applied to textures on this CanvasItem.
Color modulate = Color(1, 1, 1, 1)
The color applied to textures on this CanvasItem.
Color self_modulate = Color(1, 1, 1, 1)
The color applied to textures on this CanvasItem. This is not inherited by children CanvasItems.
bool show_behind_parent = false
If true
, the object draws behind its parent.
TextureFilter texture_filter = 0
void set_texture_filter ( TextureFilter value )
TextureFilter get_texture_filter ( )
The texture filtering mode to use on this CanvasItem.
TextureRepeat texture_repeat = 0
void set_texture_repeat ( TextureRepeat value )
TextureRepeat get_texture_repeat ( )
The texture repeating mode to use on this CanvasItem.
bool top_level = false
If true
, this CanvasItem will not inherit its transform from parent CanvasItems. Its draw order will also be changed to make it draw on top of other CanvasItems that do not have top_level set to true
. The CanvasItem will effectively act as if it was placed as a child of a bare Node.
bool use_parent_material = false
If true
, the parent CanvasItem's material property is used as this one's material.
int visibility_layer = 1
The rendering layer in which this CanvasItem is rendered by Viewport nodes. A Viewport will render a CanvasItem if it and all its parents share a layer with the Viewport's canvas cull mask.
bool visible = true
If true
, this CanvasItem is drawn. The node is only visible if all of its antecedents are visible as well (in other words, is_visible_in_tree must return true
).
Note: For controls that inherit Popup, the correct way to make them visible is to call one of the multiple popup*()
functions instead.
bool y_sort_enabled = false
If true
, child nodes with the lowest Y position are drawn before those with a higher Y position. If false
, Y-sorting is disabled. Y-sorting only affects children that inherit from CanvasItem.
You can nest nodes with Y-sorting. Child Y-sorted nodes are sorted in the same space as the parent Y-sort. This feature allows you to organize a scene better or divide it into multiple ones without changing your scene tree.
bool z_as_relative = true
If true
, the node's Z index is relative to its parent's Z index. If this node's Z index is 2 and its parent's effective Z index is 3, then this node's effective Z index will be 2 + 3 = 5.
int z_index = 0
Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others. Must be between RenderingServer.CANVAS_ITEM_Z_MIN and RenderingServer.CANVAS_ITEM_Z_MAX (inclusive).
Note: Changing the Z index of a Control only affects the drawing order, not the order in which input events are handled. This can be useful to implement certain UI animations, e.g. a menu where hovered items are scaled and should overlap others.
Method Descriptions¶
void _draw ( ) virtual
Called when CanvasItem has been requested to redraw (after queue_redraw is called, either manually or by the engine).
Corresponds to the NOTIFICATION_DRAW notification in Object._notification.
void draw_animation_slice ( float animation_length, float slice_begin, float slice_end, float offset=0.0 )
Subsequent drawing commands will be ignored unless they fall within the specified animation slice. This is a faster way to implement animations that loop on background rather than redrawing constantly.
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 )
Draws an unfilled arc between the given angles with a uniform color
and width
and optional antialiasing (supported only for positive width
). The larger the value of point_count
, the smoother the curve. See also draw_circle.
If width
is negative, then the arc is drawn using RenderingServer.PRIMITIVE_LINE_STRIP. This means that when the CanvasItem is scaled, the arc will remain thin. If this behavior is not desired, then pass a positive width
like 1.0
.
The arc is drawn from start_angle
towards the value of end_angle
so in clockwise direction if start_angle < end_angle
and counter-clockwise otherwise. Passing the same angles but in reversed order will produce the same arc. If absolute difference of start_angle
and end_angle
is greater than @GDScript.TAU radians, then a full circle arc is drawn (i.e. arc will not overlap itself).
void draw_char ( Font font, Vector2 pos, String char, int font_size=16, Color modulate=Color(1, 1, 1, 1) ) const
Draws a string first character using a custom font.
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
Draws a string first character outline using a custom font.
void draw_circle ( Vector2 position, float radius, Color color )
Draws a colored, filled circle. See also draw_arc, draw_polyline and draw_polygon.
void draw_colored_polygon ( PackedVector2Array points, Color color, PackedVector2Array uvs=PackedVector2Array(), Texture2D texture=null )
Draws a colored polygon of any number of points, convex or concave. Unlike draw_polygon, a single color must be specified for the whole polygon.
void draw_dashed_line ( Vector2 from, Vector2 to, Color color, float width=-1.0, float dash=2.0, bool aligned=true )
Draws a dashed line from a 2D point to another, with a given color and width. See also draw_multiline and draw_polyline.
If width
is negative, then a two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the line parts will remain thin. If this behavior is not desired, then pass a positive width
like 1.0
.
void draw_end_animation ( )
After submitting all animations slices via draw_animation_slice, this function can be used to revert drawing to its default state (all subsequent drawing commands will be visible). If you don't care about this particular use case, usage of this function after submitting the slices is not required.
void draw_lcd_texture_rect_region ( Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate=Color(1, 1, 1, 1) )
Draws a textured rectangle region of the font texture with LCD subpixel anti-aliasing at a given position, optionally modulated by a color.
Texture is drawn using the following blend operation, blend mode of the CanvasItemMaterial is ignored:
dst.r = texture.r * modulate.r * modulate.a +