CanvasItem

继承： Node < Object

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), oversampling: float = 0.0) 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), oversampling: float = 0.0) 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_ellipse(position: Vector2, major: float, minor: float, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false)
void	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	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, oversampling: float = 0.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, oversampling: float = 0.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, oversampling: float = 0.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, oversampling: float = 0.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() 🔗

当该节点隐藏时发出，即不再在树中可见（见 is_visible_in_tree()）。

item_rect_changed() 🔗

当 CanvasItem 的边界（位置或大小）发生变化，或者发生可能影响这些边界的操作（例如更改 Sprite2D.texture）时发出。

visibility_changed() 🔗

在 CanvasItem 的可见性改变时发射，这种改变或是因为其自身的 visible 属性发生了变化，或是因为其在树中的可见性发生了变化（见 is_visible_in_tree()）。

该信号在相关的 NOTIFICATION_VISIBILITY_CHANGED 通知之后发出。

枚举

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

纹理不会重复。在纹理范围之外采样会导致边缘像素“拉伸”。你可以通过确保在纹理两侧各有一个 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

该节点用作遮罩，不进行绘制。遮罩基于该节点的 Alpha 通道：保留不透明像素，丢弃透明像素，半透明像素根据不透明度混合。子节点受到该节点绘制区域的裁剪。

ClipChildrenMode CLIP_CHILDREN_AND_DRAW = 2

该节点用作遮罩，也会进行绘制。遮罩基于该节点的 Alpha 通道：保留不透明像素，丢弃透明像素，半透明像素根据不透明度混合。子节点受到该节点绘制区域的裁剪。

ClipChildrenMode CLIP_CHILDREN_MAX = 3

代表 ClipChildrenMode 枚举的大小。

常量

NOTIFICATION_TRANSFORM_CHANGED = 2000 🔗

is_transform_notification_enabled() 为 true 时，节点的全局变换发生改变时收到的通知。另见 set_notify_transform() 和 get_transform()。

注意：Camera2D、CollisionObject2D 等许多画布项会自动启用此功能以确保正常运行。

NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 35 🔗

is_local_transform_notification_enabled() 为 true 时，节点的变换发生改变时收到的通知。父级 Node2D 的变换发生改变时不会收到该通知。另见 set_notify_local_transform()。

注意：Camera2D、CollisionShape2D 等许多画布项会自动启用此功能以确保正常运行。

NOTIFICATION_DRAW = 30 🔗

要求绘制该 CanvasItem（见 _draw()）。

NOTIFICATION_VISIBILITY_CHANGED = 31 🔗

节点的可见性发生改变时收到的通知（见 visible 和 is_visible_in_tree()）。

该通知会在相关 visibility_changed 信号之前收到。

NOTIFICATION_ENTER_CANVAS = 32 🔗

该 CanvasItem 已进入画布。

NOTIFICATION_EXIT_CANVAS = 33 🔗

该 CanvasItem 已退出画布。

该通知会以反向顺序发送。

NOTIFICATION_WORLD_2D_CHANGED = 36 🔗

该 CanvasItem 注册至新的 World2D 时收到的通知（见 get_world_2d()）。

属性说明

ClipChildrenMode clip_children = 0 🔗

void set_clip_children_mode(value: ClipChildrenMode)
ClipChildrenMode get_clip_children_mode()

该节点作为遮罩对子节点进行裁剪的模式。

注意：裁剪的节点无法嵌套，也不能位于 CanvasGroup 中。如果该节点的祖先节点裁剪了它的子级，或者祖先节点是 CanvasGroup，那么这个节点的裁剪模式应当设为 CLIP_CHILDREN_DISABLED，从而避免意外行为。

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 不同。

注意：内部子节点也不受这个属性的影响（见 Node.add_child() 方法的 include_internal 参数）。内置节点的内部子节点包括 ColorPicker 中的滑块、TabContainer 中的选项卡栏等。

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 纹理的重复模式。它会影响在纹理范围之外采样时发生的情况，例如，设置比纹理大的 Sprite2D.region_rect 或在纹理外部分配 Polygon2D UV 点。

注意：TextureRect 不受 texture_repeat 的影响，因为它使用自己的纹理重复实现。

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

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.

bool visible = true 🔗

void set_visible(value: bool)
bool is_visible()

如果为 true，则允许绘制该 CanvasItem。实际是否对该 CanvasItem 进行绘制取决于该节点的所有 CanvasItem 祖级节点的可见性。换句话说：该 CanvasItem 只有在 is_visible_in_tree() 返回 true，并且所有 CanvasItem 祖级节点都至少与这个 CanvasItem 共享一个 visibility_layer。

注意：对于继承了 Popup 的控件，使其可见的正确方法是调用多个 popup*() 函数之一。

bool y_sort_enabled = false 🔗

void set_y_sort_enabled(value: bool)
bool is_y_sort_enabled()

如果为 true，则该节点及其子 CanvasItem 节点中 Y 位置较高的节点会渲染在 Y 位置较低的节点的前面。如果为 false，则该节点及其子 CanvasItem 节点会按照场景树的顺序正常渲染。

如果父节点（“A”）启用了 Y 排序，而子节点（“B”）没有启用，那么子节点（“B”）会进行排序，但它自己的子节点（“C1”“C2”等）会渲染在与子节点（“B”）相同的 Y 位置。这样你就可以在不修改场景树的前提下组织场景的渲染顺序了。

只有 z_index 相同的节点才会互相进行排序。

bool z_as_relative = true 🔗

void set_z_as_relative(value: bool)
bool is_z_relative()

如果为 true，则该节点的最终 Z 索引是相对于父节点的 Z 索引而言的。

例如 z_index 为 2、父节点的最终 Z 索引为 3，那么该节点的最终 Z 索引就是 5（2 + 3）。

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 之间（含两端）。

注意：Z 索引不会影响 CanvasItem 节点的处理顺序和输入事件的处理顺序。Control 节点尤其需要注意这一点。

方法说明

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

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 @GDScript.TAU radians, then a full circle arc is drawn (i.e. arc will not overlap itself).

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

使用自定义字体绘制字符串中的第一个字符。如果 oversampling 大于零则会用作字体过采样系数，否则使用视口的过采样设置。pos 定义在局部空间。

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

使用自定义字体绘制字符串中第一个字符的轮廓。如果 oversampling 大于零则会用作字体过采样系数，否则使用视口的过采样设置。pos 定义在局部空间。

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

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.

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

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 点到另一个点绘制一条虚线。from 位置和 to 位置定义在局部空间。另见 draw_line()、draw_multiline() 和 draw_polyline()。

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

dash 是每一段的长度，单位为像素，段与段之间的留空使用相同的长度。如果 aligned 为 true，则可能会缩短第一段和最后一段的长度，使得虚线的两端精确地落在 from 和 to 所定义的位置。aligned 为 true 时虚线两端始终是对称的。如果 aligned 为 false，则每一段的长度都相同，但是虚线长度无法被段长度整除时，末尾可能看上去不完整。aligned 为 false 时只会绘制完整的段。

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

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

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

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.

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

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 @GDScript.TAU radians, then a full ellipse is drawn (i.e. arc will not overlap itself).

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

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.

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

使用给定的颜色和宽度，从一个 2D 点到另一个点绘制一条直线。它可以选择抗锯齿。from 位置和 to 位置定义在局部空间。另见 draw_dashed_line()、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)) 🔗

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.

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

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.

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, oversampling: float = 0.0) const 🔗

使用 font 字体分若干行绘制 text 文本，以局部空间中的 pos 作为左上角。文本颜色会与 modulate 相乘。如果 width 大于等于 0，则文本超出该宽度的部分会被裁剪。如果 oversampling 大于零则会用作字体过采样系数，否则使用视口的过采样设置。

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, oversampling: float = 0.0) const 🔗

使用 font 字体分若干行绘制 text 文本的轮廓，以局部空间中的 pos 作为左上角。文本颜色会与 modulate 相乘。如果 width 大于等于 0，则文本超出该宽度的部分会被裁剪。如果 oversampling 大于零则会用作字体过采样系数，否则使用视口的过采样设置。

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

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.

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

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

使用一致的 color 和 width 以及可选的抗锯齿（仅支持正 width ），绘制相互连接的线段。points 数组定义在局部空间。绘制大量线条时，这比使用单独的 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 的索引，即每条线段填充的都是在两个端点之间颜色的渐变色。points 数组定义在局部空间。绘制大量线段时，这种方法比使用 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) 🔗

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.

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

绘制一个矩形。如果 filled 为 true，则矩形将使用指定的 color 填充。如果 filled 为 false，则矩形将被绘制为具有指定的 color 和 width 的笔划。rect 使用局部空间指定。另见 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, oversampling: float = 0.0) const 🔗

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)

DrawString(ThemeDB.FallbackFont, new Vector2(64, 64), "Hello world", HorizontalAlignment.Left, -1, ThemeDB.FallbackFontSize);