summaryrefslogtreecommitdiff
path: root/doc/classes/CanvasItem.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/classes/CanvasItem.xml')
-rw-r--r--doc/classes/CanvasItem.xml91
1 files changed, 72 insertions, 19 deletions
diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml
index d74f49c897..c3c768c12d 100644
--- a/doc/classes/CanvasItem.xml
+++ b/doc/classes/CanvasItem.xml
@@ -42,10 +42,12 @@
<param index="3" name="end_angle" type="float" />
<param index="4" name="point_count" type="int" />
<param index="5" name="color" type="Color" />
- <param index="6" name="width" type="float" default="1.0" />
+ <param index="6" name="width" type="float" default="-1.0" />
<param index="7" name="antialiased" type="bool" default="false" />
<description>
- Draws a unfilled arc between the given angles. The larger the value of [param point_count], the smoother the curve. See also [method draw_circle].
+ Draws an unfilled arc between the given angles with a uniform [param color] and [param width] and optional antialiasing (supported only for positive [param width]). The larger the value of [param point_count], the smoother the curve. See also [method draw_circle].
+ If [param width] is negative, then the arc is drawn using [constant 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 [param width] like [code]1.0[/code].
+ The arc is drawn from [param start_angle] towards the value of [param end_angle] so in clockwise direction if [code]start_angle &lt; end_angle[/code] and counter-clockwise otherwise. Passing the same angles but in reversed order will produce the same arc. If absolute difference of [param start_angle] and [param end_angle] is greater than [constant @GDScript.TAU] radians, then a full circle arc is drawn (i.e. arc will not overlap itself).
</description>
</method>
<method name="draw_char" qualifiers="const">
@@ -95,10 +97,12 @@
<param index="0" name="from" type="Vector2" />
<param index="1" name="to" type="Vector2" />
<param index="2" name="color" type="Color" />
- <param index="3" name="width" type="float" default="1.0" />
+ <param index="3" name="width" type="float" default="-1.0" />
<param index="4" name="dash" type="float" default="2.0" />
+ <param index="5" name="aligned" type="bool" default="true" />
<description>
Draws a dashed line from a 2D point to another, with a given color and width. See also [method draw_multiline] and [method draw_polyline].
+ If [param width] is negative, then a two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the line parts will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code].
</description>
</method>
<method name="draw_end_animation">
@@ -114,7 +118,7 @@
<param index="2" name="src_rect" type="Rect2" />
<param index="3" name="modulate" type="Color" default="Color(1, 1, 1, 1)" />
<description>
- Draws a textured rectangle region of the font texture with LCD sub-pixel anti-aliasing at a given position, optionally modulated by a color.
+ Draws a textured rectangle region of the font texture with LCD subpixel anti-aliasing at a given position, optionally modulated by a color.
Texture is drawn using the following blend operation, blend mode of the [CanvasItemMaterial] is ignored:
[codeblock]
dst.r = texture.r * modulate.r * modulate.a + dst.r * (1.0 - texture.r * modulate.a);
@@ -129,10 +133,11 @@
<param index="0" name="from" type="Vector2" />
<param index="1" name="to" type="Vector2" />
<param index="2" name="color" type="Color" />
- <param index="3" name="width" type="float" default="1.0" />
+ <param index="3" name="width" type="float" default="-1.0" />
<param index="4" name="antialiased" type="bool" default="false" />
<description>
Draws a line from a 2D point to another, with a given color and width. It can be optionally antialiased. See also [method draw_multiline] and [method draw_polyline].
+ If [param width] is negative, then a two-point primitive will be drawn instead of a four-point one. This means that when the CanvasItem is scaled, the line will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code].
</description>
</method>
<method name="draw_mesh">
@@ -153,6 +158,7 @@
<param index="3" name="modulate" type="Color" default="Color(1, 1, 1, 1)" />
<param index="4" name="outline" type="float" default="0.0" />
<param index="5" name="pixel_range" type="float" default="4.0" />
+ <param index="6" name="scale" type="float" default="1.0" />
<description>
Draws a textured rectangle region of the multi-channel signed distance field texture at a given position, optionally modulated by a color. See [member FontFile.multichannel_signed_distance_field] for more information and caveats about MSDF font rendering.
If [param outline] is positive, each alpha channel value of pixel in region is set to maximum value of true distance in the [param outline] radius.
@@ -163,18 +169,20 @@
<return type="void" />
<param index="0" name="points" type="PackedVector2Array" />
<param index="1" name="color" type="Color" />
- <param index="2" name="width" type="float" default="1.0" />
+ <param index="2" name="width" type="float" default="-1.0" />
<description>
Draws multiple disconnected lines with a uniform [param color]. When drawing large amounts of lines, this is faster than using individual [method draw_line] calls. To draw interconnected lines, use [method draw_polyline] instead.
+ If [param 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 [param width] like [code]1.0[/code].
</description>
</method>
<method name="draw_multiline_colors">
<return type="void" />
<param index="0" name="points" type="PackedVector2Array" />
<param index="1" name="colors" type="PackedColorArray" />
- <param index="2" name="width" type="float" default="1.0" />
+ <param index="2" name="width" type="float" default="-1.0" />
<description>
Draws multiple disconnected lines with a uniform [param width] and segment-by-segment coloring. Colors assigned to line segments match by index between [param points] and [param colors]. When drawing large amounts of lines, this is faster than using individual [method draw_line] calls. To draw interconnected lines, use [method draw_polyline_colors] instead.
+ If [param 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 [param width] like [code]1.0[/code].
</description>
</method>
<method name="draw_multiline_string" qualifiers="const">
@@ -236,20 +244,22 @@
<return type="void" />
<param index="0" name="points" type="PackedVector2Array" />
<param index="1" name="color" type="Color" />
- <param index="2" name="width" type="float" default="1.0" />
+ <param index="2" name="width" type="float" default="-1.0" />
<param index="3" name="antialiased" type="bool" default="false" />
<description>
- Draws interconnected line segments with a uniform [param color] and [param width] and optional antialiasing. When drawing large amounts of lines, this is faster than using individual [method draw_line] calls. To draw disconnected lines, use [method draw_multiline] instead. See also [method draw_polygon].
+ Draws interconnected line segments with a uniform [param color] and [param width] and optional antialiasing (supported only for positive [param width]). When drawing large amounts of lines, this is faster than using individual [method draw_line] calls. To draw disconnected lines, use [method draw_multiline] instead. See also [method draw_polygon].
+ If [param width] is negative, the polyline is drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code].
</description>
</method>
<method name="draw_polyline_colors">
<return type="void" />
<param index="0" name="points" type="PackedVector2Array" />
<param index="1" name="colors" type="PackedColorArray" />
- <param index="2" name="width" type="float" default="1.0" />
+ <param index="2" name="width" type="float" default="-1.0" />
<param index="3" name="antialiased" type="bool" default="false" />
<description>
- Draws interconnected line segments with a uniform [param width] and segment-by-segment coloring, and optional antialiasing. Colors assigned to line segments match by index between [param points] and [param colors]. When drawing large amounts of lines, this is faster than using individual [method draw_line] calls. To draw disconnected lines, use [method draw_multiline_colors] instead. See also [method draw_polygon].
+ Draws interconnected line segments with a uniform [param width] and segment-by-segment coloring, and optional antialiasing (supported only for positive [param width]). Colors assigned to line segments match by index between [param points] and [param colors]. When drawing large amounts of lines, this is faster than using individual [method draw_line] calls. To draw disconnected lines, use [method draw_multiline_colors] instead. See also [method draw_polygon].
+ If [param width] is negative, then the polyline is drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code].
</description>
</method>
<method name="draw_primitive">
@@ -258,7 +268,6 @@
<param index="1" name="colors" type="PackedColorArray" />
<param index="2" name="uvs" type="PackedVector2Array" />
<param index="3" name="texture" type="Texture2D" default="null" />
- <param index="4" name="width" type="float" default="1.0" />
<description>
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. See also [method draw_line], [method draw_polyline], [method draw_polygon], and [method draw_rect].
</description>
@@ -268,10 +277,12 @@
<param index="0" name="rect" type="Rect2" />
<param index="1" name="color" type="Color" />
<param index="2" name="filled" type="bool" default="true" />
- <param index="3" name="width" type="float" default="1.0" />
+ <param index="3" name="width" type="float" default="-1.0" />
<description>
Draws a rectangle. If [param filled] is [code]true[/code], the rectangle will be filled with the [param color] specified. If [param filled] is [code]false[/code], the rectangle will be drawn as a stroke with the [param color] and [param width] specified.
+ If [param 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 [param width] like [code]1.0[/code].
[b]Note:[/b] [param width] is only effective if [param filled] is [code]false[/code].
+ [b]Note:[/b] Unfilled rectangles drawn with a negative [param width] may not display perfectly. For example, corners may be missing or brighter due to overlapping lines (for a translucent [param color]).
</description>
</method>
<method name="draw_set_transform">
@@ -404,7 +415,7 @@
<method name="get_canvas_transform" qualifiers="const">
<return type="Transform2D" />
<description>
- Returns the transform matrix of this item's canvas.
+ Returns the transform from the coordinate system of the canvas, this item is in, to the [Viewport]s coordinate system.
</description>
</method>
<method name="get_global_mouse_position" qualifiers="const">
@@ -416,13 +427,13 @@
<method name="get_global_transform" qualifiers="const">
<return type="Transform2D" />
<description>
- Returns the global transform matrix of this item.
+ Returns the global transform matrix of this item, i.e. the combined transform up to the topmost [CanvasItem] node. The topmost item is a [CanvasItem] that either has no parent, has non-[CanvasItem] parent or it has [member top_level] enabled.
</description>
</method>
<method name="get_global_transform_with_canvas" qualifiers="const">
<return type="Transform2D" />
<description>
- Returns the global transform matrix of this item in relation to the canvas.
+ Returns the transform from the local coordinate system of this [CanvasItem] to the [Viewport]s coordinate system.
</description>
</method>
<method name="get_local_mouse_position" qualifiers="const">
@@ -453,7 +464,14 @@
<method name="get_viewport_transform" qualifiers="const">
<return type="Transform2D" />
<description>
- Returns this item's transform in relation to the viewport.
+ Returns the transform from the coordinate system of the canvas, this item is in, to the [Viewport]s embedders coordinate system.
+ </description>
+ </method>
+ <method name="get_visibility_layer_bit" qualifiers="const">
+ <return type="bool" />
+ <param index="0" name="layer" type="int" />
+ <description>
+ Returns an individual bit on the rendering visibility layer.
</description>
</method>
<method name="get_world_2d" qualifiers="const">
@@ -503,7 +521,7 @@
<method name="move_to_front">
<return type="void" />
<description>
- Moves this node to display on top of its siblings. This has more use in [Control], as [Node2D] can be ordered with [member Node2D.z_index].
+ Moves this node to display on top of its siblings.
Internally, the node is moved to the bottom of parent's children list. The method has no effect on nodes without a parent.
</description>
</method>
@@ -527,6 +545,14 @@
If [param enable] is [code]true[/code], this node will receive [constant NOTIFICATION_TRANSFORM_CHANGED] when its global transform changes.
</description>
</method>
+ <method name="set_visibility_layer_bit">
+ <return type="void" />
+ <param index="0" name="layer" type="int" />
+ <param index="1" name="enabled" type="bool" />
+ <description>
+ Set/clear individual bits on the rendering visibility layer. This simplifies editing this [CanvasItem]'s visibility layer.
+ </description>
+ </method>
<method name="show">
<return type="void" />
<description>
@@ -535,7 +561,8 @@
</method>
</methods>
<members>
- <member name="clip_children" type="bool" setter="set_clip_children" getter="is_clipping_children" default="false">
+ <member name="clip_children" type="int" setter="set_clip_children_mode" getter="get_clip_children_mode" enum="CanvasItem.ClipChildrenMode" default="0">
+ Allows the current node to clip children nodes, essentially acting as a mask.
</member>
<member name="light_mask" type="int" setter="set_light_mask" getter="get_light_mask" default="1">
The rendering layers in which this [CanvasItem] responds to [Light2D] nodes.
@@ -564,10 +591,24 @@
<member name="use_parent_material" type="bool" setter="set_use_parent_material" getter="get_use_parent_material" default="false">
If [code]true[/code], the parent [CanvasItem]'s [member material] property is used as this one's material.
</member>
+ <member name="visibility_layer" type="int" setter="set_visibility_layer" getter="get_visibility_layer" default="1">
+ 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.
+ </member>
<member name="visible" type="bool" setter="set_visible" getter="is_visible" default="true">
If [code]true[/code], this [CanvasItem] is drawn. The node is only visible if all of its antecedents are visible as well (in other words, [method is_visible_in_tree] must return [code]true[/code]).
[b]Note:[/b] For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup*()[/code] functions instead.
</member>
+ <member name="y_sort_enabled" type="bool" setter="set_y_sort_enabled" getter="is_y_sort_enabled" default="false">
+ If [code]true[/code], child nodes with the lowest Y position are drawn before those with a higher Y position. If [code]false[/code], Y-sorting is disabled. Y-sorting only affects children that inherit from [CanvasItem].
+ You can nest nodes with Y-sorting. Child Y-sorted nodes are sorted in the same space as the parent Y-sort. This feature allows you to organize a scene better or divide it into multiple ones without changing your scene tree.
+ </member>
+ <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" default="true">
+ If [code]true[/code], the node's Z index is relative to its parent's Z index. If this node's Z index is 2 and its parent's effective Z index is 3, then this node's effective Z index will be 2 + 3 = 5.
+ </member>
+ <member name="z_index" type="int" setter="set_z_index" getter="get_z_index" default="0">
+ Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others. Must be between [constant RenderingServer.CANVAS_ITEM_Z_MIN] and [constant RenderingServer.CANVAS_ITEM_Z_MAX] (inclusive).
+ [b]Note:[/b] Changing the Z index of a [Control] only affects the drawing order, not the order in which input events are handled. This can be useful to implement certain UI animations, e.g. a menu where hovered items are scaled and should overlap others.
+ </member>
</members>
<signals>
<signal name="draw">
@@ -652,5 +693,17 @@
<constant name="TEXTURE_REPEAT_MAX" value="4" enum="TextureRepeat">
Represents the size of the [enum TextureRepeat] enum.
</constant>
+ <constant name="CLIP_CHILDREN_DISABLED" value="0" enum="ClipChildrenMode">
+ Child draws over parent and is not clipped.
+ </constant>
+ <constant name="CLIP_CHILDREN_ONLY" value="1" enum="ClipChildrenMode">
+ Parent is used for the purposes of clipping only. Child is clipped to the parent's visible area, parent is not drawn.
+ </constant>
+ <constant name="CLIP_CHILDREN_AND_DRAW" value="2" enum="ClipChildrenMode">
+ Parent is used for clipping child, but parent is also drawn underneath child as normal before clipping child to its visible area.
+ </constant>
+ <constant name="CLIP_CHILDREN_MAX" value="3" enum="ClipChildrenMode">
+ Represents the size of the [enum ClipChildrenMode] enum.
+ </constant>
</constants>
</class>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-17 21:39:01 +0000