Drawing

Note

This page is generated from the doc comments in kiln/ by tools/docgen. Fix the comment, not the page.

At a glance

Drawing :: struct {...}
Line_Cap :: enum {...}
Line_Join :: enum {...}
arc :: proc(d: ^Drawing, center: [2]f32, radius, from, to: f32)
circle_path :: proc(d: ^Drawing, center: [2]f32, radius: f32)
clip :: proc(d: ^Drawing, even_odd := false) -> bool
close_path :: proc(d: ^Drawing)
curve_to :: proc(d: ^Drawing, c1, c2, p: [2]f32)
draw :: proc(d: ^Drawing) -> clay.CustomElementConfig
draw_image :: proc(d: ^Drawing, img: Image, pos, size: [2]f32, tint := Color{255, 255, 255, 255})
draw_text :: proc(d: ^Drawing, s: string, pos: [2]f32, style := TextStyle.Body, color: Color)
drawing :: proc(scale: f32 = 1) -> ^Drawing
fill_path :: proc(d: ^Drawing, color: Color, even_odd := false)
line_to :: proc(d: ^Drawing, p: [2]f32)
move_to :: proc(d: ^Drawing, p: [2]f32)
opacity :: proc(d: ^Drawing, alpha: f32) -> bool
quad_to :: proc(d: ^Drawing, c, p: [2]f32)
rect_path :: proc(d: ^Drawing, pos, size: [2]f32, radius: f32 = 0)
render_image :: proc(d: ^Drawing, width, height: int) -> Image
stroke_path :: proc(d: ^Drawing, color: Color, width: f32, cap := Line_Cap.Round, join := Line_Join.Round, miter_limit: f32 = 4)
transform :: proc(d: ^Drawing, translate := [2]f32{}, rotate: f32 = 0, scale := [2]f32{1, 1}) -> bool

Types

Drawing

Drawing :: struct {
  base:   f32, // the scale given to `drawing`
  path:   Path_Builder, // the current path, in pixels; its `m` is the current transform
  cur:    [2]f32, // the current point, in drawing coordinates
  start:  [2]f32, // where the current subpath started
  ops:    [dynamic]Draw_Op,
  saved:  [dynamic]Mat, // transforms of the enclosing `transform` blocks
  groups: int, // open `clip` and `opacity` blocks
}

A drawing being recorded; build it with the procs in this file, not by hand.

Field	Type	Notes
base	f32	the scale given to drawing
path	Path_Builder	the current path, in pixels; its m is the current transform
cur	[2]f32	the current point, in drawing coordinates
start	[2]f32	where the current subpath started
ops	[dynamic]Draw_Op
saved	[dynamic]Mat	transforms of the enclosing transform blocks
groups	int	open clip and opacity blocks

Source: kiln/draw.odin:41

Line_Cap

Line_Cap :: enum {
  Butt,
  Round,
  Square,
}

Values: .Butt, .Round, .Square

Source: kiln/draw.odin:28

Line_Join

Line_Join :: enum {
  Miter,
  Round,
  Bevel,
}

Values: .Miter, .Round, .Bevel

Source: kiln/draw.odin:34

Procedures

arc

arc :: proc(d: ^Drawing, center: [2]f32, radius, from, to: f32)

A circular arc around center from angle from to to. A line connects the current point with the start of the arc; to < from draws counter-clockwise.

Argument	Type	Default
d	^Drawing	required
center	[2]f32	required
radius	f32	required
from	f32	required
to	f32	required

Source: kiln/draw.odin:144

circle_path

circle_path :: proc(d: ^Drawing, center: [2]f32, radius: f32)

A circle as a closed subpath.

Argument	Type	Default
d	^Drawing	required
center	[2]f32	required
radius	f32	required

Source: kiln/draw.odin:176

clip

clip :: proc(d: ^Drawing, even_odd := false) -> bool

Cuts off what is drawn inside at the current path (which it uses up):

kiln.circle_path(d, c, r)
if kiln.clip(d) {kiln.draw_image(d, photo, c - r, 2 * r)}

Argument	Type	Default
d	^Drawing	required
even_odd	bool	false

Returns	Type
#0	bool

Source: kiln/draw.odin:319

close_path

close_path :: proc(d: ^Drawing)

Closes the current subpath with a line back to its start.

Argument	Type	Default
d	^Drawing	required

Source: kiln/draw.odin:151

curve_to

curve_to :: proc(d: ^Drawing, c1, c2, p: [2]f32)

A cubic Bézier curve from the current point to p with the control points c1 and c2.

Argument	Type	Default
d	^Drawing	required
c1	[2]f32	required
c2	[2]f32	required
p	[2]f32	required

Source: kiln/draw.odin:136

draw

draw :: proc(d: ^Drawing) -> clay.CustomElementConfig

The custom config that makes an element show a drawing: custom = kiln.draw(d).

Argument	Type	Default
d	^Drawing	required

Returns	Type
#0	clay.CustomElementConfig

Source: kiln/draw.odin:107

draw_image

draw_image :: proc(d: ^Drawing, img: Image, pos, size: [2]f32, tint := Color{255, 255, 255, 255})

An image stretched over the rectangle at pos with size, its pixels multiplied by tint.

Argument	Type	Default
d	^Drawing	required
img	Image	required
pos	[2]f32	required
size	[2]f32	required
tint	[4]f32	Color{255, 255, 255, 255}

Source: kiln/draw.odin:236

draw_text

draw_text :: proc(d: ^Drawing, s: string, pos: [2]f32, style := TextStyle.Body, color: Color)

One line of text in a text style, its top left corner at pos. The letters are filled outlines, so they turn and scale with transform. measure gives the width in pixels.

Argument	Type	Default
d	^Drawing	required
s	string	required
pos	[2]f32	required
style	TextStyle	TextStyle.Body
color	Color	required

Source: kiln/draw.odin:244

drawing

drawing :: proc(scale: f32 = 1) -> ^Drawing

A new drawing for this frame. scale turns drawing coordinates into pixels: 1 draws in pixels, scale_factor() in units.

Argument	Type	Default
scale	f32	1

Returns	Type
#0	^Drawing

Source: kiln/draw.odin:97

fill_path

fill_path :: proc(d: ^Drawing, color: Color, even_odd := false)

Fills the inside of the current path (open subpaths are closed) and starts a new path. even_odd makes overlapping parts holes, otherwise everything enclosed is filled.

Argument	Type	Default
d	^Drawing	required
color	Color	required
even_odd	bool	false

Source: kiln/draw.odin:205

line_to

line_to :: proc(d: ^Drawing, p: [2]f32)

A straight line from the current point to p.

Argument	Type	Default
d	^Drawing	required
p	[2]f32	required

Source: kiln/draw.odin:122

move_to

move_to :: proc(d: ^Drawing, p: [2]f32)

Starts a new subpath at p.

Argument	Type	Default
d	^Drawing	required
p	[2]f32	required

Source: kiln/draw.odin:116

opacity

opacity :: proc(d: ^Drawing, alpha: f32) -> bool

Draws what is inside on its own and blends it with alpha (0..1), so overlapping parts do not show through each other.

Argument	Type	Default
d	^Drawing	required
alpha	f32	required

Returns	Type
#0	bool

Source: kiln/draw.odin:337

quad_to

quad_to :: proc(d: ^Drawing, c, p: [2]f32)

A quadratic Bézier curve from the current point to p with the control point c.

Argument	Type	Default
d	^Drawing	required
c	[2]f32	required
p	[2]f32	required

Source: kiln/draw.odin:129

rect_path

rect_path :: proc(d: ^Drawing, pos, size: [2]f32, radius: f32 = 0)

A rectangle as a closed subpath, with rounded corners if radius > 0.

Argument	Type	Default
d	^Drawing	required
pos	[2]f32	required
size	[2]f32	required
radius	f32	0

Source: kiln/draw.odin:157

render_image

render_image :: proc(d: ^Drawing, width, height: int) -> Image

Draws a drawing into a new width x height image (pixels), e.g. a picture that is expensive to draw and changes rarely. Free it with destroy_image.

Argument	Type	Default
d	^Drawing	required
width	int	required
height	int	required

Returns	Type
#0	Image

Source: kiln/draw.odin:361

stroke_path

stroke_path :: proc(
  d: ^Drawing,
  color: Color,
  width: f32,
  cap := Line_Cap.Round,
  join := Line_Join.Round,
  miter_limit: f32 = 4,
)

Draws the outline of the current path width wide and starts a new path. A subpath of a single point gives a dot with round or square caps.

Argument	Type	Default
d	^Drawing	required
color	Color	required
width	f32	required
cap	Line_Cap	Line_Cap.Round
join	Line_Join	Line_Join.Round
miter_limit	f32	4

Source: kiln/draw.odin:215

transform

transform :: proc(d: ^Drawing, translate := [2]f32{}, rotate: f32 = 0, scale := [2]f32{1, 1}) -> bool

Moves, turns and scales what is drawn inside: the origin moves to translate, then the coordinates turn by rotate and are scaled by scale.

if kiln.transform(d, translate = center, rotate = angle) { ... }

Argument	Type	Default
d	^Drawing	required
translate	[2]f32	[2]f32{}
rotate	f32	0
scale	[2]f32	[2]f32{1, 1}

Returns	Type
#0	bool

Source: kiln/draw.odin:300