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.

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

纹理过滤器在最邻近的四个像素之间混合。如果想要避免像素化样式,大多数情况下请使用此选项。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS = 3

纹理过滤器读取最邻近的 mipmap 中的最邻近像素。这是使用 mipmap 从纹理中读取的最快方法。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS = 4

纹理过滤器在最邻近的 4 个像素和最邻近的 2 个 mipmap 之间混合。请用于可能以低缩放率查看的非像素画纹理(例如由 Camera2D 缩放造成),因为 mipmap 对于平滑小于屏幕像素的像素很重要。

TextureFilter TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC = 5

纹理过滤器读取最邻近的像素,但会根据表面和相机视图之间的角度选择 mipmap。可以减少几乎与相机成一直线的表面的伪影。各向异性过滤级别可以通过调整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 来改变。

注意:这个纹理过滤器很少用于 2D 项目。TEXTURE_FILTER_NEAREST_WITH_MIPMAPS 通常更合适。

TextureFilter TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC = 6

纹理过滤器在最邻近的 4 个像素之间进行混合,并会根据表面和相机视图之间的角度选择 mipmap。可以减少几乎与相机成一直线的表面的伪影。这是最慢的过滤选项,但可以得到最高质量的纹理。各向异性过滤级别可以通过调整 ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level 来改变。

注意:这个纹理过滤器很少用于 2D 项目。TEXTURE_FILTER_NEAREST_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 为负