Index · Object → Node → CanvasItem

CanvasItem

Abstract base class for everything in 2D space.

Inherited by (2): ControlNode2D
Class 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 on their canvas layer. 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.

Note that properties like transform, modulation, and visibility are only propagated to direct CanvasItem child nodes. If there is a non-CanvasItem node in between, like Node or AnimationPlayer, the CanvasItem nodes below will have an independent position and modulate chain. See also top_level.

Properties

var clip_children: CanvasItem.ClipChildrenMode = 0

The mode in which this node clips its children, acting as a mask.

Note: Clipping nodes cannot be nested or placed within a CanvasGroup. If an ancestor of this node clips its children or is a CanvasGroup, then this node's clip mode should be set to CLIP_CHILDREN_DISABLED to avoid unexpected behavior.

var light_mask: int = 1

The rendering layers in which this CanvasItem responds to Light2D nodes.

var material: Material

The material applied to this CanvasItem.

var modulate: Color = Color(1, 1, 1, 1)

The color applied to this CanvasItem. This property does affect child CanvasItems, unlike self_modulate which only affects the node itself.

var oversampling_with_scale: CanvasItem.OversamplingWithScale = 0

If enabled, oversampling for this CanvasItem is automatically adjusted with scale.

var self_modulate: Color = Color(1, 1, 1, 1)

The color applied to this CanvasItem. This property does not affect child CanvasItems, unlike modulate which affects both the node itself and its children.

Note: Internal children are also not affected by this property (see the include_internal parameter in Node.add_child()). For built-in nodes this includes sliders in ColorPicker, and the tab bar in TabContainer.

var show_behind_parent: bool = false

If true, this node draws behind its parent.

var texture_filter: CanvasItem.TextureFilter = 0

The filtering mode used to render this CanvasItem's texture(s).

var texture_repeat: CanvasItem.TextureRepeat = 0

The repeating mode used to render this CanvasItem's texture(s). It affects what happens when the texture is sampled outside its extents, for example by setting a Sprite2D.region_rect that is larger than the texture or assigning Polygon2D UV points outside the texture.

Note: TextureRect is not affected by texture_repeat, as it uses its own texture repeating implementation.

var top_level: bool = 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.

var use_parent_material: bool = false

If true, the parent CanvasItem's material is used as this node's material.

var visibility_layer: int = 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.

Note: A CanvasItem does not inherit its parents' visibility layers. This means that if a parent CanvasItem does not have all the same layers as its child, the child may not be visible even if both the parent and child have visible set to true. For example, if a parent has layer 1 and a child has layer 2, the child will not be visible in a Viewport with the canvas cull mask set to layer 1 or 2 (see Viewport.canvas_cull_mask). To ensure that both the parent and child are visible, the parent must have both layers 1 and 2, or the child must have top_level set to true.

var visible: bool = true

If true, this CanvasItem may be drawn. Whether this CanvasItem is actually drawn depends on the visibility of all of its CanvasItem ancestors. In other words: this CanvasItem will be drawn when is_visible_in_tree() returns true and all CanvasItem ancestors share at least one visibility_layer with this CanvasItem.

Note: For controls that inherit Popup, the correct way to make them visible is to call one of the multiple popup*() functions instead.

var y_sort_enabled: bool = false

If true, this and child CanvasItem nodes with a higher Y position are rendered in front of nodes with a lower Y position. If false, this and child CanvasItem nodes are rendered normally in scene tree order.

With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc.) render together on the same Y position as the child node ('B'). This allows you to organize the render order of a scene without changing the scene tree.

Nodes sort relative to each other only if they are on the same z_index.

var z_as_relative: bool = true

If true, this node's final Z index is relative to its parent's Z index.

For example, if z_index is 2 and its parent's final Z index is 3, then this node's final Z index will be 5 (2 + 3).

var z_index: int = 0

The order in which this node is drawn. 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: The Z index does not affect the order in which CanvasItem nodes are processed or the way input events are handled. This is especially important to keep in mind for Control nodes.

Inherited from Node (14)
var owner: Node

Methods

func _draw() -> void

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().

func draw_animation_slice(animation_length: float, slice_begin: float, slice_end: float, offset: float = 0.0) -> void

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.

func draw_arc(center: Vector2, radius: float, start_angle: float, end_angle: float, point_count: int, color: Color, width: float = -1.0, antialiased: bool = false) -> void

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. center is defined in local space. For elliptical arcs, see draw_ellipse_arc(). See also draw_circle().

If width is negative, it will be ignored and the arc will be 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 TAU radians, then a full circle arc is drawn (i.e. arc will not overlap itself).

func draw_char(font: Font, pos: Vector2, char: String, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) -> void

Draws a string first character using a custom font. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. pos is defined in local space.

func draw_char_outline(font: Font, pos: Vector2, char: String, font_size: int = 16, size: int = -1, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) -> void

Draws a string first character outline using a custom font. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. pos is defined in local space.

func draw_circle(position: Vector2, radius: float, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void

Draws a circle, with position defined in local space. See also draw_ellipse(), draw_arc(), draw_polyline(), and draw_polygon().

If filled is true, the circle will be filled with the color specified. If filled is false, the circle will be drawn as a stroke with the color and width specified.

If width is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

If antialiased is true, half transparent "feathers" will be attached to the boundary, making outlines smooth.

Note: width is only effective if filled is false.

func draw_colored_polygon(points: PackedVector2Array, color: Color, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null) -> void

Draws a colored polygon of any number of points, convex or concave. The points in the points array are defined in local space. Unlike draw_polygon(), a single color must be specified for the whole polygon.

Note: If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with Geometry2D.triangulate_polygon() and using draw_mesh(), draw_multimesh(), or RenderingServer.canvas_item_add_triangle_array().

Note: Styleboxes, textures, and meshes stored only inside local variables should not be used with this method in GDScript, because the drawing operation doesn't begin immediately once this method is called. In GDScript, when the function with the local variables ends, the local variables get destroyed before the rendering takes place.

func draw_dashed_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, dash: float = 2.0, aligned: bool = true, antialiased: bool = false) -> void

Draws a dashed line from a 2D point to another, with a given color and width. The from and to positions are defined in local space. See also draw_line(), 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.

dash is the length of each dash in pixels, with the gap between each dash being the same length. If aligned is true, the length of the first and last dashes may be shortened or lengthened to allow the line to begin and end at the precise points defined by from and to. Both ends are always symmetrical when aligned is true. If aligned is false, all dashes will have the same length, but the line may appear incomplete at the end due to the dash length not dividing evenly into the line length. Only full dashes are drawn when aligned is false.

If antialiased is true, half transparent "feathers" will be attached to the boundary, making outlines smooth.

Note: antialiased is only effective if width is greater than 0.0.

func draw_ellipse(position: Vector2, major: float, minor: float, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void

Draws an ellipse with semi-major axis major and semi-minor axis minor. See also draw_circle(), draw_ellipse_arc(), draw_polyline(), and draw_polygon().

If filled is true, the ellipse will be filled with the color specified. If filled is false, the ellipse will be drawn as a stroke with the color and width specified.

If width is negative, then two-point primitives will be drawn instead of four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

If antialiased is true, half transparent "feathers" will be attached to the boundary, making outlines smooth.

Note: width is only effective if filled is false.

func draw_ellipse_arc(center: Vector2, major: float, minor: float, start_angle: float, end_angle: float, point_count: int, color: Color, width: float = -1.0, antialiased: bool = false) -> void

Draws an unfilled elliptical 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. For circular arcs, see draw_arc(). See also draw_ellipse().

If width is negative, it will be ignored and the arc will be 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 TAU radians, then a full ellipse is drawn (i.e. arc will not overlap itself).

func draw_end_animation() -> void

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.

func draw_lcd_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1)) -> void

Draws a textured rectangle region of the font texture with LCD subpixel anti-aliasing at a given position, optionally modulated by a color. The rect is defined in local space.

Texture is drawn using the following blend operation, blend mode of the CanvasItemMaterial is ignored:

dst.r = texture.r * modulate.r * modulate.a + dst.r * (1.0 - texture.r * modulate.a);
dst.g = texture.g * modulate.g * modulate.a + dst.g * (1.0 - texture.g * modulate.a);
dst.b = texture.b * modulate.b * modulate.a + dst.b * (1.0 - texture.b * modulate.a);
dst.a = modulate.a + dst.a * (1.0 - modulate.a);

Note: Styleboxes, textures, and meshes stored only inside local variables should not be used with this method in GDScript, because the drawing operation doesn't begin immediately once this method is called. In GDScript, when the function with the local variables ends, the local variables get destroyed before the rendering takes place.

func draw_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, antialiased: bool = false) -> void

Draws a line from a 2D point to another, with a given color and width. It can be optionally antialiased. The from and to positions are defined in local space. See also draw_dashed_line(), draw_multiline(), and draw_polyline().

If width is negative, then a two-point primitive will be drawn instead of a four-point one. This means that when the CanvasItem is scaled, the line will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

func draw_mesh(mesh: Mesh, texture: Texture2D, transform: Transform2D = Transform2D(1, 0, 0, 1, 0, 0), modulate: Color = Color(1, 1, 1, 1)) -> void

Draws a Mesh in 2D, using the provided texture. See MeshInstance2D for related documentation. The transform is defined in local space.

Note: Styleboxes, textures, and meshes stored only inside local variables should not be used with this method in GDScript, because the drawing operation doesn't begin immediately once this method is called. In GDScript, when the function with the local variables ends, the local variables get destroyed before the rendering takes place.

func draw_msdf_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1), outline: float = 0.0, pixel_range: float = 4.0, scale: float = 1.0) -> void

Draws a textured rectangle region of the multichannel signed distance field texture at a given position, optionally modulated by a color. The rect is defined in local space. See FontFile.multichannel_signed_distance_field for more information and caveats about MSDF font rendering.

If outline is positive, each alpha channel value of pixel in region is set to maximum value of true distance in the outline radius.

Value of the pixel_range should the same that was used during distance field texture generation.

Note: Styleboxes, textures, and meshes stored only inside local variables should not be used with this method in GDScript, because the drawing operation doesn't begin immediately once this method is called. In GDScript, when the function with the local variables ends, the local variables get destroyed before the rendering takes place.

func draw_multiline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false) -> void

Draws multiple disconnected lines with a uniform width and color. Each line is defined by two consecutive points from points array in local space, i.e. i-th segment consists of points[2 * i], points[2 * i + 1] endpoints. When drawing large amounts of lines, this is faster than using individual draw_line() calls. To draw interconnected lines, use draw_polyline() instead.

If width is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

Note: antialiased is only effective if width is greater than 0.0.

func draw_multiline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false) -> void

Draws multiple disconnected lines with a uniform width and segment-by-segment coloring. Each segment is defined by two consecutive points from points array in local space and a corresponding color from colors array, i.e. i-th segment consists of points[2 * i], points[2 * i + 1] endpoints and has colors[i] color. When drawing large amounts of lines, this is faster than using individual draw_line() calls. To draw interconnected lines, use draw_polyline_colors() instead.

If width is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

Note: antialiased is only effective if width is greater than 0.0.

func draw_multiline_string(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, modulate: Color = Color(1, 1, 1, 1), brk_flags: TextServer.LineBreakFlag = 3, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void

Breaks text into lines and draws it using the specified font at the pos in local space (top-left corner). The text will have its color multiplied by modulate. If width is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

func draw_multiline_string_outline(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, size: int = 1, modulate: Color = Color(1, 1, 1, 1), brk_flags: TextServer.LineBreakFlag = 3, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void

Breaks text to the lines and draws text outline using the specified font at the pos in local space (top-left corner). The text will have its color multiplied by modulate. If width is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

func draw_multimesh(multimesh: MultiMesh, texture: Texture2D) -> void

Draws a MultiMesh in 2D with the provided texture. See MultiMeshInstance2D for related documentation.

Note: Styleboxes, textures, and meshes stored only inside local variables should not be used with this method in GDScript, because the drawing operation doesn't begin immediately once this method is called. In GDScript, when the function with the local variables ends, the local variables get destroyed before the rendering takes place.

func draw_polygon(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null) -> void

Draws a solid polygon of any number of points, convex or concave. Unlike draw_colored_polygon(), each point's color can be changed individually. The points array is defined in local space. See also draw_polyline() and draw_polyline_colors(). If you need more flexibility (such as being able to use bones), use RenderingServer.canvas_item_add_triangle_array() instead.

Note: If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with Geometry2D.triangulate_polygon() and using draw_mesh(), draw_multimesh(), or RenderingServer.canvas_item_add_triangle_array().

Note: Styleboxes, textures, and meshes stored only inside local variables should not be used with this method in GDScript, because the drawing operation doesn't begin immediately once this method is called. In GDScript, when the function with the local variables ends, the local variables get destroyed before the rendering takes place.

func draw_polyline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false) -> void

Draws interconnected line segments with a uniform color and width and optional antialiasing (supported only for positive width). The points array is defined in local space. When drawing large amounts of lines, this is faster than using individual draw_line() calls. To draw disconnected lines, use draw_multiline() instead. See also draw_polygon().

If width is negative, it will be ignored and the polyline will be drawn using RenderingServer.PRIMITIVE_LINE_STRIP. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

func draw_polyline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false) -> void

Draws interconnected line segments with a uniform width, point-by-point coloring, and optional antialiasing (supported only for positive width). Colors assigned to line points match by index between points and colors, i.e. each line segment is filled with a gradient between the colors of the endpoints. The points array is defined in local space. When drawing large amounts of lines, this is faster than using individual draw_line() calls. To draw disconnected lines, use draw_multiline_colors() instead. See also draw_polygon().

If width is negative, it will be ignored and the polyline will be drawn using RenderingServer.PRIMITIVE_LINE_STRIP. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

func draw_primitive(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array, texture: Texture2D = null) -> void

Draws a custom primitive. 1 point for a point, 2 points for a line, 3 points for a triangle, and 4 points for a quad. If 0 points or more than 4 points are specified, nothing will be drawn and an error message will be printed. The points array is defined in local space. See also draw_line(), draw_polyline(), draw_polygon(), and draw_rect().

Note: Styleboxes, textures, and meshes stored only inside local variables should not be used with this method in GDScript, because the drawing operation doesn't begin immediately once this method is called. In GDScript, when the function with the local variables ends, the local variables get destroyed before the rendering takes place.

func draw_rect(rect: Rect2, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void

Draws a rectangle. If filled is true, the rectangle will be filled with the color specified. If filled is false, the rectangle will be drawn as a stroke with the color and width specified. The rect is specified in local space. See also draw_texture_rect().

If width is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

If antialiased is true, half transparent "feathers" will be attached to the boundary, making outlines smooth.

Note: width is only effective if filled is false.

Note: Unfilled rectangles drawn with a negative width may not display perfectly. For example, corners may be missing or brighter due to overlapping lines (for a translucent color).

func draw_set_transform(position: Vector2, rotation: float = 0.0, scale: Vector2 = Vector2(1, 1)) -> void

Sets a custom local transform for drawing via components. Anything drawn afterwards will be transformed by this.

Note: FontFile.oversampling does not take scale into account. This means that scaling up/down will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated. To ensure text remains crisp regardless of scale, you can enable MSDF font rendering by enabling ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field (applies to the default project font only), or enabling Multichannel Signed Distance Field in the import options of a DynamicFont for custom fonts. On system fonts, SystemFont.multichannel_signed_distance_field can be enabled in the inspector.

func draw_set_transform_matrix(xform: Transform2D) -> void

Sets a custom local transform for drawing via matrix. Anything drawn afterwards will be transformed by this.

func draw_string(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void

Draws text using the specified font at the pos in local space (bottom-left corner using the baseline of the font). The text will have its color multiplied by modulate. If width is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

Example: Draw "Hello world", using the project's default font:

draw_string(ThemeDB.fallback_font, Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, ThemeDB.fallback_font_size)

See also Font.draw_string().

func draw_string_outline(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, size: int = 1, modulate: Color = Color(1, 1, 1, 1), justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void

Draws text outline using the specified font at the pos in local space (bottom-left corner using the baseline of the font). The text will have its color multiplied by modulate. If width is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

func draw_style_box(style_box: StyleBox, rect: Rect2) -> void

Draws a styled rectangle. The rect is defined in local space.

Note: Styleboxes, textures, and meshes stored only inside local variables should not be used with this method in GDScript, because the drawing operation doesn't begin immediately once this method is called. In GDScript, when the function with the local variables ends, the local variables get destroyed before the rendering takes place.

func draw_texture(texture: Texture2D, position: Vector2, modulate: Color = Color(1, 1, 1, 1)) -> void

Draws a texture at a given position. The position is defined in local space.

Note: Styleboxes, textures, and meshes stored only inside local variables should not be used with this method in GDScript, because the drawing operation doesn't begin immediately once this method is called. In GDScript, when the function with the local variables ends, the local variables get destroyed before the rendering takes place.

func draw_texture_rect(texture: Texture2D, rect: Rect2, tile: bool, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false) -> void

Draws a textured rectangle at a given position, optionally modulated by a color. The rect is defined in local space. If transpose is true, the texture will have its X and Y coordinates swapped. See also draw_rect() and draw_texture_rect_region().

Note: Styleboxes, textures, and meshes stored only inside local variables should not be used with this method in GDScript, because the drawing operation doesn't begin immediately once this method is called. In GDScript, when the function with the local variables ends, the local variables get destroyed before the rendering takes place.

func draw_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false, clip_uv: bool = true) -> void

Draws a textured rectangle from a texture's region (specified by src_rect) at a given position in local space, optionally modulated by a color. If transpose is true, the texture will have its X and Y coordinates swapped. See also draw_texture_rect().

Note: Styleboxes, textures, and meshes stored only inside local variables should not be used with this method in GDScript, because the drawing operation doesn't begin immediately once this method is called. In GDScript, when the function with the local variables ends, the local variables get destroyed before the rendering takes place.

func force_update_transform() -> void

Forces the node's transform to update. Fails if the node is not inside the tree. See also get_transform().

Note: For performance reasons, transform changes are usually accumulated and applied once at the end of the frame. The update propagates through CanvasItem children, as well. Therefore, use this method only when you need an up-to-date transform (such as during physics operations).

func get_canvas() -> RID

Returns the RID of the World2D canvas where this node is registered to, used by the RenderingServer.

func get_canvas_item() -> RID

Returns the internal canvas item RID used by the RenderingServer for this node.

func get_canvas_layer_node() -> CanvasLayer

Returns the CanvasLayer that contains this node, or null if the node is not in any CanvasLayer.

func get_canvas_transform() -> Transform2D

Returns the transform of this node, converted from its registered canvas's coordinate system to its viewport's coordinate system. See also Node.get_viewport().

func get_global_mouse_position() -> Vector2

Returns mouse cursor's global position relative to the CanvasLayer that contains this node.

Note: For screen-space coordinates (e.g. when using a non-embedded Popup), you can use DisplayServer.mouse_get_position().

func get_global_transform() -> Transform2D

Returns the global transform matrix of this item, i.e. the combined transform up to the topmost CanvasItem node. The topmost item is a CanvasItem that either has no parent, has non-CanvasItem parent or it has top_level enabled.

func get_global_transform_with_canvas() -> Transform2D

Returns the transform from the local coordinate system of this CanvasItem to the Viewports coordinate system.

func get_instance_shader_parameter(name: StringName) -> Variant

Get the value of a shader parameter as set on this instance.

func get_local_mouse_position() -> Vector2

Returns the mouse's position in this CanvasItem using the local coordinate system of this CanvasItem.

func get_screen_transform() -> Transform2D

Returns the transform of this CanvasItem in global screen coordinates (i.e. taking window position into account). Mostly useful for editor plugins.

Equivalent to get_global_transform_with_canvas() if the window is embedded (see Viewport.gui_embed_subwindows).

func get_transform() -> Transform2D

Returns the transform matrix of this CanvasItem.

func get_viewport_rect() -> Rect2

Returns this node's viewport boundaries as a Rect2. See also Node.get_viewport().

func get_viewport_transform() -> Transform2D

Returns the transform of this node, converted from its registered canvas's coordinate system to its viewport embedder's coordinate system. See also Viewport.get_final_transform() and Node.get_viewport().

func get_visibility_layer_bit(layer: int) -> bool

Returns true if the layer at the given index is set in visibility_layer.

func get_world_2d() -> World2D

Returns the World2D this node is registered to.

Usually, this is the same as this node's viewport (see Node.get_viewport() and Viewport.find_world_2d()).

func hide() -> void

Hide the CanvasItem if it's currently visible. This is equivalent to setting visible to false.

func is_local_transform_notification_enabled() -> bool

Returns true if the node receives NOTIFICATION_LOCAL_TRANSFORM_CHANGED whenever its local transform changes. This is enabled with set_notify_local_transform().

func is_transform_notification_enabled() -> bool

Returns true if the node receives NOTIFICATION_TRANSFORM_CHANGED whenever its global transform changes. This is enabled with set_notify_transform().

func is_visible_in_tree() -> bool

Returns true if the node is present in the SceneTree, its visible property is true and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is therefore not drawn (see _draw()).

Visibility is checked only in parent nodes that inherit from CanvasItem, CanvasLayer, and Window. If the parent is of any other type (such as Node, AnimationPlayer, or Node3D), it is assumed to be visible.

Note: This method does not take visibility_layer into account, so even if this method returns true, the node might end up not being rendered.

func make_canvas_position_local(viewport_point: Vector2) -> Vector2

Transforms viewport_point from the viewport's coordinates to this node's local coordinates.

For the opposite operation, use get_global_transform_with_canvas().

var viewport_point = get_global_transform_with_canvas() * local_point
func make_input_local(event: InputEvent) -> InputEvent

Returns a copy of the given event with its coordinates converted from global space to this CanvasItem's local space. If not possible, returns the same InputEvent unchanged.

func move_to_front() -> void

Moves this node below its siblings, usually causing the node to draw on top of its siblings. Does nothing if this node does not have a parent. See also Node.move_child().

func queue_redraw() -> void

Queues the CanvasItem to redraw. During idle time, if CanvasItem is visible, NOTIFICATION_DRAW is sent and _draw() is called. This only occurs once per frame, even if this method has been called multiple times.

func set_instance_shader_parameter(name: StringName, value: Variant) -> void

Set the value of a shader uniform for this instance only (per-instance uniform). See also ShaderMaterial.set_shader_parameter() to assign a uniform on all instances using the same ShaderMaterial.

Note: For a shader uniform to be assignable on a per-instance basis, it must be defined with instance uniform ... rather than uniform ... in the shader code.

Note: name is case-sensitive and must match the name of the uniform in the code exactly (not the capitalized name in the inspector).

func set_notify_local_transform(enable: bool) -> void

If true, the node will receive NOTIFICATION_LOCAL_TRANSFORM_CHANGED whenever its local transform changes.

Note: Many canvas items such as Bone2D or CollisionShape2D automatically enable this in order to function correctly.

func set_notify_transform(enable: bool) -> void

If true, the node will receive NOTIFICATION_TRANSFORM_CHANGED whenever its global transform changes.

Note: Many canvas items such as Camera2D or Light2D automatically enable this in order to function correctly.

func set_visibility_layer_bit(layer: int, enabled: bool) -> void

Set/clear individual bits on the rendering visibility layer. This simplifies editing this CanvasItem's visibility layer.

func show() -> void

Show the CanvasItem if it's currently hidden. This is equivalent to setting visible to true.

Note: For controls that inherit Popup, the correct way to make them visible is to call one of the multiple popup*() functions instead.

Inherited from Node (106)
func _enter_tree() -> void
func _exit_tree() -> void
func _input(event: InputEvent) -> void
func _physics_process(delta: float) -> void
func _process(delta: float) -> void
func _ready() -> void
func _shortcut_input(event: InputEvent) -> void
func _unhandled_input(event: InputEvent) -> void
func _unhandled_key_input(event: InputEvent) -> void
func add_child(node: Node, force_readable_name: bool = false, internal: Node.InternalMode = 0) -> void
func add_sibling(sibling: Node, force_readable_name: bool = false) -> void
func add_to_group(group: StringName, persistent: bool = false) -> void
func atr(message: String, context: StringName = "") -> String
func atr_n(message: String, plural_message: StringName, n: int, context: StringName = "") -> String
func can_process() -> bool
func duplicate(flags: int = 15) -> Node
func find_child(pattern: String, recursive: bool = true, owned: bool = true) -> Node
func find_children(pattern: String, type: String = "", recursive: bool = true, owned: bool = true) -> Node[]
func find_parent(pattern: String) -> Node
func get_child(idx: int, include_internal: bool = false) -> Node
func get_child_count(include_internal: bool = false) -> int
func get_children(include_internal: bool = false) -> Node[]
func get_groups() -> StringName[]
func get_index(include_internal: bool = false) -> int
func get_node(path: NodePath) -> Node
func get_orphan_node_ids() -> int[]
func get_parent() -> Node
func get_path() -> NodePath
func get_path_to(node: Node, use_unique_path: bool = false) -> NodePath
func get_window() -> Window
func has_node(path: NodePath) -> bool
func is_ancestor_of(node: Node) -> bool
func is_greater_than(node: Node) -> bool
func is_in_group(group: StringName) -> bool
func move_child(child_node: Node, to_index: int) -> void
func notify_deferred_thread_group(what: int) -> void
func notify_thread_safe(what: int) -> void
func print_orphan_nodes() -> void
func print_tree() -> void
func print_tree_pretty() -> void
func propagate_call(method: StringName, args: Array = [], parent_first: bool = false) -> void
func propagate_notification(what: int) -> void
func queue_free() -> void
func remove_child(node: Node) -> void
func remove_from_group(group: StringName) -> void
func reparent(new_parent: Node, keep_global_transform: bool = true) -> void
func replace_by(node: Node, keep_groups: bool = false) -> void
func request_ready() -> void
func rpc(method: StringName) -> Error
func rpc_config(method: StringName, config: Variant) -> void
func rpc_id(peer_id: int, method: StringName) -> Error
func set_deferred_thread_group(property: StringName, value: Variant) -> void
func set_display_folded(fold: bool) -> void
func set_editable_instance(node: Node, is_editable: bool) -> void
func set_multiplayer_authority(id: int, recursive: bool = true) -> void
func set_physics_process(enable: bool) -> void
func set_physics_process_internal(enable: bool) -> void
func set_process(enable: bool) -> void
func set_process_input(enable: bool) -> void
func set_process_internal(enable: bool) -> void
func set_process_shortcut_input(enable: bool) -> void
func set_process_unhandled_input(enable: bool) -> void
func set_scene_instance_load_placeholder(load_placeholder: bool) -> void
func set_thread_safe(property: StringName, value: Variant) -> void
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

signal 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.

signal hidden()

Emitted when this node becomes hidden, i.e. it's no longer visible in the tree (see is_visible_in_tree()).

signal item_rect_changed()

Emitted when the CanvasItem's boundaries (position or size) change, or when an action took place that may have affected these boundaries (e.g. changing Sprite2D.texture).

signal visibility_changed()

Emitted when the CanvasItem's visibility changes, either because its own visible property changed or because its visibility in the tree changed (see is_visible_in_tree()).

This signal is emitted after the related NOTIFICATION_VISIBILITY_CHANGED notification.

Inherited from Node (11)
signal child_entered_tree(node: Node)
signal child_exiting_tree(node: Node)
signal ready()
signal renamed()
signal replacing_by(node: Node)
signal tree_entered()
signal tree_exited()
signal tree_exiting()
Inherited from Object (2)

Enums & Constants

enum TextureFilter
TEXTURE_FILTER_PARENT_NODE = 0

The CanvasItem will inherit the filter from its parent.

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).

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).

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.

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.

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.

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.

TEXTURE_FILTER_MAX = 7

Represents the size of the TextureFilter enum.

enum TextureRepeat
TEXTURE_REPEAT_PARENT_NODE = 0

The CanvasItem will inherit the repeat mode from its parent.

TEXTURE_REPEAT_DISABLED = 1

The texture does not repeat. Sampling the texture outside its extents will result in "stretching" of the edge pixels. You can avoid this by ensuring a 1-pixel fully transparent border on each side of the texture.

TEXTURE_REPEAT_ENABLED = 2

The texture repeats when exceeding the texture's size.

TEXTURE_REPEAT_MIRROR = 3

The texture repeats when the exceeding the texture's size in a "2×2 tiled mode". Repeated textures at even positions are mirrored.

TEXTURE_REPEAT_MAX = 4

Represents the size of the TextureRepeat enum.

enum ClipChildrenMode
CLIP_CHILDREN_DISABLED = 0

Children are drawn over this node and are not clipped.

CLIP_CHILDREN_ONLY = 1

This node is used as a mask and is not drawn. The mask is based on this node's alpha channel: Opaque pixels are kept, transparent pixels are discarded, and semi-transparent pixels are blended in according to their opacity. Children are clipped to this node's drawn area.

CLIP_CHILDREN_AND_DRAW = 2

This node is used as a mask and is also drawn. The mask is based on this node's alpha channel: Opaque pixels are kept, transparent pixels are discarded, and semi-transparent pixels are blended in according to their opacity. Children are clipped to the parent's drawn area.

CLIP_CHILDREN_MAX = 3

Represents the size of the ClipChildrenMode enum.

enum OversamplingWithScale
OVERSAMPLING_WITH_SCALE_PARENT_NODE = 0

The CanvasItem will inherit the oversampling mode from its parent.

OVERSAMPLING_WITH_SCALE_DISABLED = 1

The oversampling is not affected by CanvasItem scale, and is equal to the Viewport oversampling.

OVERSAMPLING_WITH_SCALE_ENABLED = 2

The oversampling is a product of CanvasItem scale and Viewport oversampling.

OVERSAMPLING_WITH_SCALE_MAX = 3

Represents the size of the OversamplingWithScale enum.

const NOTIFICATION_TRANSFORM_CHANGED = 2000

Notification received when this node's global transform changes, if is_transform_notification_enabled() is true. See also set_notify_transform() and get_transform().

Note: Many canvas items such as Camera2D or CollisionObject2D automatically enable this in order to function correctly.

const NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 35

Notification received when this node's transform changes, if is_local_transform_notification_enabled() is true. This is not received when a parent Node2D's transform changes. See also set_notify_local_transform().

Note: Many canvas items such as Camera2D or CollisionShape2D automatically enable this in order to function correctly.

const NOTIFICATION_DRAW = 30

The CanvasItem is requested to draw (see _draw()).

const NOTIFICATION_VISIBILITY_CHANGED = 31

Notification received when this node's visibility changes (see visible and is_visible_in_tree()).

This notification is received before the related visibility_changed signal.

const NOTIFICATION_ENTER_CANVAS = 32

The CanvasItem has entered the canvas.

const NOTIFICATION_EXIT_CANVAS = 33

The CanvasItem has exited the canvas.

This notification is sent in reversed order.

const NOTIFICATION_WORLD_2D_CHANGED = 36

Notification received when this CanvasItem is registered to a new World2D (see get_world_2d()).