Base class of anything 2D. Canvas items are laid out in a tree; children inherit and extend their parent's transform. godot.CanvasItem
is extended by godot.Control
for anything GUI-related, and by godot.Node2D
for anything related to the 2D engine.
Any godot.CanvasItem
can draw. For this, godot.CanvasItem.update
must be called, then godot.CanvasItem.notificationDraw
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 godot.CanvasItem
are provided (see draw_*
functions). However, they can only be used inside the godot.Object._Notification
, signal or godot.CanvasItem._Draw
virtual functions.
Canvas items are drawn in tree order. By default, children are on top of their parents so a root godot.CanvasItem
will be drawn behind everything. This behavior can be changed on a per-item basis.
A godot.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 @GDScript.deg2rad
.
Static variables
staticread onlyNOTIFICATION_TRANSFORM_CHANGED:Int
The godot.CanvasItem
's transform has changed. This notification is only received if enabled by godot.CanvasItem.setNotifyTransform
or godot.CanvasItem.setNotifyLocalTransform
.
Variables
selfModulate:Color
The color applied to textures on this godot.CanvasItem
. This is not inherited by children godot.CanvasItem
s.
useParentMaterial:Bool
If true
, the parent godot.CanvasItem
's godot.CanvasItem.material
property is used as this one's material.
visible:Bool
If true
, this godot.CanvasItem
is drawn. The node is only visible if all of its antecedents are visible as well (in other words, godot.CanvasItem.isVisibleInTree
must return true
).
Note: For controls that inherit godot.Popup
, the correct way to make them visible is to call one of the multiple popup*()
functions instead.
Methods
drawArc(center:Vector2, radius:Single, startAngle:Single, endAngle:Single, pointCount:Int, color:Color, ?width:Single, ?antialiased:Bool):Void
Draws a unfilled arc between the given angles. The larger the value of point_count
, the smoother the curve. See also godot.CanvasItem.drawCircle
.
Note: Line drawing is not accelerated by batching if antialiased
is true
.
Note: Due to how it works, built-in antialiasing will not look correct for translucent lines and may not work on certain platforms. As a workaround, install the [https://github.com/godot-extended-libraries/godot-antialiased-line2d](Antialiased Line2D) add-on then create an AntialiasedRegularPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing. 2D batching is also still supported with those antialiased lines.
drawChar(font:Font, position:Vector2, char:String, next:String, ?modulate:Color):Single
Draws a string character using a custom font. Returns the advance, depending on the character width and kerning with an optional next character.
Parameters:
modulate | If the parameter is null, then the default value is new Color(1, 1, 1, 1) |
---|
drawCircle(position:Vector2, radius:Single, color:Color):Void
Draws a colored, filled circle. See also godot.CanvasItem.drawArc
, godot.CanvasItem.drawPolyline
and godot.CanvasItem.drawPolygon
.
Note: Built-in antialiasing is not provided for godot.CanvasItem.drawCircle
. As a workaround, install the [https://github.com/godot-extended-libraries/godot-antialiased-line2d](Antialiased Line2D) add-on then create an AntialiasedRegularPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
drawColoredPolygon(points:Array<Vector2>, color:Color, ?uvs:Array<Vector2>, ?texture:Texture, ?normalMap:Texture, ?antialiased:Bool):Void
Draws a colored polygon of any amount of points, convex or concave. Unlike godot.CanvasItem.drawPolygon
, a single color must be specified for the whole polygon.
Note: Due to how it works, built-in antialiasing will not look correct for translucent polygons and may not work on certain platforms. As a workaround, install the [https://github.com/godot-extended-libraries/godot-antialiased-line2d](Antialiased Line2D) add-on then create an AntialiasedPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
Parameters:
uvs | If the parameter is null, then the default value is Array.Empty<Vector2>() |
---|
drawLine(from:Vector2, to:Vector2, color:Color, ?width:Single, ?antialiased:Bool):Void
Draws a line from a 2D point to another, with a given color and width. It can be optionally antialiased. See also godot.CanvasItem.drawMultiline
and godot.CanvasItem.drawPolyline
.
Note: Line drawing is not accelerated by batching if antialiased
is true
.
Note: Due to how it works, built-in antialiasing will not look correct for translucent lines and may not work on certain platforms. As a workaround, install the [https://github.com/godot-extended-libraries/godot-antialiased-line2d](Antialiased Line2D) add-on then create an AntialiasedLine2D node. That node relies on a texture with custom mipmaps to perform antialiasing. 2D batching is also still supported with those antialiased lines.
drawMesh(mesh:Mesh, texture:Texture, ?normalMap:Texture, ?transform:Transform2D, ?modulate:Color):Void
Draws a godot.Mesh
in 2D, using the provided texture. See godot.MeshInstance2D
for related documentation.
Parameters:
transform | If the parameter is null, then the default value is Transform2D.Identity |
---|---|
modulate | If the parameter is null, then the default value is new Color(1, 1, 1, 1) |
drawMultiline(points:Array<Vector2>, color:Color, ?width:Single, ?antialiased:Bool):Void
Draws multiple disconnected lines with a uniform color
. When drawing large amounts of lines, this is faster than using individual godot.CanvasItem.drawLine
calls. To draw interconnected lines, use godot.CanvasItem.drawPolyline
instead.
Note: width
and antialiased
are currently not implemented and have no effect. As a workaround, install the [https://github.com/godot-extended-libraries/godot-antialiased-line2d](Antialiased Line2D) add-on then create an AntialiasedLine2D node. That node relies on a texture with custom mipmaps to perform antialiasing. 2D batching is also still supported with those antialiased lines.
drawMultilineColors(points:Array<Vector2>, colors:Array<Color>, ?width:Single, ?antialiased:Bool):Void
Draws multiple disconnected lines with a uniform width
and segment-by-segment coloring. Colors assigned to line segments match by index between points
and colors
. When drawing large amounts of lines, this is faster than using individual godot.CanvasItem.drawLine
calls. To draw interconnected lines, use godot.CanvasItem.drawPolylineColors
instead.
Note: width
and antialiased
are currently not implemented and have no effect. As a workaround, install the [https://github.com/godot-extended-libraries/godot-antialiased-line2d](Antialiased Line2D) add-on then create an AntialiasedLine2D node. That node relies on a texture with custom mipmaps to perform antialiasing. 2D batching is also still supported with those antialiased lines.
drawMultimesh(multimesh:MultiMesh, texture:Texture, ?normalMap:Texture):Void
Draws a godot.MultiMesh
in 2D with the provided texture. See godot.MultiMeshInstance2D
for related documentation.
drawPolygon(points:Array<Vector2>, colors:Array<Color>, ?uvs:Array<Vector2>, ?texture:Texture, ?normalMap:Texture, ?antialiased:Bool):Void
Draws a solid polygon of any amount of points, convex or concave. Unlike godot.CanvasItem.drawColoredPolygon
, each point's color can be changed individually. See also godot.CanvasItem.drawPolyline
and godot.CanvasItem.drawPolylineColors
.
Note: Due to how it works, built-in antialiasing will not look correct for translucent polygons and may not work on certain platforms. As a workaround, install the [https://github.com/godot-extended-libraries/godot-antialiased-line2d](Antialiased Line2D) add-on then create an AntialiasedPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
Parameters:
uvs | If the parameter is null, then the default value is Array.Empty<Vector2>() |
---|
drawPolyline(points:Array<Vector2>, color:Color, ?width:Single, ?antialiased:Bool):Void
Draws interconnected line segments with a uniform color
and width
and optional antialiasing. When drawing large amounts of lines, this is faster than using individual godot.CanvasItem.drawLine
calls. To draw disconnected lines, use godot.CanvasItem.drawMultiline
instead. See also godot.CanvasItem.drawPolygon
.
Note: Due to how it works, built-in antialiasing will not look correct for translucent polygons and may not work on certain platforms. As a workaround, install the [https://github.com/godot-extended-libraries/godot-antialiased-line2d](Antialiased Line2D) add-on then create an AntialiasedPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
drawPolylineColors(points:Array<Vector2>, colors:Array<Color>, ?width:Single, ?antialiased:Bool):Void
Draws interconnected line segments with a uniform width
and segment-by-segment coloring, and optional antialiasing. Colors assigned to line segments match by index between points
and colors
. When drawing large amounts of lines, this is faster than using individual godot.CanvasItem.drawLine
calls. To draw disconnected lines, use godot.CanvasItem.drawMultilineColors
instead. See also godot.CanvasItem.drawPolygon
.
Note: Due to how it works, built-in antialiasing will not look correct for translucent polygons and may not work on certain platforms. As a workaround, install the [https://github.com/godot-extended-libraries/godot-antialiased-line2d](Antialiased Line2D) add-on then create an AntialiasedPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
drawPrimitive(points:Array<Vector2>, colors:Array<Color>, uvs:Array<Vector2>, ?texture:Texture, ?width:Single, ?normalMap:Texture):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. See also godot.CanvasItem.drawLine
, godot.CanvasItem.drawPolyline
, godot.CanvasItem.drawPolygon
, and godot.CanvasItem.drawRect
.
drawRect(rect:Rect2, color:Color, ?filled:Bool, ?width:Single, ?antialiased:Bool):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. If antialiased
is true
, the lines will attempt to perform antialiasing using OpenGL line smoothing.
Note: width
and antialiased
are only effective if filled
is false
.
Note: Due to how it works, built-in antialiasing will not look correct for translucent polygons and may not work on certain platforms. As a workaround, install the [https://github.com/godot-extended-libraries/godot-antialiased-line2d](Antialiased Line2D) add-on then create an AntialiasedPolygon2D node. That node relies on a texture with custom mipmaps to perform antialiasing.
drawSetTransform(position:Vector2, rotation:Single, scale:Vector2):Void
Sets a custom transform for drawing via components. Anything drawn afterwards will be transformed by this.
drawSetTransformMatrix(xform:Transform2D):Void
Sets a custom transform for drawing via matrix. Anything drawn afterwards will be transformed by this.
drawString(font:Font, position:Vector2, text:String, ?modulate:Color, ?clipW:Int):Void
Draws text
using the specified font
at the position
(bottom-left corner using the baseline of the font). The text will have its color multiplied by modulate
. If clip_w
is greater than or equal to 0, the text will be clipped if it exceeds the specified width.
Example using the default project font:
# If using this method in a script that redraws constantly, move the
# `default_font` declaration to a member variable assigned in `_ready()`
# so the Control is only created once.
var default_font = Control.new().get_font("font")
draw_string(default_font, Vector2(64, 64), "Hello world")
See also godot.Font.draw
.
Parameters:
modulate | If the parameter is null, then the default value is new Color(1, 1, 1, 1) |
---|
drawTexture(texture:Texture, position:Vector2, ?modulate:Color, ?normalMap:Texture):Void
Draws a texture at a given position.
Parameters:
modulate | If the parameter is null, then the default value is new Color(1, 1, 1, 1) |
---|
drawTextureRect(texture:Texture, rect:Rect2, tile:Bool, ?modulate:Color, ?transpose:Bool, ?normalMap:Texture):Void
Draws a textured rectangle at a given position, optionally modulated by a color. If transpose
is true
, the texture will have its X and Y coordinates swapped.
Parameters:
modulate | If the parameter is null, then the default value is new Color(1, 1, 1, 1) |
---|
drawTextureRectRegion(texture:Texture, rect:Rect2, srcRect:Rect2, ?modulate:Color, ?transpose:Bool, ?normalMap:Texture, ?clipUv:Bool):Void
Draws a textured rectangle region at a given position, optionally modulated by a color. If transpose
is true
, the texture will have its X and Y coordinates swapped.
Parameters:
modulate | If the parameter is null, then the default value is new Color(1, 1, 1, 1) |
---|
forceUpdateTransform():Void
Forces the transform to update. Transform changes in physics are not instant for performance reasons. Transforms are accumulated and then set. Use this if you need an up-to-date transform when doing physics operations.
getGlobalTransformWithCanvas():Transform2D
Returns the global transform matrix of this item in relation to the canvas.
hide():Void
Hide the godot.CanvasItem
if it's currently visible. This is equivalent to setting godot.CanvasItem.visible
to false
.
isLocalTransformNotificationEnabled():Bool
Returns true
if local transform notifications are communicated to children.
isSetAsToplevel():Bool
Returns true
if the node is set as top-level. See godot.CanvasItem.setAsToplevel
.
isTransformNotificationEnabled():Bool
Returns true
if global transform notifications are communicated to children.
isVisibleInTree():Bool
Returns true
if the node is present in the godot.SceneTree
, its godot.CanvasItem.visible
property is true
and all its antecedents are also visible. If any antecedent is hidden, this node will not be visible in the scene tree.
makeCanvasPositionLocal(screenPoint:Vector2):Vector2
Assigns screen_point
as this node's new local transform.
makeInputLocal(event:InputEvent):InputEvent
Transformations issued by event
's inputs are applied in local space instead of global space.
setAsToplevel(enable:Bool):Void
If enable
is true
, this godot.CanvasItem
will not inherit its transform from parent godot.CanvasItem
s. Its draw order will also be changed to make it draw on top of other godot.CanvasItem
s that are not set as top-level. The godot.CanvasItem
will effectively act as if it was placed as a child of a bare godot.Node
. See also godot.CanvasItem.isSetAsToplevel
.
setNotifyLocalTransform(enable:Bool):Void
If enable
is true
, children will be updated with local transform data.
setNotifyTransform(enable:Bool):Void
If enable
is true
, children will be updated with global transform data.
show():Void
Show the godot.CanvasItem
if it's currently hidden. This is equivalent to setting godot.CanvasItem.visible
to true
. For controls that inherit godot.Popup
, the correct way to make them visible is to call one of the multiple popup*()
functions instead.
update():Void
Queue the godot.CanvasItem
for update. godot.CanvasItem.notificationDraw
will be called on idle time to request redraw.