GeomDraw

enum Geom.ThicknessSpace

Geom.SPACE_METERS = 0

Thickness in world units; shrinks on screen with distance.

Geom.SPACE_PIXELS = 1

Thickness in screen pixels; constant on-screen size.

Geom.SPACE_VIEWPORT = 2

A fraction of the viewport: 100 span its shorter side, so 1 is one percent of it and about 11 pixels at 1080p. The same idea as CSS vmin. Radii and sizes here are whole-ish numbers; strokes come out below 1, and a stroke that should stay a fixed pixel width wants SPACE_PIXELS instead.

enum Geom.LineEndCap

Geom.CAP_NONE = 0

Cut off exactly at each endpoint.

Geom.CAP_SQUARE = 1

Extend by half the thickness at each endpoint.

Geom.CAP_ROUND = 2

Extend by half the thickness, rounded.

enum Geom.LineGeometry

Geom.LINE_BILLBOARD = 1

A flat quad that turns to face the camera.

Geom.LINE_VOLUMETRIC = 2

Real tube geometry, with volume.

enum Geom.ColorMode

Geom.COLOR_SINGLE = 0

One flat color.

Geom.COLOR_RADIAL = 1

Interpolate color to color_end from the center outwards.

Geom.COLOR_ANGULAR = 2

Interpolate color to color_end around the sweep.

enum Geom.PolylineJoin

Geom.JOIN_SIMPLE = 0

Corners at plain half-width; the outside of a corner pinches inward.

Geom.JOIN_MITER = 1

Corners extended to where the edges meet, clamped on sharp turns.

Geom.JOIN_ROUND = 2

As simple, with a disc laid over each joint.

Geom.JOIN_BEVEL = 3

The outside of a corner cut off square.

enum Geom.BlendMode

Geom.BLEND_OPAQUE = 0

Writes depth and sorts against other geometry; hard edges, no fade.

Geom.BLEND_TRANSPARENT = 1

Standard alpha compositing. The default.

Geom.BLEND_ADDITIVE = 2

Brightens what is behind. Good for glows.

Geom.BLEND_MULTIPLY = 3

Darkens what is behind. Good for tints.

Geom.BLEND_SUBTRACT = 4

Subtracts this color from the background.

Geom.BLEND_TRANSPARENT_DEPTH = 5

Transparent, but writing depth so shapes occlude by position.

enum Geom.DashSpace

Geom.DASH_METERS = 0

Dash size and spacing are lengths in the shape's own units.

Geom.DASH_RELATIVE = 1

Dash size and spacing are multiples of the wall thickness.

Geom.DASH_FIXED_COUNT = 2

Dash size is a repeat count; spacing is the empty fraction of a period.

enum Geom.DashSnap

Geom.SNAP_OFF = 0

Use the dash period as given.

Geom.SNAP_TILING = 1

Round to a whole number of periods so the pattern tiles seamlessly.

Geom.SNAP_END_TO_END = 2

Round so a dash lands at each end of the shape.

enum Geom.DashType

Geom.DASH_BASIC = 0

Square dash ends.

Geom.DASH_ANGLED = 1

Dash ends sheared into a parallelogram. The shear is 0 by default, which looks exactly like DASH_BASIC; set dash_modifier on GeomDraw, or modifier on GeomDash.

Geom.DASH_ROUNDED = 2

Rounded dash ends.

BlendMode blend_mode

How following shapes combine with what is already drawn.

Opaque is the only mode that writes depth, so it is the only one that sorts correctly against other 3D geometry. Every mode is a separate compiled program and a separate draw call, created on first use.

Color color

Default color for shapes that do not override it.

Color color_end

Second color, used when color_mode is not Single.

ColorMode color_mode

Single flat color, or a Radial or Angular gradient between color and color_end.

ThicknessSpace radius_space

Space for radii, so a shape can be sized in meters while its wall stays a constant pixel width.

ThicknessSpace size_space

Space for rectangle width and height.

float thickness

Thickness in the current thickness_space.

ThicknessSpace thickness_space

Whether thickness is meters, pixels or viewport units. Meters are world units and shrink with distance; pixels hold their width on screen.

bool arc_end_cap_round

Whether an arc's ends are rounded off.

LineEndCap line_end_cap

How a line's ends are finished: None, Square, or Round.

LineGeometry line_geometry

Whether 3D lines are billboarded quads or real tubes. A tube has volume, so it occludes and keeps its width viewed end-on; a billboard is cheaper and anti-aliased.

int line_sides

Radial segments around a volumetric line.

PolylineJoin polyline_join

How a polyline's corners are shaped.

Vector4 corner_radii

Rectangle corner radii as fractions of the shorter half-side, clockwise from bottom-left. See set_corner_roundness for the uniform case.

float polygon_angle

Rotation applied to regular polygons, in radians.

bool polygon_convex_only

Skip ear clipping and fan from the first corner. Much cheaper, and correct only for convex polygons.

bool rect_pivot_corner

Whether a rectangle's position is its bottom-left corner, not its center.

float roundness

Corner rounding for regular polygons, 0 sharp to 1 fully circular.

bool billboard

Whether 3D flat shapes turn to face the camera instead of sitting in the plane of the current matrix.

Off by default, so a disc rotated flat lies flat. Turning it on is what a health bar or a ground marker wants: readable from anywhere, at the cost of the shape's own orientation being ignored.

bool cone_cap

Whether a cone's base is filled in.

int primitive_detail

Segments around the equator of a generated sphere. Higher is smoother and costs more vertices per instance.

float shading

How strongly the solid 3D primitives are shaded, 0 flat to 1 full. Flat leaves a sphere looking exactly like a disc, which is occasionally what you want and usually not.

Font font

Font for text. Left empty, the engine's fallback is used, so text works with no setup at all. Not part of the saved draw style: it is a resource handle, like a material, rather than a setting.

int font_size

Point size for text.

float dash_modifier

Shear amount for angled dashes, -1 to 1. Zero by default, so DASH_ANGLED does nothing until this is set.

float dash_offset

Shifts the pattern by whole periods; integers look identical.

float dash_size

Length of one dash, read in dash_space — which defaults to RELATIVE, where it is a multiple of the wall's thickness and not a length. In METERS it is a length in the shape's own units; in FIXED_COUNT it is a repeat count instead.

DashSnap dash_snap

Whether the pattern is stretched to fit the shape it runs along. Tiling makes a whole number of periods fit, which matters most on a closed shape, where a pattern that does not fit has to break somewhere.

DashSpace dash_space

How dash_size and dash_spacing are read: in the shape's own units, as multiples of the wall's thickness, or as a count of repeats around the shape.

Defaults to RELATIVE, so dashes stay square as the wall changes thickness. Worth knowing before reaching for a length: on a wall 12 units thick, a dash_size of 26 is a dash 312 units long, which on a small ring is most of the way round it.

float dash_spacing

Gap between dashes, read the same way as dash_size: multiples of the wall in RELATIVE, a length in METERS, and the empty fraction of each period in FIXED_COUNT.

DashType dash_type

The shape of each dash: Basic square ends, Angled, or Rounded.

bool dashed

Whether following dashable shapes are drawn dashed. Dashed shapes use a separately compiled program, so this also selects which batch they join.

Transform3D matrix

Applied to 3D positions before batching, like Draw.Matrix.

Transform2D matrix_2d

Applied to 2D positions before batching.

void begin_frame()

Starts a new frame's worth of drawing.

Connected to SceneTree::process_frame, which fires immediately before _process runs on any node, so everything drawn during a tick lands between one of these and the next.

The frame boundary has to be the logic tick rather than the rendered frame, because in the editor they are wildly different rates. Measured with an idle editor: 400 process ticks against 7 renders. Clearing on render meant fifty-odd ticks of shapes piling into one upload, each repetition opening fresh runs, so draw order was decided by wherever the render happened to land in that pile -- and it shifted every time the editor redrew. At runtime the two rates are 1:1 and this changes nothing.

The cost is that work done on ticks that never render is thrown away. That is the right trade: it is bounded by one tick's drawing, where the alternative was unbounded growth between renders.

void flush_frame()

Uploads everything drawn this frame and resets for the next one.

Connected to RenderingServer::frame_pre_draw, so it runs after every node's _process and before anything is rendered. Callers never invoke this; it is public only because Godot needs to reach it as a signal handler.

Uploads only. Clearing belongs to begin_frame, because a rendered frame and a logic frame are not the same thing -- see there.

void request_editor_redraw()

Asks the editor to render the next frame, for drawing that animates.

Does nothing in a running game, where every logic frame is rendered anyway.

The editor renders on demand: it keeps ticking _process at full rate but only redraws when it believes something changed, and drawing through the rendering server is invisible to that judgement. Measured on an idle editor, an animating tool script gets one rendered frame per forty-odd ticks -- the motion is running at full speed and being _sampled_ at about 1 fps, which reads as severe lag.

Call this once per frame from a tool script whose drawing moves. Rendering then runs 1:1 with processing, measured both for canvas and spatial drawing.

Marking the editor's own control is deliberately broad: a rendered frame is a whole frame, so one request covers both viewports. A Node2D could mark itself instead, but a Node3D has nothing equivalent to mark.

int draw_calls_3d()

Draw calls the 3D half will issue this frame: one per run of consecutive calls sharing a shader program.

int queued_3d()

Number of 3D shapes queued in the current scope. Useful in tests.

int draw_calls_2d()

Draw calls the 2D half will issue this frame, text runs included: each is its own canvas item.

int queued_2d()

Number of 2D shapes queued in the current scope.

void reset_all_draw_states()

Resets styling _and_ matrices.

void reset_matrix()

Resets the draw matrices to identity.

void reset_style()

Resets styling but preserves the matrix, like Draw.ResetStyle().

void set_corner_roundness(roundness: float)

Sets all four rectangle corner radii at once, as a fraction of the shorter half-side: 0 is square, 1 fully rounded.

void line_2d(from: Vector2, to: Vector2)

Line between two points on the canvas, using the current style color.

void line_2d_colored(from: Vector2, to: Vector2, color: Color)

Line between two canvas points in an explicit color.

void line_2d_gradient(from: Vector2, to: Vector2, color_a: Color, color_b: Color)

Canvas line with a gradient. color_b is bit-packed into one float, because canvas_item shaders expose only CUSTOM0/CUSTOM1.

void arc_2d(center: Vector2, radius: float, angle_start: float, angle_end: float)

Circular arc on the canvas. Angles are radians. The sweep runs forward from the start, wrapping past a full turn, so 350 to 10 degrees is a 20 degree sweep, not a 340 degree one.

void arc_2d_colored(center: Vector2, radius: float, angle_start: float, angle_end: float, color: Color)

Circular arc on the canvas in an explicit color.

void disc_2d(center: Vector2, radius: float)

Filled circle on the canvas.

void disc_2d_colored(center: Vector2, radius: float, color: Color)

Filled circle on the canvas in an explicit color.

void pie_2d(center: Vector2, radius: float, angle_start: float, angle_end: float)

Filled circular sector on the canvas. Angles are radians. The sweep runs forward from the start, wrapping past a full turn, so 350 to 10 degrees is a 20 degree sweep, not a 340 degree one.

void pie_2d_colored(center: Vector2, radius: float, angle_start: float, angle_end: float, color: Color)

Filled circular sector on the canvas in an explicit color.

void ring_2d(center: Vector2, radius: float)

Circle outline on the canvas.

void ring_2d_colored(center: Vector2, radius: float, color: Color)

Circle outline on the canvas in an explicit color.

void rect_2d(center: Vector2, size: Vector2)

Filled rectangle on the canvas.

void rect_border_2d(center: Vector2, size: Vector2)

Rectangle outline on the canvas.

void rect_border_2d_colored(center: Vector2, size: Vector2, color: Color)

Rectangle outline on the canvas in an explicit color.

void rect_2d_colored(center: Vector2, size: Vector2, color: Color)

Filled rectangle on the canvas in an explicit color.

void regular_polygon_2d(center: Vector2, radius: float, sides: int)

Filled regular polygon on the canvas.

void regular_polygon_border_2d(center: Vector2, radius: float, sides: int)

Regular polygon outline on the canvas.

void regular_polygon_border_2d_colored(center: Vector2, radius: float, sides: int, color: Color)

Regular polygon outline on the canvas in an explicit color.

void regular_polygon_2d_colored(center: Vector2, radius: float, sides: int, color: Color)

Filled regular polygon on the canvas in an explicit color.

void quad_2d(a: Vector2, b: Vector2, c: Vector2, d: Vector2)

Quad on the canvas.

void quad_border_2d(a: Vector2, b: Vector2, c: Vector2, d: Vector2)

Canvas quad outline.

void quad_2d_colored(a: Vector2, b: Vector2, c: Vector2, d: Vector2, color: Color)

Canvas quad in an explicit color.

void quad_2d_gradient(a: Vector2, b: Vector2, c: Vector2, d: Vector2, color_a: Color, color_b: Color, color_c: Color, color_d: Color)

Canvas quad with a color per corner.

void triangle_2d(a: Vector2, b: Vector2, c: Vector2)

Triangle on the canvas.

void triangle_border_2d(a: Vector2, b: Vector2, c: Vector2)

Canvas triangle outline.

void triangle_2d_colored(a: Vector2, b: Vector2, c: Vector2, color: Color)

Canvas triangle in an explicit color.

void triangle_2d_gradient(a: Vector2, b: Vector2, c: Vector2, color_a: Color, color_b: Color, color_c: Color)

Canvas triangle with a color per corner.

void line(from: Vector3, to: Vector3)

Line between two points, using the current style color.

void line_colored(from: Vector3, to: Vector3, color: Color)

Line between two points in an explicit color.

void line_gradient(from: Vector3, to: Vector3, color_a: Color, color_b: Color)

Line with a gradient from color_a at the start to color_b at the end.

void arc(center: Vector3, radius: float, angle_start: float, angle_end: float)

Circular arc. Angles are radians; arc_end_cap_round rounds the ends. The sweep runs forward from the start, wrapping past a full turn, so 350 to 10 degrees is a 20 degree sweep, not a 340 degree one.

void arc_colored(center: Vector3, radius: float, angle_start: float, angle_end: float, color: Color)

Circular arc in an explicit color.

void disc(center: Vector3, radius: float)

Filled circle.

void disc_colored(center: Vector3, radius: float, color: Color)

Filled circle in an explicit color.

void pie(center: Vector3, radius: float, angle_start: float, angle_end: float)

Filled circular sector. Angles are radians. The sweep runs forward from the start, wrapping past a full turn, so 350 to 10 degrees is a 20 degree sweep, not a 340 degree one.

void pie_colored(center: Vector3, radius: float, angle_start: float, angle_end: float, color: Color)

Filled circular sector in an explicit color.

void ring(center: Vector3, radius: float)

Circle outline. radius is to the center of the wall, not its outer edge, so radius and thickness stay independent.

void ring_colored(center: Vector3, radius: float, color: Color)

Circle outline in an explicit color.

void rect(center: Vector3, size: Vector2)

Filled rectangle, honouring corner_radii and rect_pivot_corner.

void rect_border(center: Vector3, size: Vector2)

Rectangle outline, using the current style thickness.

void rect_border_colored(center: Vector3, size: Vector2, color: Color)

Rectangle outline in an explicit color.

void rect_colored(center: Vector3, size: Vector2, color: Color)

Filled rectangle in an explicit color.

void regular_polygon(center: Vector3, radius: float, sides: int)

Filled regular polygon. radius is center-to-vertex.

void regular_polygon_border(center: Vector3, radius: float, sides: int)

Regular polygon outline, using the current style thickness.

void regular_polygon_border_colored(center: Vector3, radius: float, sides: int, color: Color)

Regular polygon outline in an explicit color.

void regular_polygon_colored(center: Vector3, radius: float, sides: int, color: Color)

Filled regular polygon in an explicit color.

void quad(a: Vector3, b: Vector3, c: Vector3, d: Vector3)

Quad through four points, wound in order.

void quad_border(a: Vector3, b: Vector3, c: Vector3, d: Vector3)

Quad outline.

void quad_colored(a: Vector3, b: Vector3, c: Vector3, d: Vector3, color: Color)

Quad in an explicit color.

void quad_gradient(a: Vector3, b: Vector3, c: Vector3, d: Vector3, color_a: Color, color_b: Color, color_c: Color, color_d: Color)

Quad with a color per corner.

void triangle(a: Vector3, b: Vector3, c: Vector3)

Triangle through three points, in the current style color.

void triangle_border(a: Vector3, b: Vector3, c: Vector3)

Triangle outline, using the current style thickness.

void triangle_colored(a: Vector3, b: Vector3, c: Vector3, color: Color)

Triangle in an explicit color.

void triangle_gradient(a: Vector3, b: Vector3, c: Vector3, color_a: Color, color_b: Color, color_c: Color)

Triangle with a color per corner.

void cone(base: Vector3, radius: float, length: float)

Solid cone, base centered on base with the tip along local +Y. Point it by setting the draw matrix; an arrowhead is a cone at a line's far end.

void cone_colored(base: Vector3, radius: float, length: float, color: Color)

Solid cone in an explicit color.

void cube(center: Vector3, size: float)

Solid box, equal on every axis.

void cube_colored(center: Vector3, size: float, color: Color)

Solid cube in an explicit color.

void cuboid(center: Vector3, size: Vector3)

Solid box with a size per axis.

void cuboid_colored(center: Vector3, size: Vector3, color: Color)

Solid box in an explicit color.

void sphere(center: Vector3, radius: float)

Solid sphere.

void sphere_colored(center: Vector3, radius: float, color: Color)

Solid sphere in an explicit color.

void torus(center: Vector3, radius: float, thickness: float)

Solid torus about the local Z axis. radius is to the center of the tube and thickness is its diameter, matching the ring convention.

void torus_colored(center: Vector3, radius: float, thickness: float, color: Color)

Solid torus in an explicit color.

void polyline(path: GeomPolylinePath, closed: bool)

Draws a path in world space. Point colors and thicknesses multiply the style's, so the same path can be redrawn tinted or weighted differently.

Several polylines still share one draw call: the strips are appended to one mesh with independent index runs, so drawing many paths does not cost a draw call each.

void polyline_points(points: PackedVector3Array, closed: bool)

Draws a path straight from an array of points, at the style's color and thickness throughout.

A PolylinePath exists for paths that carry their own per-point color and thickness; this is for when they do not, and saves allocating an object to hold what is already an array.

void polyline_2d(path: GeomPolylinePath, closed: bool)

Draws a path on the canvas.

void polyline_points_2d(points: PackedVector2Array, closed: bool)

Draws a canvas path straight from an array of points.

void polygon(points: PackedVector3Array)

Filled polygon of any number of corners, concave included.

Triangulated by ear clipping unless polygon_convex_only is set. The corners must describe a simple, non-self-intersecting ring; the points are assumed coplanar.

void polygon_colored(points: PackedVector3Array, color: Color)

Filled polygon in an explicit color.

void polygon_2d(points: PackedVector2Array)

Filled polygon on the canvas.

void polygon_2d_colored(points: PackedVector2Array, color: Color)

Filled canvas polygon in an explicit color.

void texture(center: Vector3, size: Vector2, texture: Texture2D)

A texture drawn into a rectangle, tinted by the style color.

Two textured rectangles share a draw call only if they share a texture, since a texture binds to the material rather than the mesh. Drawing many small images is therefore a case for an atlas.

void texture_colored(center: Vector3, size: Vector2, texture: Texture2D, modulate: Color)

A texture drawn into a rectangle in an explicit tint.

void texture_2d(center: Vector2, size: Vector2, texture: Texture2D)

A texture drawn into a rectangle on the canvas.

void texture_2d_colored(center: Vector2, size: Vector2, texture: Texture2D, modulate: Color)

A canvas texture rectangle in an explicit tint.

void text(world_position: Vector3, text: String)

A label at a point in the world, drawn flat on the canvas above everything 3D.

Projected to the screen rather than built as 3D glyph geometry, because a 3D label is nearly always wanted screen-facing and screen-sized. Text behind the camera is skipped rather than mirrored in front of it.

void text_colored(world_position: Vector3, text: String, color: Color)

A world-space label in an explicit color.

Vector2 text_size(text: String)

Measured size of a string at the current font and size, for laying text out against shapes.

void text_2d(position: Vector2, text: String)

Text on the canvas, with position at its left baseline.

void text_2d_colored(position: Vector2, text: String, color: Color)

Canvas text in an explicit color.

void arcs(centers: PackedVector3Array, radii: PackedFloat32Array, angle_starts: PackedFloat32Array, angle_ends: PackedFloat32Array, colors: PackedColorArray)

Circular arcs in 3D, in one call. Uses the current thickness.

void discs(centers: PackedVector3Array, radii: PackedFloat32Array, colors: PackedColorArray)

Filled circles in 3D, in one call.

void lines(from: PackedVector3Array, to: PackedVector3Array, colors: PackedColorArray)

Line segments in 3D, in one call.

void pies(centers: PackedVector3Array, radii: PackedFloat32Array, angle_starts: PackedFloat32Array, angle_ends: PackedFloat32Array, colors: PackedColorArray)

Filled circular sectors in 3D, in one call. Angles are radians.

void polygons(centers: PackedVector3Array, radii: PackedFloat32Array, sides: PackedInt32Array, colors: PackedColorArray)

Filled regular polygons in 3D, in one call.

void polylines(points: PackedVector3Array, counts: PackedInt32Array, colors: PackedColorArray, closed: bool)

Many separate paths in 3D, in one call. See polylines_2d.

void rects(centers: PackedVector3Array, sizes: PackedVector2Array, colors: PackedColorArray)

Filled rectangles in 3D, in one call.

void rings(centers: PackedVector3Array, radii: PackedFloat32Array, colors: PackedColorArray)

Circle outlines in 3D, in one call. Uses the current thickness.

void arcs_2d(centers: PackedVector2Array, radii: PackedFloat32Array, angle_starts: PackedFloat32Array, angle_ends: PackedFloat32Array, colors: PackedColorArray)

Circular arcs on the canvas, in one call. Uses the current thickness.

void discs_2d(centers: PackedVector2Array, radii: PackedFloat32Array, colors: PackedColorArray)

Filled circles on the canvas, in one call. See discs for 3D.

radii takes one entry per circle or a single entry for all of them. colors may also be empty, meaning the current color.

void lines_2d(from: PackedVector2Array, to: PackedVector2Array, colors: PackedColorArray)

Line segments on the canvas, in one call.

void pies_2d(centers: PackedVector2Array, radii: PackedFloat32Array, angle_starts: PackedFloat32Array, angle_ends: PackedFloat32Array, colors: PackedColorArray)

Filled circular sectors on the canvas, in one call. Angles are radians.

void polygons_2d(centers: PackedVector2Array, radii: PackedFloat32Array, sides: PackedInt32Array, colors: PackedColorArray)

Filled regular polygons on the canvas, in one call.

void polylines_2d(points: PackedVector2Array, counts: PackedInt32Array, colors: PackedColorArray, closed: bool)

Many separate paths on the canvas, in one call.

counts says how many points each path takes from points, so twelve points with counts [4, 4, 4] are three disconnected four-point paths rather than one of twelve. closed applies to all of them.

Per-point color and thickness are what GeomPolylinePath is for; this takes one color per path.

void rects_2d(centers: PackedVector2Array, sizes: PackedVector2Array, colors: PackedColorArray)

Filled rectangles on the canvas, in one call.

void rings_2d(centers: PackedVector2Array, radii: PackedFloat32Array, colors: PackedColorArray)

Circle outlines on the canvas, in one call. Uses the current thickness.