CanvasItem¶
任何 2D 对象的基类。
描述¶
任何 2D 对象的基类。画布项目(Canvas Item)以树状排列;子节点继承并扩展其父节点的变换。CanvasItem
由 Control 扩展为任何 GUI 相关的东西,由 Node2D 扩展为任何 2D 引擎相关的东西。
任何 CanvasItem
都可以绘图。要绘图就必须调用 update,然后就会在空闲时接收到 NOTIFICATION_DRAW 来请求重绘。因此画布项目不需要每一帧都重绘,大大提升了性能。提供了几个用于在 CanvasItem
上绘图的函数(请参阅 draw_*
函数)。但是,它们只能在 Object._notification、信号或虚函数 _draw 内部使用。
画布项目是按树状顺序绘制的。默认情况下,子项目在其父项目的顶部,因此根CanvasItem
将被画在所有项目的后面。这种行为可以在每个项目的基础上进行更改。
CanvasItem
也可以被隐藏,这也将隐藏其子项目。它提供了许多方法来改变参数,如调制(对它自己和它的子项目)和自调制(只对它自己),以及它的混合模式。
最终,可以请求一个变换通知,它将在父树改变的情况下通知节点它的全局位置发生了变化。
注意:除非另有说明,所有具有角度参数的方法必须将角度指定为弧度。要将度数转换为弧度,请使用 @GDScript.deg2rad。
教程¶
属性¶
|
||
|
||
|
||
|
||
|
||
|
方法¶
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 ) |
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 ) |
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 ) ) |
void |
draw_multiline ( PoolVector2Array points, Color color, float width=1.0, bool antialiased=false ) |
void |
draw_multiline_colors ( PoolVector2Array points, PoolColorArray colors, float width=1.0, bool antialiased=false ) |
void |
draw_multimesh ( MultiMesh multimesh, Texture texture, Texture normal_map=null ) |
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 ) |
void |
draw_polyline_colors ( PoolVector2Array points, PoolColorArray colors, float width=1.0, bool antialiased=false ) |
void |
draw_primitive ( PoolVector2Array points, PoolColorArray colors, PoolVector2Array uvs, Texture texture=null, float width=1.0, Texture normal_map=null ) |
void |
draw_rect ( Rect2 rect, Color color, bool filled=true, float width=1.0, bool antialiased=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 ) |
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 ) |
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 ) |
void |
|
get_canvas ( ) const |
|
get_canvas_item ( ) const |
|
get_canvas_transform ( ) const |
|
get_global_mouse_position ( ) const |
|
get_global_transform ( ) const |
|
get_global_transform_with_canvas ( ) const |
|
get_local_mouse_position ( ) const |
|
get_transform ( ) const |
|
get_viewport_rect ( ) const |
|
get_viewport_transform ( ) const |
|
get_world_2d ( ) const |
|
void |
hide ( ) |
is_local_transform_notification_enabled ( ) const |
|
is_set_as_toplevel ( ) const |
|
is_transform_notification_enabled ( ) const |
|
is_visible_in_tree ( ) const |
|
make_canvas_position_local ( Vector2 screen_point ) const |
|
make_input_local ( InputEvent event ) const |
|
void |
set_as_toplevel ( bool enable ) |
void |
set_notify_local_transform ( bool enable ) |
void |
set_notify_transform ( bool enable ) |
void |
show ( ) |
void |
update ( ) |
信号¶
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
Default |
|
Setter |
set_light_mask(value) |
Getter |
get_light_mask() |
此CanvasItem
在其中响应Light2D节点的渲染层。
Material material
Setter |
set_material(value) |
Getter |
get_material() |
在此CanvasItem
上应用于纹理的材质。
Color modulate
Default |
|
Setter |
set_modulate(value) |
Getter |
get_modulate() |
应用于此CanvasItem
上纹理的颜色。
Color self_modulate
Default |
|
Setter |
set_self_modulate(value) |
Getter |
get_self_modulate() |
应用于此CanvasItem
上纹理的颜色。子节点CanvasItem
不能继承这个颜色。
bool show_behind_parent
Default |
|
Setter |
set_draw_behind_parent(value) |
Getter |
is_draw_behind_parent_enabled() |
如果true
,则对象在其父对象后面绘制。
bool show_on_top
如果true
,则对象在其父对象的顶部绘制。
bool use_parent_material
Default |
|
Setter |
set_use_parent_material(value) |
Getter |
get_use_parent_material() |
如果true
,则将父级CanvasItem
的material属性用作此项的材质。
bool visible
Default |
|
Setter |
set_visible(value) |
Getter |
is_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_colored_polygon ( PoolVector2Array points, Color color, PoolVector2Array uvs=PoolVector2Array( ), Texture texture=null, Texture normal_map=null, 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
目前没有实现,没有效果。
用所提供的纹理以 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_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_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
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
。如果任何先决条件被隐藏,则该节点在场景树中将不可见。
分配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以请求重绘。