Skip to content

Presort text draw calls. #108369

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+2,000 −224
Open

Presort text draw calls. #108369

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/classes/TextEdit.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1053,7 +1053,7 @@
<param index="0" name="column" type="int" />
<param index="1" name="draw_callback" type="Callable" />
<description>
Set a custom draw callback for the gutter at the given index. [param draw_callback] must take the following arguments: A line index [int], a gutter index [int], and an area [Rect2]. This callback only works when the gutter type is [constant GUTTER_TYPE_CUSTOM] (see [method set_gutter_type]).
Set a custom draw callback for the gutter at the given index. [param draw_callback] must take the following arguments: A canvas item [RID], a line index [int], a gutter index [int], and an area [Rect2]. This callback only works when the gutter type is [constant GUTTER_TYPE_CUSTOM] (see [method set_gutter_type]).
</description>
</method>
<method name="set_gutter_draw">
Expand Down
25 changes: 25 additions & 0 deletions doc/classes/TextLine.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,19 @@
Adds inline object to the text buffer, [param key] must be unique. In the text, object is represented as [param length] object replacement characters.
</description>
</method>
<method name="add_outline_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="layer" type="int" />
<param index="1" name="list" type="RID" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="pos" type="Vector2" />
<param index="4" name="outline_size" type="int" default="1" />
<param index="5" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="6" name="oversampling" type="float" default="0.0" />
<description>
Adds draw calls for glyph outlines to the draw list [param list].
</description>
</method>
<method name="add_string">
<return type="bool" />
<param index="0" name="text" type="String" />
Expand All @@ -31,6 +44,18 @@
Adds text span and font to draw it.
</description>
</method>
<method name="add_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="layer" type="int" />
<param index="1" name="list" type="RID" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="pos" type="Vector2" />
<param index="4" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="5" name="oversampling" type="float" default="0.0" />
<description>
Adds draw calls for glyphs to the draw list [param list].
</description>
</method>
<method name="clear">
<return type="void" />
<description>
Expand Down
79 changes: 79 additions & 0 deletions doc/classes/TextParagraph.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,58 @@
<tutorials>
</tutorials>
<methods>
<method name="add_dropcap_outline_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="layer" type="int" />
<param index="1" name="list" type="RID" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="pos" type="Vector2" />
<param index="4" name="outline_size" type="int" default="1" />
<param index="5" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="6" name="oversampling" type="float" default="0.0" />
<description>
Adds draw calls for dropcap glyph outlines to the draw list [param list].
Copy link
Member

@Mickeon Mickeon Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can be seen as huge nitpick but I had to get it off of my chest someday.

All of these very brief descriptions in the TextServer may seem good at a glance, but they're quite unwelcoming. Hard to parse, difficult to localize, devoid of information. Yes, as an experienced developer with decent English knowledge, it's reasonably easy to understand what each parameter does, but that's not every one. Neither are the parameter names taken for granted in most of the class reference.
In this PR the descriptions are mostly okay, in my opinion, considering it's better to keep them consistent with the surrounding TextServer-related documentation (which is arguably more important), as well as to avoid redundancy. Regardless, it will be worth doing a huge pass someday.

Again, it's easy to understand these as a professional, but exposing methods and assigning them very terse and cryptid descriptions is one sure way to make the reader feel uneasy, like they're interacting with something they shouldn't be doing.

</description>
</method>
<method name="add_dropcap_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="layer" type="int" />
<param index="1" name="list" type="RID" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="pos" type="Vector2" />
<param index="4" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="5" name="oversampling" type="float" default="0.0" />
<description>
Adds draw calls for dropcap glyphs to the draw list [param list].
</description>
</method>
<method name="add_line_outline_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="layer" type="int" />
<param index="1" name="list" type="RID" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="pos" type="Vector2" />
<param index="4" name="line" type="int" />
<param index="5" name="outline_size" type="int" default="1" />
<param index="6" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="7" name="oversampling" type="float" default="0.0" />
<description>
Adds draw calls for line [param line] glyph outlines to the draw list [param list].
</description>
</method>
<method name="add_line_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="layer" type="int" />
<param index="1" name="list" type="RID" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="pos" type="Vector2" />
<param index="4" name="line" type="int" />
<param index="5" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="6" name="oversampling" type="float" default="0.0" />
<description>
Adds draw calls for line [param line] glyphs to the draw list [param list].
</description>
</method>
<method name="add_object">
<return type="bool" />
<param index="0" name="key" type="Variant" />
Expand All @@ -20,6 +72,20 @@
Adds inline object to the text buffer, [param key] must be unique. In the text, object is represented as [param length] object replacement characters.
</description>
</method>
<method name="add_outline_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="layer" type="int" />
<param index="1" name="list" type="RID" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="pos" type="Vector2" />
<param index="4" name="outline_size" type="int" default="1" />
<param index="5" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="6" name="dc_color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="7" name="oversampling" type="float" default="0.0" />
<description>
Adds draw calls for paragraph glyph outlines to the draw list [param list].
</description>
</method>
<method name="add_string">
<return type="bool" />
<param index="0" name="text" type="String" />
Expand All @@ -31,6 +97,19 @@
Adds text span and font to draw it.
</description>
</method>
<method name="add_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="layer" type="int" />
<param index="1" name="list" type="RID" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="pos" type="Vector2" />
<param index="4" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="5" name="dc_color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="6" name="oversampling" type="float" default="0.0" />
<description>
Adds draw calls for paragraph glyphs to the draw list [param list].
</description>
</method>
<method name="clear">
<return type="void" />
<description>
Expand Down
180 changes: 180 additions & 0 deletions doc/classes/TextServer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,12 @@
<tutorials>
</tutorials>
<methods>
<method name="create_draw_list">
<return type="RID" />
<description>
Creates a new, empty draw list resource.
</description>
</method>
<method name="create_font">
<return type="RID" />
<description>
Expand Down Expand Up @@ -53,6 +59,122 @@
Draws box displaying character hexadecimal code. Used for replacing missing characters.
</description>
</method>
<method name="draw_list_add_custom" qualifiers="const">
<return type="void" />
<param index="0" name="list" type="RID" />
<param index="1" name="layer" type="int" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="callback" type="Callable" />
<description>
Adds custom draw call to a draw list [param list]. [param callback] is called with one argument, [RID] of canvas item to draw it to.
</description>
</method>
<method name="draw_list_add_hexbox" qualifiers="const">
<return type="void" />
<param index="0" name="list" type="RID" />
<param index="1" name="layer" type="int" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="pos" type="Vector2" />
<param index="4" name="index" type="int" />
<param index="5" name="size" type="int" />
<param index="6" name="modulate" type="Color" />
<description>
Adds draw call for box displaying character hexadecimal code to a draw list [param list].
</description>
</method>
<method name="draw_list_add_line" qualifiers="const">
<return type="void" />
<param index="0" name="list" type="RID" />
<param index="1" name="layer" type="int" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="start" type="Vector2" />
<param index="4" name="end" type="Vector2" />
<param index="5" name="width" type="float" />
<param index="6" name="dash" type="float" />
<param index="7" name="modulate" type="Color" />
<description>
Adds draw call for a line to a draw list [param list].
</description>
</method>
<method name="draw_list_add_rect" qualifiers="const">
<return type="void" />
<param index="0" name="list" type="RID" />
<param index="1" name="layer" type="int" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="rect" type="Rect2" />
<param index="4" name="filled" type="bool" />
<param index="5" name="modulate" type="Color" />
<description>
Adds draw call for a rectangle to a draw list [param list].
</description>
</method>
<method name="draw_list_add_texture" qualifiers="const">
<return type="void" />
<param index="0" name="list" type="RID" />
<param index="1" name="layer" type="int" />
<param index="2" name="transform" type="Transform2D" />
<param index="3" name="texture" type="RID" />
<param index="4" name="rect" type="Rect2" />
<param index="5" name="modulate" type="Color" />
<description>
Adds draw call for a texture to a draw list [param list].
</description>
</method>
<method name="draw_list_draw">
<return type="void" />
<param index="0" name="list" type="RID" />
<param index="1" name="ci" type="RID" />
<param index="2" name="free" type="bool" default="false" />
<description>
Processes all draw calls in the draw list [param list] to the canvas item [param ci]. If [param free] is [code]true[/code], the draw list is also deleted.
</description>
</method>
<method name="draw_list_reserve">
Copy link
Member

@Mickeon Mickeon Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we sure we want to expose what is essentially a reserve method to the public API? I would be very wary since this is a very prickly topic of discussion.
(Note that clayjohn got originally confused by the purpose of the linked PR).

Copy link
Member Author

@bruvzg bruvzg Oct 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the way TextServer is implemented (to be implementable as GDExtension), I do not think it is possible to have non-exposed methods. And unlike Dictionary, TextServer is a low level API most users won't ever interact with, so it should not be an issue.

<return type="void" />
<param index="0" name="list" type="RID" />
<param index="1" name="count" type="int" />
<description>
Reserves additional space in the draw list [param list] for a [param count] draw calls.
</description>
</method>
<method name="draw_list_sort">
<return type="void" />
<param index="0" name="list" type="RID" />
<description>
Sorts draw calls in the draw list using to layer index and texture id.
</description>
</method>
<method name="font_add_glyph_outline_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="font_rid" type="RID" />
<param index="1" name="layer" type="int" />
<param index="2" name="list" type="RID" />
<param index="3" name="transform" type="Transform2D" />
<param index="4" name="size" type="int" />
<param index="5" name="outline_size" type="int" />
<param index="6" name="pos" type="Vector2" />
<param index="7" name="index" type="int" />
<param index="8" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="9" name="oversampling" type="float" default="0.0" />
<description>
Adds draw call for a single glyph outline to a draw list [param list].
</description>
</method>
<method name="font_add_glyph_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="font_rid" type="RID" />
<param index="1" name="layer" type="int" />
<param index="2" name="list" type="RID" />
<param index="3" name="transform" type="Transform2D" />
<param index="4" name="size" type="int" />
<param index="5" name="pos" type="Vector2" />
<param index="6" name="index" type="int" />
<param index="7" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="8" name="oversampling" type="float" default="0.0" />
<description>
Adds draw call for a single glyph to a draw list [param list].
</description>
</method>
<method name="font_clear_glyphs">
<return type="void" />
<param index="0" name="font_rid" type="RID" />
Expand Down Expand Up @@ -1363,6 +1485,22 @@
Adds inline object to the text buffer, [param key] must be unique. In the text, object is represented as [param length] object replacement characters.
</description>
</method>
<method name="shaped_text_add_outline_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="shaped" type="RID" />
<param index="1" name="layer" type="int" />
<param index="2" name="list" type="RID" />
<param index="3" name="transform" type="Transform2D" />
<param index="4" name="pos" type="Vector2" />
<param index="5" name="clip_l" type="float" default="-1" />
<param index="6" name="clip_r" type="float" default="-1" />
<param index="7" name="outline_size" type="int" default="1" />
<param index="8" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="9" name="oversampling" type="float" default="0.0" />
<description>
Adds draw calls for text buffer glyph outlines to the draw list [param list].
</description>
</method>
<method name="shaped_text_add_string">
<return type="bool" />
<param index="0" name="shaped" type="RID" />
Expand All @@ -1376,6 +1514,21 @@
Adds text span and font to draw it to the text buffer.
</description>
</method>
<method name="shaped_text_add_to_draw_list" qualifiers="const">
<return type="void" />
<param index="0" name="shaped" type="RID" />
<param index="1" name="layer" type="int" />
<param index="2" name="list" type="RID" />
<param index="3" name="transform" type="Transform2D" />
<param index="4" name="pos" type="Vector2" />
<param index="5" name="clip_l" type="float" default="-1" />
<param index="6" name="clip_r" type="float" default="-1" />
<param index="7" name="color" type="Color" default="Color(1, 1, 1, 1)" />
<param index="8" name="oversampling" type="float" default="0.0" />
<description>
Adds draw calls for text buffer glyphs to the draw list [param list].
</description>
</method>
<method name="shaped_text_clear">
<return type="void" />
<param index="0" name="rid" type="RID" />
Expand Down Expand Up @@ -2216,6 +2369,33 @@
<constant name="SUBPIXEL_POSITIONING_ONE_QUARTER_MAX_SIZE" value="16" enum="SubpixelPositioning">
Maximum font size which will use "one quarter of the pixel" subpixel positioning in [constant SUBPIXEL_POSITIONING_AUTO] mode.
</constant>
<constant name="DRAW_CALL_NULL" value="0" enum="DrawCallType">
Draw call that does nothing. This is used to initialize new [code]TextServer::DrawCallType[/code] native structures.
</constant>
<constant name="DRAW_CALL_NORMAL" value="1" enum="DrawCallType">
Draw call for a normal glyph or glyph outline.
</constant>
<constant name="DRAW_CALL_MSDF" value="2" enum="DrawCallType">
Draw call for a MSDF glyph or glyph outline.
</constant>
<constant name="DRAW_CALL_LCD" value="3" enum="DrawCallType">
Draw call for a LCD anti-aliased glyph or glyph outline using.
</constant>
<constant name="DRAW_CALL_HEX" value="4" enum="DrawCallType">
Draw call for a box displaying character hexadecimal code.
</constant>
<constant name="DRAW_CALL_LINE" value="5" enum="DrawCallType">
Draw call for a line.
</constant>
<constant name="DRAW_CALL_RECT" value="6" enum="DrawCallType">
Draw call for a rectangle.
</constant>
<constant name="DRAW_CALL_IMAGE" value="7" enum="DrawCallType">
Draw call for a texture.
</constant>
<constant name="DRAW_CALL_CUSTOM" value="8" enum="DrawCallType">
Draw call using a custom draw callback.
</constant>
<constant name="FEATURE_SIMPLE_LAYOUT" value="1" enum="Feature">
TextServer supports simple text layouts.
</constant>
Expand Down
Loading