CanvasItem

Inherits: Node < Object

Inherited By: Control, Node2D

任何 2D 对象的基类。

描述

任何 2D 对象的基类。画布项目（Canvas Item）以树状排列；子节点继承并扩展其父节点的变换。CanvasItem 由 Control 扩展为任何 GUI 相关的东西，由 Node2D 扩展为任何 2D 引擎相关的东西。

任何 CanvasItem 都可以绘图。要绘图就必须调用 update，然后就会在空闲时接收到 NOTIFICATION_DRAW 来请求重绘。因此画布项目不需要每一帧都重绘，大大提升了性能。提供了几个用于在 CanvasItem 上绘图的函数（请参阅 draw_* 函数）。但是，它们只能在 Object._notification、信号或虚函数 _draw 内部使用。

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

CanvasItem 也可以被隐藏，这也将隐藏其子项目。它提供了许多方法来改变参数，如调制（对它自己和它的子项目）和自调制（只对它自己），以及它的混合模式。

最终，可以请求一个变换通知，它将在父树改变的情况下通知节点它的全局位置发生了变化。

注意：除非另有说明，所有具有角度参数的方法必须将角度指定为弧度。要将度数转换为弧度，请使用 @GDScript.deg2rad。

教程

• Viewport and canvas transforms

• Custom drawing in 2D

• Audio Spectrum Demo

属性

方法

信号

• draw ( )

当CanvasItem必须重绘时发出。这只能是实时连接，因为延迟将不允许绘制。

• hide ( )

当隐藏时发出。

• item_rect_changed ( )

在物体Rect2边缘（位置或大小）改变，或有影响到边缘的操作（比如修改Sprite.texture）时触发。

• visibility_changed ( )

当可见性（隐藏/可见）更改时发出。

枚举

enum BlendMode:

• BLEND_MODE_MIX = 0 —- 混合混合模式。假设颜色与alpha（不透明度）值无关。

• BLEND_MODE_ADD = 1 —- 加法混合模式。

• BLEND_MODE_SUB = 2 —- 减法混合模式。

• BLEND_MODE_MUL = 3 —- 乘法混合模式。

• BLEND_MODE_PREMULT_ALPHA = 4 —- 混合混合模式。假定颜色已预先乘以alpha（不透明度）值。

• BLEND_MODE_DISABLED = 5 —- 关闭混合模式。颜色（包括 alpha）将会变原来的样子。仅能在渲染透明背景的目标使用。不会应用任何光照。

常量

• NOTIFICATION_TRANSFORM_CHANGED = 2000 —- CanvasItem的变换已更改。仅当set_notify_transform或set_notify_local_transform启用时，才会收到此通知。

• NOTIFICATION_DRAW = 30 —- 要求绘制CanvasItem。

• NOTIFICATION_VISIBILITY_CHANGED = 31 —- CanvasItem的可见性已更改。

• NOTIFICATION_ENTER_CANVAS = 32 —- CanvasItem已进入画布。

• NOTIFICATION_EXIT_CANVAS = 33 —- CanvasItem已退出画布。

属性说明

• int light_mask

此CanvasItem在其中响应Light2D节点的渲染层。

• Material material

在此CanvasItem上应用于纹理的材质。

• Color modulate

应用于此CanvasItem上纹理的颜色。

• Color self_modulate

应用于此CanvasItem上纹理的颜色。子节点CanvasItem不能继承这个颜色。

• bool show_behind_parent

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

• bool show_on_top

如果true，则对象在其父对象的顶部绘制。

• bool use_parent_material

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

• bool visible

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

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

方法说明

• void _draw ( ) virtual

引擎调用的可覆盖函数（如果定义了）来绘制画布项目。

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

在给定的角度之间画一条弧线。point_count 的值越大，曲线越平滑。

• float draw_char ( Font font, Vector2 position, String char, String next, Color modulate=Color( 1, 1, 1, 1 ) )

使用自定义字体绘制一个字符串字符。返回前进量，这个量取决于该字符的宽度，以及与可选的下一个字符的字偶距。

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

画一个彩色的圆。

• void draw_colored_polygon ( PoolVector2Array points, Color color, PoolVector2Array uvs=PoolVector2Array( ), Texture texture=null, Texture normal_map=null, bool antialiased=false )

绘制任意数量点的彩色多边形，凸或凹。

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

绘制一条从 2D 点到另一个点的线，具有给定的颜色和宽度。它可以选择抗锯齿。

• void draw_mesh ( Mesh mesh, Texture texture, Texture normal_map=null, Transform2D transform=Transform2D( 1, 0, 0, 1, 0, 0 ), Color modulate=Color( 1, 1, 1, 1 ) )

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

• void draw_multiline ( PoolVector2Array points, Color color, float width=1.0, bool antialiased=false )

使用 uniform color 绘制多条平行线。

注意：width 和 antialiased 目前没有实现，没有效果。

• void draw_multiline_colors ( PoolVector2Array points, PoolColorArray colors, float width=1.0, bool antialiased=false )

以 uniform 的 width 和逐段着色绘制多条平行线。分配给线段的颜色按 points 和 colors 之间的索引匹配。

注： width和antialiased目前没有实现，没有效果。

• void draw_multimesh ( MultiMesh multimesh, Texture texture, Texture normal_map=null )

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

• void draw_polygon ( PoolVector2Array points, PoolColorArray colors, PoolVector2Array uvs=PoolVector2Array( ), Texture texture=null, Texture normal_map=null, bool antialiased=false )

绘制任意数量的点的多边形，凸或凹。

• void draw_polyline ( PoolVector2Array points, Color color, float width=1.0, bool antialiased=false )

以uniform 的color和width来绘制相互连接的线段，可选抗锯齿。

• void draw_polyline_colors ( PoolVector2Array points, PoolColorArray colors, float width=1.0, bool antialiased=false )

以uniform的width绘制相互连接的线段，逐段着色，可选抗锯齿。分配给线段的颜色通过points和colors之间的索引进行匹配。

• void draw_primitive ( PoolVector2Array points, PoolColorArray colors, PoolVector2Array uvs, Texture texture=null, float width=1.0, Texture normal_map=null )

绘制自定义基本网格。1点为一个点，2点为一条线，3点为一个三角形，4点为一个四边形。

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

绘制一个矩形。如果filled是true，矩形将被填充为指定的color。如果filled是false，矩形将以color和width指定的笔画形式绘制。如果antialiased是true，线条抗锯齿。

注意：width和antialiased只有在filled是false时才有效。

• void draw_set_transform ( Vector2 position, float rotation, Vector2 scale )

设置通过组件进行绘图的自定义变换。之后绘制的任何东西都将被转换。

• void draw_set_transform_matrix ( Transform2D xform )

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

• void draw_string ( Font font, Vector2 position, String text, Color modulate=Color( 1, 1, 1, 1 ), int clip_w=-1 )

使用指定的font在position绘制text（左下角作为字体的基线）。该文本的颜色将乘以modulate。如果clip_w大于或等于0，文本超过了指定的宽度，将被裁剪。

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

# 如果在不断重绘的脚本中使用此方法，
# 则将`default_font`声明移动到在`_ready()`中赋值的成员变量中
# 这样Control只创建一次。
var default_font = Control.new().get_font("font")
draw_string(default_font, Vector2(64, 64), "Hello world")

参阅Font.draw。

• void draw_style_box ( StyleBox style_box, Rect2 rect )

绘制一个样式矩形。

• void draw_texture ( Texture texture, Vector2 position, Color modulate=Color( 1, 1, 1, 1 ), Texture normal_map=null )

在给定的位置绘制纹理。

• void draw_texture_rect ( Texture texture, Rect2 rect, bool tile, Color modulate=Color( 1, 1, 1, 1 ), bool transpose=false, Texture normal_map=null )

在给定的位置上绘制一个纹理矩形，可以选择用颜色调制。如果 transpose 是 true，纹理的 X 和 Y 坐标将被调换。

• void draw_texture_rect_region ( Texture texture, Rect2 rect, Rect2 src_rect, Color modulate=Color( 1, 1, 1, 1 ), bool transpose=false, Texture normal_map=null, bool clip_uv=true )

在给定的位置绘制纹理矩形区域，可选择用颜色调制。如果 transpose 是 true，纹理的 X 和 Y 坐标将被调换。

• void force_update_transform ( )

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

• RID get_canvas ( ) const

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

• RID get_canvas_item ( ) const

返回此项目在 VisualServer 中使用的画布项 RID。

• 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_transform ( ) const

返回此项目的变换矩阵。

• Rect2 get_viewport_rect ( ) const

以Rect2形式返回视窗的边界。

• Transform2D get_viewport_transform ( ) const

返回这个项目相对于视窗的变换。

• World2D get_world_2d ( ) const

返回此物品所在的World2D。

• void hide ( )

如果CanvasItem当前可见，则隐藏它。

• bool is_local_transform_notification_enabled ( ) const

如果将本地转换通知传达给子级，则返回true。

• bool is_set_as_toplevel ( ) const

如果节点设置为顶层，则返回true。参阅set_as_toplevel。

• bool is_transform_notification_enabled ( ) const

如果将全局转换通知传达给子级，则返回true。

• bool is_visible_in_tree ( ) const

如果该节点位于SceneTree中，并且其visible属性为true，并且其所有前提均可见，则返回true。如果任何先决条件被隐藏，则该节点在场景树中将不可见。

• Vector2 make_canvas_position_local ( Vector2 screen_point ) const

分配screen_point作为该节点的新本地转换。

• InputEvent make_input_local ( InputEvent event ) const

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

• void set_as_toplevel ( bool enable )

如果enable为true，则该节点将不会从父画布项目继承其变换。

• void set_notify_local_transform ( bool enable )

如果enable为true，则将使用局部变换数据更新子项。

• void set_notify_transform ( bool enable )

如果enable为true，则将使用全局变换数据更新子项。

• void show ( )

如果CanvasItem当前是隐藏的，则显示它。对于继承Popup的控件，使其可见的正确方法是调用多个popup*()函数中的一个来代替。

• void update ( )

将CanvasItem排队等待更新。在空闲时间将调用NOTIFICATION_DRAW以请求重绘。