Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

CanvasItem

继承： Node < Object

派生： Control, Node2D

2D 空间中所有对象的抽象基类。

描述

2D 空间中所有对象的抽象基类。画布项目以树状排列；子节点继承并扩展其父节点的变换。CanvasItem 由 Control 扩展为 GUI 相关的节点，由 Node2D 扩展为 2D 游戏对象。

任何 CanvasItem 都可以进行绘图。绘图时，引擎会调用 queue_redraw，然后 NOTIFICATION_DRAW 就会在空闲时被接收到以请求重绘。因此，画布项目不需要每一帧都重绘，这显著提升了性能。这个类还提供了几个用于在 CanvasItem 上绘图的函数（见 draw_* 函数）。不过这些函数都只能在 _draw 及其对应的 Object._notification 或连接到 draw 的方法内使用。

画布项目在其画布层上是按树状顺序绘制的。默认情况下，子项目位于其父项目的上方，因此根 CanvasItem 将被画在所有项目的后面。这种行为可以针对每个画布项目进行更改。

CanvasItem 可以隐藏，隐藏时也会隐藏其子项目。通过调整 CanvasItem 的各种其它属性，你还可以调制它的颜色（通过 modulate 或 self_modulate）、更改 Z 索引、混合模式等。

请注意，变换、调制、可见性等属性只会传播至直属的 CanvasItem 子节点。如果中间有 Node、AnimationPlayer 等非 CanvasItem 节点，那么更深层 CanvasItem 的位置和 modulate 链就是独立的了。另见 top_level。

教程

属性

ClipChildrenMode	clip_children	`0`
int	light_mask	`1`
Material	material
Color	modulate	`Color(1, 1, 1, 1)`
Color	self_modulate	`Color(1, 1, 1, 1)`
bool	show_behind_parent	`false`
TextureFilter	texture_filter	`0`
TextureRepeat	texture_repeat	`0`
bool	top_level	`false`
bool	use_parent_material	`false`
int	visibility_layer	`1`
bool	visible	`true`
bool	y_sort_enabled	`false`
bool	z_as_relative	`true`
int	z_index	`0`

方法

void	_draw() virtual
void	draw_animation_slice(animation_length: float, slice_begin: float, slice_end: float, offset: float = 0.0)
void	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	draw_char(font: Font, pos: Vector2, char: String, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1)) const
void	draw_char_outline(font: Font, pos: Vector2, char: String, font_size: int = 16, size: int = -1, modulate: Color = Color(1, 1, 1, 1)) const
void	draw_circle(position: Vector2, radius: float, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false)
void	draw_colored_polygon(points: PackedVector2Array, color: Color, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null)
void	draw_dashed_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, dash: float = 2.0, aligned: bool = true, antialiased: bool = false)
void	draw_end_animation()
void	draw_lcd_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1))
void	draw_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, antialiased: bool = false)
void	draw_mesh(mesh: Mesh, texture: Texture2D, transform: Transform2D = Transform2D(1, 0, 0, 1, 0, 0), modulate: Color = Color(1, 1, 1, 1))
void	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	draw_multiline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false)
void	draw_multiline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false)
void	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: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const
void	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: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const
void	draw_multimesh(multimesh: MultiMesh, texture: Texture2D)
void	draw_polygon(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null)
void	draw_polyline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false)
void	draw_polyline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false)
void	draw_primitive(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array, texture: Texture2D = null)
void	draw_rect(rect: Rect2, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false)
void	draw_set_transform(position: Vector2, rotation: float = 0.0, scale: Vector2 = Vector2(1, 1))
void	draw_set_transform_matrix(xform: Transform2D)
void	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: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const
void	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: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const
void	draw_style_box(style_box: StyleBox, rect: Rect2)
void	draw_texture(texture: Texture2D, position: Vector2, modulate: Color = Color(1, 1, 1, 1))
void	draw_texture_rect(texture: Texture2D, rect: Rect2, tile: bool, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false)
void	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	force_update_transform()
RID	get_canvas() const
RID	get_canvas_item() const
CanvasLayer	get_canvas_layer_node() const
Transform2D	get_canvas_transform() const
Vector2	get_global_mouse_position() const
Transform2D	get_global_transform() const
Transform2D	get_global_transform_with_canvas() const
Variant	get_instance_shader_parameter(name: StringName) const
Vector2	get_local_mouse_position() const
Transform2D	get_screen_transform() const
Transform2D	get_transform() const
Rect2	get_viewport_rect() const
Transform2D	get_viewport_transform() const
bool	get_visibility_layer_bit(layer: int) const
World2D	get_world_2d() const
void	hide()
bool	is_local_transform_notification_enabled() const
bool	is_transform_notification_enabled() const
bool	is_visible_in_tree() const
Vector2	make_canvas_position_local(viewport_point: Vector2) const
InputEvent	make_input_local(event: InputEvent) const
void	move_to_front()
void	queue_redraw()
void	set_instance_shader_parameter(name: StringName, value: Variant)
void	set_notify_local_transform(enable: bool)
void	set_notify_transform(enable: bool)
void	set_visibility_layer_bit(layer: int, enabled: bool)
void	show()

信号

draw() 🔗

当该 CanvasItem 必须重绘时发出，发生在相关的 NOTIFICATION_DRAW 通知之后，调用 _draw 之前。

注意：延迟连接无法使用 draw_* 方法进行绘制。

hidden() 🔗

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

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

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

枚举

enum TextureFilter: 🔗

TextureFilter TEXTURE_FILTER_PARENT_NODE = 0

该 CanvasItem 将从其父级继承过滤器。

TextureFilter TEXTURE_FILTER_NEAREST = 1

纹理过滤仅从最近的像素读取。这使得纹理从近距离看是像素化的，从远处看是颗粒状的（由于多级渐远纹理没有被采样）。

TextureFilter TEXTURE_FILTER_LINEAR = 2

纹理过滤在最近的 4 个像素之间进行混合。这使得纹理从近处看起来很平滑，从远处看起来却有颗粒感（由于多级渐远纹理没有被采样）。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 3

纹理过滤从最近的像素读取并在最近的 2 个多级渐远纹理之间进行混合（或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 为 true，则使用最近的多级渐远纹理）。这使得纹理从近处看起来像素化，从远处看起来平滑。

将此用于可能以低缩放查看的非像素艺术纹理（例如，由于 Camera2D 缩放或精灵缩放），因为多级渐远纹理对于平滑小于屏幕像素的像素很重要。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 4

纹理过滤在最近的 4 个像素和最近的 2 个多级渐远纹理之间进行混合（或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 为 true，则使用最近的多级渐远纹理）。这使得纹理从近处看起来平滑，从远处看起来也平滑。

将此用于可能以低缩放查看的非像素艺术纹理（例如，由于 Camera2D 缩放或精灵缩放），因为多级渐远纹理对于平滑小于屏幕像素的像素很重要。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC = 5

纹理过滤从最近的像素读取并根据表面和相机视图之间的角度在 2 个多级渐远纹理之间进行混合（或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 为 true，则使用最近的多级渐远纹理）。这使得纹理从近处看起来像素化，从远处看起来平滑。各向异性过滤提高了几乎与相机位于一条线的表面上的纹理质量，但速度稍慢。各向异性过滤级别可以通过调整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 来改变。

注意：该纹理过滤在 2D 项目中很少有用。TEXTURE_FILTER_NEAREST_WITH_MIPMAPS 在这种情况下通常更合适。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC = 6

纹理过滤在最近的 4 个像素之间进行混合，并基于表面与相机视图之间的角度在 2 个多级渐远纹理之间进行混合（或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter 为 true，则使用最近的多级渐远纹理）。这使得纹理从近处看起来平滑，从远处看起来也平滑。各向异性过滤提高了几乎与相机位于一条线的表面上的纹理质量，但速度稍慢。各向异性过滤级别可以通过调整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 来改变。

注意：该纹理过滤在 2D 项目中很少有用。TEXTURE_FILTER_LINEAR_WITH_MIPMAPS 在这种情况下通常更合适。

TextureFilter TEXTURE_FILTER_MAX = 7

代表 TextureFilter 枚举的大小。

enum TextureRepeat: 🔗

TextureRepeat TEXTURE_REPEAT_PARENT_NODE = 0

该 CanvasItem 将从其父级继承过滤器。

TextureRepeat TEXTURE_REPEAT_DISABLED = 1

纹理不会重复。

TextureRepeat TEXTURE_REPEAT_ENABLED = 2

纹理将正常重复。

TextureRepeat TEXTURE_REPEAT_MIRROR = 3

纹理将以 2×2 平铺模式重复，其中偶数位置的元素会被镜像。

TextureRepeat TEXTURE_REPEAT_MAX = 4

代表 TextureRepeat 枚举的大小。

enum ClipChildrenMode: 🔗

ClipChildrenMode CLIP_CHILDREN_DISABLED = 0

子级绘制在父级之上，不会被裁剪。

ClipChildrenMode CLIP_CHILDREN_ONLY = 1

父级仅用于裁剪目的。子级被裁剪到父级的可见区域，不绘制父级。

ClipChildrenMode CLIP_CHILDREN_AND_DRAW = 2

父级用于裁剪子级，但在将子级剪裁到其可见区域之前，父级也像往常一样绘制在子级下方。

ClipChildrenMode CLIP_CHILDREN_MAX = 3

代表 ClipChildrenMode 枚举的大小。

常量

NOTIFICATION_TRANSFORM_CHANGED = 2000 🔗

该 CanvasItem 的全局变换已更改。只有在通过 set_notify_transform 启用时，才会收到这个通知。

NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 35 🔗

该 CanvasItem 的局部变换已更改。只有在通过 set_notify_local_transform 启用时，才会收到这个通知。

NOTIFICATION_DRAW = 30 🔗

要求绘制该 CanvasItem（见 _draw）。

NOTIFICATION_VISIBILITY_CHANGED = 31 🔗

该 CanvasItem 的可见性已更改。

NOTIFICATION_ENTER_CANVAS = 32 🔗

该 CanvasItem 已进入画布。

NOTIFICATION_EXIT_CANVAS = 33 🔗

该 CanvasItem 已退出画布。

NOTIFICATION_WORLD_2D_CHANGED = 36 🔗

该 CanvasItem 的活动 World2D 已更改。

属性说明

ClipChildrenMode clip_children = 0 🔗

void set_clip_children_mode(value: ClipChildrenMode)
ClipChildrenMode get_clip_children_mode()

Allows the current node to clip child nodes, essentially acting as a mask.

Note: Clipping nodes cannot be nested or placed within CanvasGroups. 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.

int light_mask = 1 🔗

void set_light_mask(value: int)
int get_light_mask()

该 CanvasItem 的渲染层，用于响应 Light2D 节点。

Material material 🔗

void set_material(value: Material)
Material get_material()

应用于这个 CanvasItem 的材质。

Color modulate = Color(1, 1, 1, 1) 🔗

void set_modulate(value: Color)
Color get_modulate()

应用于这个 CanvasItem 的颜色。这个属性会影响子级 CanvasItem，与只会影响节点自身的 self_modulate 不同。

Color self_modulate = Color(1, 1, 1, 1) 🔗

void set_self_modulate(value: Color)
Color get_self_modulate()

应用于这个 CanvasItem 的颜色。这个属性不会影响子级 CanvasItem，与会同时影响节点自身和子级的 modulate 不同。

注意：内部子节点（例如 ColorPicker 中的滑块、TabContainer 中的选项卡栏）也不受这个属性的影响（见 Node.get_child 等类似方法的 include_internal 参数）。

bool show_behind_parent = false 🔗

void set_draw_behind_parent(value: bool)
bool is_draw_behind_parent_enabled()

如果为 true，则对象在其父对象后面绘制。

TextureFilter texture_filter = 0 🔗

void set_texture_filter(value: TextureFilter)
TextureFilter get_texture_filter()

在该 CanvasItem 上使用的纹理过滤模式。

TextureRepeat texture_repeat = 0 🔗

void set_texture_repeat(value: TextureRepeat)
TextureRepeat get_texture_repeat()

在该 CanvasItem 上使用的纹理重复模式。

bool top_level = false 🔗

void set_as_top_level(value: bool)
bool is_set_as_top_level()

如果为 true，则该 CanvasItem 不会继承父级 CanvasItem 的变换。它的绘制顺序也会发生改变，会在其他没有将 top_level 设置为 true 的 CanvasItem 之上绘制。效果和把该 CanvasItem 作为裸 Node 的子级一样。

bool use_parent_material = false 🔗

void set_use_parent_material(value: bool)
bool get_use_parent_material()

如果为 true，则将父级 CanvasItem 的 material 属性用作此项的材质。

int visibility_layer = 1 🔗

void set_visibility_layer(value: int)
int get_visibility_layer()

Viewport 节点渲染该 CanvasItem 时所使用的渲染层。只有 CanvasItem 及其所有父级均与 Viewport 的画布剔除遮罩有交集，该 Viewport 才会渲染此 CanvasItem。

bool visible = true 🔗

void set_visible(value: bool)
bool is_visible()

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.

bool y_sort_enabled = false 🔗

void set_y_sort_enabled(value: bool)
bool is_y_sort_enabled()

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.

bool z_as_relative = true 🔗

void set_z_as_relative(value: bool)
bool is_z_relative()

如果为 true，节点的 Z 索引是相对于它的父节点的 Z 索引而言的。如果这个节点的 Z 索引是 2，它的父节点的实际 Z 索引是 3，那么这个节点的实际 Z 索引将是 2 + 3 = 5。

int z_index = 0 🔗

void set_z_index(value: int)
int get_z_index()

控制节点的渲染顺序。具有较高 Z 索引的节点将显示在其他节点的前面。必须在 RenderingServer.CANVAS_ITEM_Z_MIN 和 RenderingServer.CANVAS_ITEM_Z_MAX之间（包含）。

注意：改变 Control 的 Z 索引只影响绘图顺序，不影响处理输入事件的顺序。可用于实现某些 UI 动画，例如对处于悬停状态的菜单项进行缩放，此时会与其他内容重叠。

方法说明

void _draw() virtual 🔗

当 CanvasItem 被请求重绘时调用（手动调用或者引擎调用 queue_redraw 之后）。

对应于 Object._notification 中的 NOTIFICATION_DRAW 通知。

void draw_animation_slice(animation_length: float, slice_begin: float, slice_end: float, offset: float = 0.0) 🔗

后续的绘制命令将被忽略，除非它们位于指定的动画切片内。这是实现在背景上循环而不是不断重绘的动画的更快方法。

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

使用一个 uniform color 和 width 以及可选的抗锯齿（仅支持正 width ），在给定的角度之间绘制一条未填充的弧线。point_count 的值越大，该曲线越平滑。另见 draw_circle。

如果 width 为负，则它将被忽略，并使用 RenderingServer.PRIMITIVE_LINE_STRIP 绘制该弧线。这意味着当缩放 CanvasItem 时，弧线将保持细长。如果不需要此行为，请传递一个正的 width，如 1.0。

如果 start_angle < end_angle ，则圆弧是从 start_angle 朝向 end_angle 的值绘制的，即是顺时针方向；否则为逆时针方向。以相反的顺序传递相同的角度，将产生相同的弧线。如果 start_angle 和 end_angle 的差的绝对值大于 @GDScript.TAU 弧度，则绘制一个完整的圆弧（即弧线不会与自身重叠）。

void draw_char(font: Font, pos: Vector2, char: String, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1)) const 🔗

使用自定义字体绘制字符串的第一个字符。

void draw_char_outline(font: Font, pos: Vector2, char: String, font_size: int = 16, size: int = -1, modulate: Color = Color(1, 1, 1, 1)) const 🔗

使用自定义字体绘制字符串中第一个字符的轮廓。

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

绘制圆形。另见 draw_arc、draw_polyline、draw_polygon。

如果 filled 为 true，则圆形将使用指定的 color 填充。如果 filled 为 false，则圆形将被绘制为具有指定的 color 和 width 的笔划。

如果 width 为负，则将绘制两点图元而不是四点图元。这意味着当缩放 CanvasItem 时，线条将保持细长。如果不需要此行为，请传递一个正的 width，如 1.0。

如果 antialiased 为 true，则半透明的“羽毛”将附加到边界，使轮廓变得平滑。

注意：width 只有在 filled 为 false 时才有效。

void draw_colored_polygon(points: PackedVector2Array, color: Color, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = 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.

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.

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

使用给定的颜色和宽度，从一个 2D 点到另一个点绘制一条虚线。另见 draw_multiline 和 draw_polyline。

如果 width 为负，则将绘制一个两点图元而不是一个四点图元。这意味着当缩放 CanvasItem 时，线条部分将保持细长。如果不需要此行为，请传递一个正的 width，如 1.0。

如果 antialiased 为 true，则半透明的“羽毛”将附加到边界，使轮廓变得平滑。

注意：仅当 width 大于 0.0 时，antialiased 才有效。

void draw_end_animation() 🔗

通过 draw_animation_slice 提交所有动画切片后，该函数可以被用来将绘制恢复到其默认状态（所有后续绘制命令都将可见）。如果不关心这个特定用例，则不需要在提交切片后使用该函数。

void draw_lcd_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1)) 🔗

在给定的位置绘制一个带有 LCD 子像素抗锯齿的字体纹理的矩形区域，可以选择用一种颜色来调制。

纹理是通过以下混合操作绘制的，CanvasItemMaterial 的混合模式被忽略：

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

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

使用给定的颜色和宽度，从一个 2D 点到另一个点绘制一条直线。它可以选择抗锯齿。另请参阅 draw_multiline 和 draw_polyline。

如果 width 为负，则将绘制一个两点图元而不是一个四点图元。这意味着当缩放 CanvasItem 时，线条将保持细长。如果不需要此行为，请传递一个正的 width，如 1.0。

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

使用所提供的纹理以 2D 方式绘制一个 Mesh。相关文档请参阅 MeshInstance2D。

void 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) 🔗

在给定位置，绘制一条多通道有符号距离场纹理的纹理矩形区域，可以选择用一种颜色来调制。有关 MSDF 字体渲染的更多信息和注意事项，请参阅 FontFile.multichannel_signed_distance_field。

如果 outline 为正，则区域中像素的每个 Alpha 通道值都被设置为 outline 半径内真实距离的最大值。

pixel_range 的值应该与距离场纹理生成期间使用的值相同。

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

使用一致的宽度 width 和颜色 color 绘制多条断开的线段。points 数组中相邻的两个点定义一条线段，即第 i 条线段由端点 points[2 * i] 和 points[2 * i + 1] 组成。绘制大量线段时，这种方法比使用 draw_line 一条条画要快。要绘制相连的线段，请改用 draw_polyline。

如果 width 为负数，则会绘制由两个点组成的图元，不使用四个点组成的图元。此时如果 CanvasItem 发生缩放，则线段仍然会很细。如果不想要这样的行为，请传入 1.0 等正数 width。

注意：仅当 width 大于 0.0 时，antialiased 才有效。

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

使用一致的宽度 width 分段颜色绘制多条断开的线段。points 数组中相邻的两个点定义一条线段，即第 i 条线段由端点 points[2 * i] 和 points[2 * i + 1] 组成，使用的颜色为 colors[i]。绘制大量线段时，这种方法比使用 draw_line 一条条画要快。要绘制相连的线段，请改用 draw_polyline_colors。

如果 width 为负数，则会绘制由两个点组成的图元，不使用四个点组成的图元。此时如果 CanvasItem 发生缩放，则线段仍然会很细。如果不想要这样的行为，请传入 1.0 等正数 width。

注意：仅当 width 大于 0.0 时，antialiased 才有效。

void 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: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const 🔗

将 text 分成几行，并在 pos（左上角）处使用指定的 font 绘制文本。该文本的颜色将乘以 modulate。如果 width 大于等于 0，则当该文本超过指定宽度时将被裁剪。

void 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: BitField[LineBreakFlag] = 3, justification_flags: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const 🔗

将 text 分成几行，并在 pos（左上角）处使用指定的 font 绘制文本轮廓。该文本的颜色将乘以 modulate。如果 width 大于等于 0，则当该文本超过指定宽度时将被裁剪。

void draw_multimesh(multimesh: MultiMesh, texture: Texture2D) 🔗

用所提供的纹理以 2D 方式绘制一个 MultiMesh。相关文档请参考 MultiMeshInstance2D。

void draw_polygon(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null) 🔗

Draws a solid polygon of any number of points, convex or concave. Unlike draw_colored_polygon, each point's color can be changed individually. 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.

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

使用一致的 color 和 width 以及可选的抗锯齿（仅支持正 width ），绘制相互连接的线段。绘制大量线条时，这比使用单独的 draw_line 调用更快。要绘制不相连的的线段，请改用 draw_multiline。另见 draw_polygon。

如果 width 为负，则它将被忽略，并使用 RenderingServer.PRIMITIVE_LINE_STRIP 绘制该折线。这意味着当 CanvasItem 被缩放时，折线将保持为细线。如果不需要该行为，请传入一个正的 width，如 1.0。

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

绘制相连的线段，使用一致的宽度 width，按点指定颜色，还可以开启抗锯齿（仅支持正的 width）。将颜色与线段上的点匹配时，使用的是 points 和 colors 的索引，即每条线段填充的都是在两个端点之间颜色的渐变色。绘制大量线段时，这种方法比使用 draw_line 一条条画要快。要绘制不相连的线段，请改用 draw_multiline_colors。另见 draw_polygon。

如果 width 为负，则它将被忽略，并使用 RenderingServer.PRIMITIVE_LINE_STRIP 绘制该折线。这意味着当 CanvasItem 被缩放时，折线将保持为细线。如果不需要该行为，请传入一个正的 width，如 1.0。

void draw_primitive(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array, texture: Texture2D = null) 🔗

绘制自定义图元。1 个点的是个点，2 个点的是线段，3 个点的是三角形，4 个点的是四边形。如果没有指定点或者指定了超过 4 个点，则不会绘制任何东西，只会输出错误消息。另请参阅 draw_line、draw_polyline、draw_polygon、draw_rect。

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

绘制一个矩形。如果 filled 为 true，则矩形将使用指定的 color 填充。如果 filled 为 false，则矩形将被绘制为具有指定的 color 和 width 的笔划。另见 draw_texture_rect。

如果 width 为负，则将绘制一个两点图元而不是一个四点图元。这意味着当缩放 CanvasItem 时，线条将保持细长。如果不需要此行为，请传递一个正的 width，如 1.0。

如果 antialiased 为 true，则半透明的“羽毛”将附加到边界，使轮廓变得平滑。

注意：width 只有在 filled 为 false 时才有效。

注意：使用负 width 绘制的未填充矩形可能不会完美显示。例如，由于线条的重叠，角可能会缺失或变亮（对于半透明的 color）。

void draw_set_transform(position: Vector2, rotation: float = 0.0, scale: Vector2 = Vector2(1, 1)) 🔗

使用分量设置用于绘图的自定义变换。后续的绘制都会使用这个变换。

注意：FontFile.oversampling 不会考虑 scale。这意味着将位图字体及栅格化（非 MSDF）动态字体放大/缩小会产生模糊或像素化的结果。要让文本无论如何缩放都保持清晰，可以启用 MSDF 字体渲染，方法是启用 ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field（仅应用于默认项目字体），或者启用自定义 DynamicFont 的多通道带符号距离场导入选项。对于系统字体，可以在检查器中启用 SystemFont.multichannel_signed_distance_field。

void draw_set_transform_matrix(xform: Transform2D) 🔗

设置通过矩阵绘制时的自定义变换。此后绘制的任何东西都将被它变换。

void 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: BitField[JustificationFlag] = 3, direction: Direction = 0, orientation: Orientation = 0) const 🔗

Draws text using the specified font at the pos (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.

Example: Draw "Hello world", using the project's default 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 = ThemeDB.fallback_font
var default_font_size = ThemeDB.fallback_font_size
draw_string(default_font, Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, default_font_size)

// 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.
Font defaultFont = ThemeDB.FallbackFont;
int defaultFontSize = ThemeDB.FallbackFontSize;
DrawString(defaultFont, new Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, defaultFontSize);