Drawing
Immediate-mode 2D drawing and style.
background
background(r, g=None, b=None, a=255)Sets the background colour and clears the screen to it.
It erases everything drawn so far this frame, and the colour is reused for the automatic clear at the start of every frame. Channel values are not clamped; the 8-bit target clamps them to 0-255. Inside an Fbo (with fbo:) it clears the Fbo instead, in order with the draws around it, and leaves the window’s background colour alone.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| r | ColorLike | Iterable[float] | Red (0-255), or the gray level when g and b are omitted, or a colour: a kiln.Color, an iterable (r, g, b[, a]) or a colour string ("#rrggbb[aa]" or a name such as "tomato"). |
required |
| g | float | None | Green, or the alpha of background(gray, alpha) or background(color, alpha). |
None |
| b | float | None | Blue. | None |
| a | float | Alpha, used with background(gray) and background(r, g, b, a). |
255 |
Raises
| Name | Type | Description |
|---|---|---|
| TypeError | a given with a colour (give its alpha as g). |
fill
fill(r, g=None, b=None, a=None, /)Sets the fill colour of subsequent shapes and text, or None for no fill.
Shapes (circle, rect, triangle, with shape() and the rest) are filled in it and then outlined in the stroke colour; text is drawn in it; lines take it when the stroke is None. fill(None) stops filling: with no stroke either, shapes and text draw nothing. Images, textures, Fbos, meshes, Vbos and fields take tint instead.
The colour forms (every colour argument in Kiln takes them): fill(gray), fill(gray, alpha), fill(r, g, b[, a]), and fill(color[, alpha]) where color is a kiln.Color, an iterable (r, g, b[, a]), a hex string "#rrggbb" or "#rrggbbaa", or the lower-case name of a Color constant ("tomato", "sky_blue"). Channels are 0-255 and not clamped; the 8-bit target clamps the result.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| r | Red, the gray level, a colour, or None. | required | |
| g | Green, or the alpha of fill(gray, alpha) or fill(color, alpha). |
None |
|
| b | Blue. | None |
|
| a | Alpha of fill(r, g, b, a), 255 when omitted. |
None |
Raises
| Name | Type | Description |
|---|---|---|
| TypeError | Not a colour. | |
| ValueError | An unknown colour string. |
stroke
stroke(r=_KEEP, g=None, b=None, a=None, /, *, width=None)Sets the outline colour and width of subsequent shapes and lines, or None for none.
Shapes are filled in fill and then outlined in this colour, width points wide (1 by default), centred on the shape’s edge, so a translucent stroke shows the fill through its inner half, as in SVG. Lines take this colour, or the fill colour when it is None. Text is never outlined. stroke(None) is the default: no outline. stroke(width=3) alone changes only the width, keeping the colour. The colour forms are fill’s.
The width is in points on screen whatever the current transform; a negative width counts as 0, which draws no outline.
Under a material, shade() runs once for the fill and once for the stroke, with m.color set to each colour in turn, so a stroked shape costs two material passes.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| r | Red, the gray level, a colour, or None; left out to keep the colour. | _KEEP |
|
| g | Green, or the alpha of stroke(gray, alpha) or stroke(color, alpha). |
None |
|
| b | Blue. | None |
|
| a | Alpha of stroke(r, g, b, a), 255 when omitted. |
None |
|
| width | The stroke width in points, or None to keep it. | None |
Raises
| Name | Type | Description |
|---|---|---|
| TypeError | Not a colour, or neither a colour nor width. |
|
| ValueError | An unknown colour string. |
tint
tint(r, g=None, b=None, a=None, /)Sets the colour that multiplies images, textures, Fbos, meshes, Vbos and fields.
Every .draw() of an Image, Texture, Fbo, Mesh (its vertex colours too), Vbo and agents Field is multiplied by it: white, the default, leaves them as they are, and an alpha below 255 fades them. Shapes and text take fill and stroke instead. The colour forms are fill’s.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| r | Red, the gray level, or a colour. | required | |
| g | Green, or the alpha of tint(gray, alpha) or tint(color, alpha). |
None |
|
| b | Blue. | None |
|
| a | Alpha of tint(r, g, b, a), 255 when omitted. |
None |
Raises
| Name | Type | Description |
|---|---|---|
| TypeError | Not a colour (None included: white is “no tint”). | |
| ValueError | An unknown colour string. |
blend
blend(mode)Sets how subsequent shapes blend with what is drawn.
kiln.blend(Blend.ADD) and kiln.blend("add") are the same. Blend.ALPHA is the default; None turns blending off, which is Blend.REPLACE (shapes replace what is drawn). Read the current mode from current_style().blend.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| mode | Blend | BlendValue | None | A Blend member or its name, or None for Blend.REPLACE. |
required |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | An unknown mode name; the message lists the valid ones. |
clear
clear(r, g=None, b=None, a=None)Clears the screen to a colour, alpha included.
Unlike background, the background colour is unchanged. clear(gray) clears to a transparent gray (alpha 0) unless an alpha is given (clear(gray, alpha) or clear(gray, a=alpha)), while clear(r, g, b) and clear(color) use alpha 255 unless given. Channel values are not clamped. Inside an Fbo it clears the Fbo, in order with the draws around it.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| r | float | Iterable[float] | Red (0-255), or the gray level when g and b are omitted, or an iterable (r, g, b[, a]). |
required |
| g | float | None | Green, or the alpha of clear(gray, alpha). |
None |
| b | float | None | Blue. | None |
| a | float | None | Alpha of clear(r, g, b, a) (255 when omitted) or of clear(gray, a=alpha) (0 when omitted). |
None |
clear_alpha
clear_alpha()Makes the whole screen opaque, keeping its colours.
Useful after drawing with Blend.REPLACE or clear(gray), which leave alpha below 255. Inside an Fbo it makes the Fbo opaque.
circle
circle(x, y, radius)Draws a circle centred on (x, y).
Filled in the fill colour, then outlined in the stroke colour, each when it is not None; outlines are stroke(width=) points wide and centred on the circle’s edge.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| x | float | Centre x. | required |
| y | float | Centre y. | required |
| radius | float | Radius. | required |
ellipse
ellipse(x, y, rx, ry)Draws an ellipse centred on (x, y).
rx and ry are the radii, as circle takes a radius: ellipse(x, y, r, r) is circle(x, y, r). (Some frameworks take the full width and height, twice these.) The ellipse is always centred on (x, y), whatever the rect mode. The outline stays an even stroke(width=) points wide all the way round.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| x | float | Centre x. | required |
| y | float | Centre y. | required |
| rx | float | Horizontal radius. | required |
| ry | float | Vertical radius. | required |
rect
rect(x, y, w, h, *, radius=None)Draws a rectangle, with sharp or rounded corners.
(x, y) is the top-left corner, or the centre after rect_mode(RectMode.CENTER). Outlines have sharp (mitred) corners. A negative w or h extends the rectangle the other way.
radius rounds the corners: one radius for all four, or (top_left, top_right, bottom_right, bottom_left). Radii are clamped to half the shorter side, and a negative radius counts as 0 (a sharp corner).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| x | float | Corner or centre x, per the rect mode. | required |
| y | float | Corner or centre y, per the rect mode. | required |
| w | float | Width. | required |
| h | float | Height. | required |
| radius | float | tuple[float, float, float, float] | None | The corner radius, or one per corner; None for sharp corners. | None |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | radius is a sequence of other than 4 radii. |
|
| TypeError | A corner radius is not a number. |
line
line(x1, y1, x2, y2)Draws a line segment from (x1, y1) to (x2, y2).
Lines are stroke(width=) points wide (1 by default) and have flat (butt) ends. They are drawn in the stroke colour, or in the fill colour when the stroke is None (a line has no inside, and Kiln’s default has no stroke); with neither, nothing is drawn.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| x1 | float | Start x. | required |
| y1 | float | Start y. | required |
| x2 | float | End x. | required |
| y2 | float | End y. | required |
triangle
triangle(x1, y1, x2, y2, x3, y3)Draws a triangle through three points.
Either winding works. Outline corners are rounded (the stroke is the exact distance band around the edges).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| x1 | float | First vertex x. | required |
| y1 | float | First vertex y. | required |
| x2 | float | Second vertex x. | required |
| y2 | float | Second vertex y. | required |
| x3 | float | Third vertex x. | required |
| y3 | float | Third vertex y. | required |
circles
circles(xy, radius, color=None)Draws many circles in one call.
The result is identical to calling circle for each row, in order, but is built with numpy and is far faster beyond a few thousand shapes. Fill, stroke, stroke width, blend mode and the current matrix apply as for circle.
With a stroke colour set, each filled shape adds a second record, so the call builds about 4x slower than without a stroke.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| xy | ArrayLike | Centres, an array of shape (n, 2). | required |
| radius | ArrayLike | One radius for all circles, or an array of shape (n,) or (n, 1) with one radius per circle. | required |
| color | ArrayLike | None | None for the current colour, one colour (a kiln.Color or tuple of 0-255 channels), or an array of shape (n, 3) or (n, 4) with one colour per circle, 0-255 like fill. It is the fill colour, or the outline’s under fill(None) (in place of the stroke colour); a stroke colour outlines filled circles. With neither a fill nor a stroke, explicit colours draw outlines at the stroke width, and None draws nothing. |
None |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If an argument has the wrong shape or is None. |
ellipses
ellipses(xy, radii, color=None)Draws many ellipses in one call.
Identical to calling ellipse for each row, in order. Ellipses are always centred on their point, whatever the rect mode.
With a stroke colour set, each filled shape adds a second record, so the call builds about 4x slower than without a stroke.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| xy | ArrayLike | Centres, an array of shape (n, 2). | required |
| radii | ArrayLike | The radii, as ellipse takes them: one number for circles, an array of shape (n,) or (n, 1) for one radius per shape, (n, 2) for (rx, ry) per shape, or [[rx, ry]] (shape (1, 2)) for one (rx, ry) for every shape. A bare pair (rx, ry) raises ValueError, because with two shapes it could also mean one radius each. |
required |
| color | ArrayLike | None | None for the current colour, one colour, or an array of shape (n, 3) or (n, 4), 0-255: the fill colour, or the outline’s under fill(None), as for circles (with neither a fill nor a stroke, explicit colours still draw). |
None |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If an argument has the wrong shape or is None. |
rects
rects(xy, size, color=None)Draws many rectangles in one call.
Identical to calling rect for each row, in order. xy is each top-left corner, or each centre after rect_mode(RectMode.CENTER).
With a stroke colour set, each filled shape adds a second record, so the call builds about 4x slower than without a stroke.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| xy | ArrayLike | Corners or centres, an array of shape (n, 2). | required |
| size | ArrayLike | Width and height: one number for squares, an array of shape (n,) or (n, 1) for one side per square, (n, 2) for (w, h) per rectangle, or [[w, h]] (shape (1, 2)) for one (w, h) for every rectangle. A bare pair (w, h) raises ValueError, because with two shapes it could also mean one side each. |
required |
| color | ArrayLike | None | None for the current colour, one colour, or an array of shape (n, 3) or (n, 4), 0-255: the fill colour, or the outline’s under fill(None), as for circles (with neither a fill nor a stroke, explicit colours still draw). |
None |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If an argument has the wrong shape or is None. |
lines
lines(p1, p2, color=None)Draws many line segments in one call.
Identical to calling line for each pair, in order: always stroked with the stroke width, with flat ends. To draw an array of segments of shape (n, 2, 2), pass segments[:, 0] and segments[:, 1].
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| p1 | ArrayLike | Start points, an array of shape (n, 2). | required |
| p2 | ArrayLike | End points, an array of shape (n, 2). | required |
| color | ArrayLike | None | None for the current line colour (the stroke colour, else the fill colour, as for line; with neither, nothing is drawn), one colour, or an array of shape (n, 3) or (n, 4), 0-255. Explicit colours always draw, at the stroke width. |
None |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If an argument has the wrong shape or is None. |
rect_mode
rect_mode(mode)Sets how rectangle coordinates are read.
Affects rect, rounded or not; ellipses and circles are always centred.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| mode | RectMode | RectModeValue | A RectMode member or its name ("corner", "center"). Read the current one from current_style().rect_mode. |
required |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | An unknown mode name; the message lists the valid ones. |
curve_resolution
curve_resolution(n)Sets how many points make up each curve.
Used by curve_vertex (points per stretch), bezier_vertex, curve and bezier. The default is 20. Rounded rectangles are signed distance fields and are smooth whatever the value.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n | int | Points per curve, at least 1 (smaller values are raised to 1). | required |