Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

CanvasItem

继承: Node < Object

派生: Control, Node2D

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

描述

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

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

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

CanvasItem 可以隐藏,隐藏时也会隐藏其子项目。通过调整 CanvasItem 的各种其它属性,你还可以调制它的颜色(通过 modulateself_modulate)、更改 Z 索引、混合模式等。

教程

属性

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 ( float animation_length, float slice_begin, float slice_end, float offset=0.0 )

void

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

void

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

void

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

void

draw_circle ( Vector2 position, float radius, Color color )

void

draw_colored_polygon ( PackedVector2Array points, Color color, PackedVector2Array uvs=PackedVector2Array(), Texture2D texture=null )

void

draw_dashed_line ( Vector2 from, Vector2 to, Color color, float width=-1.0, float dash=2.0, bool aligned=true )

void

draw_end_animation ( )

void

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

void

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

void

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

void

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

void

draw_multiline ( PackedVector2Array points, Color color, float width=-1.0 )

void

draw_multiline_colors ( PackedVector2Array points, PackedColorArray colors, float width=-1.0 )

void

draw_multiline_string ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int max_lines=-1, Color modulate=Color(1, 1, 1, 1), BitField<LineBreakFlag> brk_flags=3, BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const

void

draw_multiline_string_outline ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int max_lines=-1, int size=1, Color modulate=Color(1, 1, 1, 1), BitField<LineBreakFlag> brk_flags=3, BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const

void

draw_multimesh ( MultiMesh multimesh, Texture2D texture )

void

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

void

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

void

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

void

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

void

draw_rect ( Rect2 rect, Color color, bool filled=true, float width=-1.0 )

void

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

void

draw_set_transform_matrix ( Transform2D xform )

void

draw_string ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, Color modulate=Color(1, 1, 1, 1), BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const

void

draw_string_outline ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int size=1, Color modulate=Color(1, 1, 1, 1), BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const

void

draw_style_box ( StyleBox style_box, Rect2 rect )

void

draw_texture ( Texture2D texture, Vector2 position, Color modulate=Color(1, 1, 1, 1) )

void

draw_texture_rect ( Texture2D texture, Rect2 rect, bool tile, Color modulate=Color(1, 1, 1, 1), bool transpose=false )

void

draw_texture_rect_region ( Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate=Color(1, 1, 1, 1), bool transpose=false, bool clip_uv=true )

void

force_update_transform ( )

RID

get_canvas ( ) const

RID

get_canvas_item ( ) const

Transform2D

get_canvas_transform ( ) const

Vector2

get_global_mouse_position ( ) const

Transform2D

get_global_transform ( ) const

Transform2D

get_global_transform_with_canvas ( ) 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 ( int layer ) 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 ( Vector2 screen_point ) const

InputEvent

make_input_local ( InputEvent event ) const

void

move_to_front ( )

void

queue_redraw ( )

void

set_notify_local_transform ( bool enable )

void

set_notify_transform ( bool enable )

void

set_visibility_layer_bit ( int layer, bool enabled )

void

show ( )


信号

draw ( )

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

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


hidden ( )

当隐藏时发出。


item_rect_changed ( )

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


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_filtertrue,则使用最近的多级渐远纹理)。这使得纹理从近处看起来像素化,从远处看起来平滑。

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

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 4

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

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

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC = 5

纹理过滤从最近的像素读取并根据表面和相机视图之间的角度在 2 个多级渐远纹理之间进行混合(或者如果 ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filtertrue,则使用最近的多级渐远纹理)。这使得纹理从近处看起来像素化,从远处看起来平滑。各向异性过滤提高了几乎与相机位于一条线的表面上的纹理质量,但速度稍慢。各向异性过滤级别可以通过调整 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_filtertrue,则使用最近的多级渐远纹理)。这使得纹理从近处看起来平滑,从远处看起来也平滑。各向异性过滤提高了几乎与相机位于一条线的表面上的纹理质量,但速度稍慢。各向异性过滤级别可以通过调整 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

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

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

允许当前节点裁剪子节点,本质上是充当遮罩。


int light_mask = 1

  • void set_light_mask ( int value )

  • int get_light_mask ( )

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


Material material

应用于这个 CanvasItem 的材质。


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

  • void set_modulate ( Color value )

  • Color get_modulate ( )

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


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

  • void set_self_modulate ( Color value )

  • Color get_self_modulate ( )

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

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


bool show_behind_parent = false

  • void set_draw_behind_parent ( bool value )

  • bool is_draw_behind_parent_enabled ( )

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


TextureFilter texture_filter = 0

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


TextureRepeat texture_repeat = 0

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


bool top_level = false

  • void set_as_top_level ( bool value )

  • bool is_set_as_top_level ( )

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


bool use_parent_material = false

  • void set_use_parent_material ( bool value )

  • bool get_use_parent_material ( )

如果为 true,则将父级 CanvasItemmaterial 属性用作此项的材质。


int visibility_layer = 1

  • void set_visibility_layer ( int value )

  • int get_visibility_layer ( )

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


bool visible = true

  • void set_visible ( bool value )

  • bool is_visible ( )

如果为 true,这个 CanvasItem 被绘制。只有当它的所有父节点也可见时,该节点才是可见的(换句话说,is_visible_in_tree 必须返回 true)。

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


bool y_sort_enabled = false

  • void set_y_sort_enabled ( bool value )

  • bool is_y_sort_enabled ( )

如果为 true,则会在绘制 Y 位置最低的子节点之后再绘制 Y 位置较高的子节点。如果为 false,则禁用 Y 排序。Y 排序仅影响继承自 CanvasItem 的子节点。

可以将 Y 排序的节点进行嵌套。子级 Y 排序的节点,会与父级在同一空间中进行 Y 排序。此功能可以让你在不更改场景树的情况下,更好地组织场景,或者将场景分为多个场景。


bool z_as_relative = true

  • void set_z_as_relative ( bool value )

  • bool is_z_relative ( )

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


int z_index = 0

  • void set_z_index ( int value )

  • int get_z_index ( )

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

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


方法说明

void _draw ( ) virtual

CanvasItem 被请求重绘时调用(手动调用或者引擎调用 queue_redraw 之后)。

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


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

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


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

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

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

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


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

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


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

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


void draw_circle ( Vector2 position, float radius, Color color )

绘制彩色的实心圆。另见 draw_arcdraw_polylinedraw_polygon


void draw_colored_polygon ( PackedVector2Array points, Color color, PackedVector2Array uvs=PackedVector2Array(), Texture2D texture=null )

绘制一个由任意数量的点组成的彩色多边形,凸形或凹形。与 draw_polygon 不同,必须为整个多边形指定一个单一颜色。


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

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

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


void draw_end_animation ( )

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


void draw_lcd_texture_rect_region ( Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate=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 ( Vector2 from, Vector2 to, Color color, float width=-1.0, bool antialiased=false )

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

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


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

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


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

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

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

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


void draw_multiline ( PackedVector2Array points, Color color, float width=-1.0 )

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

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


void draw_multiline_colors ( PackedVector2Array points, PackedColorArray colors, float width=-1.0 )

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

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


void draw_multiline_string ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int max_lines=-1, Color modulate=Color(1, 1, 1, 1), BitField<LineBreakFlag> brk_flags=3, BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const

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


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

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


void draw_multimesh ( MultiMesh multimesh, Texture2D texture )

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


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

绘制一个由任意数量的点构成的实心多边形,凸形或凹形。与 draw_colored_polygon 不同,每个点的颜色都可以单独改变。另见 draw_polylinedraw_polyline_colors。如果你需要更大的自由度(例如能够使用骨骼),请改用 RenderingServer.canvas_item_add_triangle_array


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

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

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


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

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

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


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

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


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

绘制一个矩形。如果 filledtrue,则矩形将使用指定的 color 填充。如果 filledfalse,则矩形将被绘制为具有指定的 colorwidth 的笔划。另见 draw_texture_rect

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

注意:width 只有在 filledfalse 时才有效。

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


void draw_set_transform ( Vector2 position, float rotation=0.0, Vector2 scale=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 ( Transform2D xform )

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


void draw_string ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, Color modulate=Color(1, 1, 1, 1), BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const

使用指定的 fontpos(使用的字体的基线的左下角)处绘制 text。该文本的颜色将乘以 modulate。如果 width 大于等于 0,则文本超过指定宽度将被裁剪。

使用项目默认字体的例子:

# 如果在不断重绘的脚本中使用此方法,
# 则将 `default_font` 声明移动到在 `_ready()` 中赋值的成员变量中
# 这样 Control 只创建一次。
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)

另请参阅 Font.draw_string


void draw_string_outline ( Font font, Vector2 pos, String text, HorizontalAlignment alignment=0, float width=-1, int font_size=16, int size=1, Color modulate=Color(1, 1, 1, 1), BitField<JustificationFlag> justification_flags=3, Direction direction=0, Orientation orientation=0 ) const

pos(左下角使用字体的基线)处使用指定的 font 绘制 text 轮廓。该文本的颜色将乘以 modulate。如果 width 大于等于 0,则当文本超过指定宽度时将被裁剪。


void draw_style_box ( StyleBox style_box, Rect2 rect )

绘制一个样式矩形。


void draw_texture ( Texture2D texture, Vector2 position, Color modulate=Color(1, 1, 1, 1) )

在给定的位置绘制纹理。


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

在给定位置绘制一个带纹理的矩形,可以选择用颜色调制。如果 transposetrue,则纹理将交换其 X 和 Y 坐标。另见 draw_rectdraw_texture_rect_region


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

在给定的位置绘制具有纹理的矩形,可以指定所使用的纹理区域(由 src_rect 指定),可选择用颜色调制。如果 transposetrue,则纹理将交换其 X 和 Y 坐标。另见 draw_texture_rect


void force_update_transform ( )

强制更新变换。由于性能原因,物理中的变换改变不是即时的。变换是在累积后再设置。如果你在进行物理操作时需要最新的变换,请使用此功能。


RID get_canvas ( ) const

返回此项目所在的 World2D 画布的 RID


RID get_canvas_item ( ) const

返回 RenderingServer 对该项目使用的画布项目 RID。


Transform2D get_canvas_transform ( ) const

返回从该项目所在的画布坐标系到 Viewport 坐标系的变换。


Vector2 get_global_mouse_position ( ) const

返回该 CanvasItem 所在的 CanvasLayer 中鼠标的位置,使用该 CanvasLayer 的坐标系。

注意:要得到屏幕空间的坐标(例如使用非嵌入式 Popup 时),你可以使用 DisplayServer.mouse_get_position


Transform2D get_global_transform ( ) const

返回该项目的全局变换矩阵,即到最顶层的 CanvasItem 节点的综合变换。最顶层的项目是一个 CanvasItem,它要么没有父级,要么有非 CanvasItem 父级,或者要么它启用了 top_level


Transform2D get_global_transform_with_canvas ( ) const

返回从该 CanvasItem 的局部坐标系到 Viewport 坐标系的变换。


Vector2 get_local_mouse_position ( ) const

返回该 CanvasItem 中鼠标的位置,使用该 CanvasItem 的局部坐标系。


Transform2D get_screen_transform ( ) const

返回该 CanvasItem 在全局屏幕坐标中的变换(即考虑窗口位置)。主要用于编辑器插件。

如果窗口是嵌入的,则等于 get_global_transform(参见 Viewport.gui_embed_subwindows)。


Transform2D get_transform ( ) const

返回此项目的变换矩阵。


Rect2 get_viewport_rect ( ) const

Rect2 形式返回视口的边界。


Transform2D get_viewport_transform ( ) const

返回从该项目所在的画布坐标系到 Viewport 嵌入坐标系的变换。


bool get_visibility_layer_bit ( int layer ) const

返回渲染可见层上的某个比特位。


World2D get_world_2d ( ) const

返回此物品所在的 World2D


void hide ( )

如果该 CanvasItem 目前是可见的,则将其隐藏。相当于将 visible 设为 false


bool is_local_transform_notification_enabled ( ) const

如果将局部变换通知传达给子级,则返回 true


bool is_transform_notification_enabled ( ) const

如果将全局变换通知传达给子级,则返回 true


bool is_visible_in_tree ( ) const

如果该节点位于 SceneTree 中,并且其 visible 属性为 true,并且其所有上层节点也均可见,则返回 true。如果任何上层节点被隐藏,则该节点在场景树中将不可见,因此也不会进行绘制(见 _draw)。


Vector2 make_canvas_position_local ( Vector2 screen_point ) const

screen_point 指定为该节点的新局部变换。


InputEvent make_input_local ( InputEvent event ) const

event 的输入发出的变换将在局部空间而不是全局空间中应用。


void move_to_front ( )

移动该节点以显示在其同级节点之上。

在内部,该节点被移动到父节点的子节点列表的底部。该方法对没有父节点的节点没有影响。


void queue_redraw ( )

将该 CanvasItem 加入重绘队列。空闲时,如果 CanvasItem 可见,则会发送 NOTIFICATION_DRAW 并调用 _draw。即便多次调用这个方法,每帧也都只会发生一次绘制。


void set_notify_local_transform ( bool enable )

如果 enabletrue,则该节点将在其局部变换发生改变时收到 NOTIFICATION_LOCAL_TRANSFORM_CHANGED


void set_notify_transform ( bool enable )

如果 enabletrue,那么这个节点会在其全局变换发生改变时接收到 NOTIFICATION_TRANSFORM_CHANGED


void set_visibility_layer_bit ( int layer, bool enabled )

设置或清除渲染可见层上的单个位。这简化了对该 CanvasItem 的可见层的编辑。


void show ( )

如果该 CanvasItem 目前是隐藏的,则将其显示。相当于将 visible 设为 true。对于继承自 Popup 的控件,让它们可见的正确做法是换成调用各种 popup*() 函数的其中之一。