`ctx` module

Note

Some functions might be better documented in the upstream uctx docs

Apologies for the divergence.

class ctx.Context(*args, **kwargs)

Context is the rendering/rasterization API used by st3m.

It’s a WebCanvas-style vector API, with an implicit pen which can be moved and can draw lines, arcs, text, etc.

In st3m, the Context object is backed by a drawlist generator. That is, any operation performed on the ctx object will cause an entry to be added to an in-memory draw list. Then, when the rasterizer is ready, it will rasterize said drawlist to pixels in a separate thread.

A Context object is passed to all draw() calls to Responder. This object should only be used within the lifecycle of the draw method and must not be persisted.

For more information, see: https://ctx.graphics/

add_stop(pos: float, color: Tuple[float, float, float], alpha: float) → Context: Adds a color stop for a linear or radial gradient. Pos is a position between 0.0 and 1.0. Should be called after linear_gradient or radial_gradient.

apply_transform(a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float) → Context

Adds a 3x3 matrix on top of the existing user to device space transform.

TODO(q3k): we probably shouldn’t expose this

arc(x: float, y: float, radius: float, angle1: float, angle2: float, direction: float) → Context: TOD(q3k): document

arc_to(x1: float, y1: float, x2: float, y2: float, radius: float) → Context: TOD(q3k): document

begin_path() → Context: Clears the current path if any.

clip() → Context: Use the current path as a clipping mask, subsequent draw calls are limited by the path. The only way to increase the visible area is to first call save and then later restore to undo the clip.

close_path() → Context: Close the current open path with a curve back to where the current sequence of path segments started.

curve_to(cx0: float, cy0: float, cx1: float, cy1: float, x: float, y: float) → Context: Add a cubic bezier segment to current path, with control handles at cx0, cy0 and cx1,cy1, the virtual pens new position is x, y.

fill() → Context: Fill the current path with the current source (color, gradient or texture).

get_font_name(ix: int) → str

Returns font name from internal font index. See ctx_config.h for defined fonts.

TODO(q3k): expose these font indices into mpy

gray(a: float) → Context: Set current draw color to a floating point grayscale value from 0 to 1.

image(path: str, x: float, y: float, w: float, h: float, clip_x: Optional[float] = None, clip_y: Optional[float] = None, clip_width: Optional[float] = None, clip_height: Optional[float] = None) → Context: Draw the image at path a in a rectangle with upper left coordinates at x,y which is w wide and h high. If w or h is -1 the other is set maintaining aspect ratio, if both are -1 the pixel dimensions of the image is used. Supports PNG and JPEG files.

line_to(x: float, y: float) → Context: Adds a line segment to the path, from the position of the virtual pen to the given coordinates, the coordinates are the new position of the virtual pen.

linear_gradient(x0: float, y0: float, x1: float, y1: float) → Context

Change the source to a linear gradient from x0,y0 to x1,y1, by default an empty gradient from black to white exists, add stops with add_stop to specify a custom gradient.

This is a simple example rendering a rainbow gradient on the right side of the screen:

>>> ctx.linear_gradient(0.18*120,0.5*120,0.95*120,0.5*120)
>>> ctx.add_stop(0.0, [1.0,0.0,0.0], 1.0)
>>> ctx.add_stop(0.2, [1.0,1.0,0.0], 1.0)
>>> ctx.add_stop(0.4, [0.0,1.0,0.0], 1.0)
>>> ctx.add_stop(0.6, [0.0,1.0,1.0], 1.0)
>>> ctx.add_stop(0.8, [0.0,0.0,1.0], 1.0)
>>> ctx.add_stop(1.0, [1.0,0.0,1.0], 1.0)
>>> ctx.rectangle(-120, -120, 240, 240)
>>> ctx.fill()

logo(x: float, y: float, dim: float) → Context: Draws the ctx logo, centered at x,y with a footprint of roughly dim units.

move_to(x: float, y: float) → Context: Moves the virtual pen to the given coordinates without drawing anything.

preserve() → Context: TOD(q3k): document

quad_to(cx: float, cy: float, x: float, y: float) → Context: Add a quadratic bezier segment to current path with control point at cx,cy ending at x,y.

radial_gradient(x0: float, y0: float, r0: float, x1: float, y1: float, r1: float) → Context

Change the source to a radial gradient from a circle x0,y0 with radius0 to an outer circle x1,y1 with radidus r1.

NOTE: currently only the second circle’s origin is used, but both radiuses are in use.

rectangle(x: float, y: float, w: float, h: float) → Context: Trace the outline of a rectangle with upper left coordinates at x,y which is w wide and h high.

rel_arc_to(x1: float, y1: float, x2: float, y2: float, radius: float) → Context: TOD(q3k): document

rel_curve_to(cx0: float, cy0: float, cx1: float, cy1: float, x: float, y: float) → Context: Adds a cubic bezier segment using relative coordinates, behaves like curve_to but all coordinate arguments are relative to the coordinates of the virtual pen when called.

rel_line_to(x: float, y: float) → Context: Adds a line segment from the current point to current_x + x, current_y + y.

rel_move_to(x: float, y: float) → Context: Moves the virtual pen a relative amount without adding a segment to the current path.

rel_quad_to(cx: float, cy: float, x: float, y: float) → Context: Adds a quadratic bezier segment using relative coordinates, behaves like quad_to but all coordinate arguments are relative to the coordinates of the virtual pen when called.

restore() → Context: Restores the state previously saved with save, calls to save/restore should be balanced.

rgb(r: float, g: float, b: float) → Context: Set current draw color to an RGB color defined by component values from 0 to 1.

rgba(r: float, g: float, b: float, a: float) → Context: Set current draw color to an RGBA color defined by component values from 0 to 1.

rotate(x: float) → Context: Add rotation to the user to device space transform by specified radians (angle * math.pi / 180).

round_rectangle(x: float, y: float, w: float, h: float, r: float) → Context: Trace the outline of a rectangle with upper left coordinates at x,y which is w wide and h high. With quarter circles with a radius of r for corners.

save() → Context: Stores the transform, clipping state, fill and stroke sources, font size, stroking and dashing options.

scale(x: float, y: float) → Context: Scales the user to device transform.

scope() → Context

Draw an audio ‘oscilloscope’-style visualizer at -120,-120,120,120 bounding box.

Needs to be stroked/filled afterwards.

stroke() → Context: Stroke the current path with the current source (color, gradient or texture), with current line_width

text(text: str) → Context: Add a text fragment using the current fill source, font and font size.

text_width(text: str) → float: Calculates width of rendered text, without rendering it.

translate(x: float, y: float) → Context: Adds translation to the user to device transform.

ALPHABETIC: str = 'alphabetic'

BOTTOM: str = 'bottom'

CENTER: str = 'center'

END: str = 'end'

HANGING: str = 'hanging'

IDEOGRAPHIC: str = 'ideographic'

JUSTIFY: str = 'justify'

LEFT: str = 'left'

MIDDLE: str = 'middle'

RIGHT: str = 'right'

START: str = 'start'

TOP: str = 'top'

font: str = ''

font_size: float = 10

global_alpha: float = 1.0

image_smoothing: bool = True

line_width: float = 1.0

text_align: str = 'start'

text_baseline: str = 'alphabetic'

ctx module

`ctx` module