Documentation / Builder packages / @web/canvas

@web/canvas

@web/canvas provides 2D canvas drawing as a binding-backed runtime package. It exposes opaque handle types and free functions for drawing shapes, text, images and pixels.

Canvas drawing

@web/canvas gives you 2D canvas drawing. Import it when you need to draw shapes, text, images or pixels onto a <canvas> element.

The package ships as a skeleton. It will grow as the language and standard library mature.

Importing

Bring in the functions you need with a grouped import.


    import @web/canvas {get_canvas, context_2d, set_fill_style, fill_rect}

    canvas = get_canvas("my-canvas") catch:
        assert(false, "canvas not found")
    ;

    ctx ~= context_2d(canvas) catch:
        assert(false, "no 2D context")
    ;

    set_fill_style(~ctx, "red")
    fill_rect(~ctx, 10.0, 10.0, 50.0, 50.0)

Opaque types

The package exposes opaque handle types. You can't construct or inspect them. You obtain them through functions.

  • CanvasElement from get_canvas or create_canvas
  • Canvas2d from context_2d
  • CanvasGradient from gradient creation functions
  • CanvasImage from get_image or create_image
  • CanvasImageData from get_image_data or create_image_data
  • CanvasPattern from create_pattern
  • CanvasTextMetrics from measure_text

Mutable access

Functions that change the canvas need mutable access with ~. Query functions use shared access. The ~ goes before the value you're mutating.


    -- mutating: needs ~ on the argument
    fill_rect(~ctx, 0.0, 0.0, 100.0, 100.0)

    -- querying: shared access, no ~
    width = canvas_width(canvas)

environment. For the full function surface, opaque type rules, pixel access and deferred surfaces, see @web/canvas advanced.

@web/canvas provides 2D canvas drawing as a builder binding-backed runtime package. It belongs to the Builder origin family with ExternalBinding backing, so the compiler registers typed external functions and opaque types from annotated JavaScript. See Package origins and backing for origin and backing rules.

@web/canvas ships as a skeleton. The current surface covers element management, context state, rectangles, paths, text, gradients, patterns, image drawing, image data and pixel access. It will grow as the language stabilises and the standard library expands.

Import roots

Import individual symbols or the whole namespace:


    import @web/canvas {get_canvas, context_2d, fill_rect}

    import @web/canvas

Opaque types

@web/canvas exposes seven opaque handle types. They have no public fields, cannot be constructed with struct syntax and must not be inspected directly. You obtain them only through @web/canvas functions.

| Type | Description | |---|---| | CanvasElement | A <canvas> DOM element handle | | Canvas2d | A 2D rendering context handle | | CanvasGradient | A gradient object handle | | CanvasPattern | A pattern object handle | | CanvasImage | An image element handle | | CanvasImageData | An ImageData pixel buffer handle | | CanvasTextMetrics | A text measurement result handle |

All opaque types lower to object references in the JS backend. The Wasm backend does not support @web/canvas and rejects reachable calls before lowering.

Canvas element management

| Function | Parameters | Returns | Access | |---|---|---|---| | get_canvas | id String | CanvasElement, Error! | shared | | create_canvas | width Int, height Int | CanvasElement | shared | | get_image | id String | CanvasImage, Error! | shared | | create_image | src String | CanvasImage | shared | | create_image_with_size | src String, width Int, height Int | CanvasImage | shared | | context_2d | canvas CanvasElement | Canvas2d, Error! | shared | | canvas_width | canvas CanvasElement | Int | shared | | canvas_height | canvas CanvasElement | Int | shared | | canvas_client_width | canvas CanvasElement | Int | shared | | canvas_client_height | canvas CanvasElement | Int | shared | | set_canvas_width | canvas ~CanvasElement, width Int | void | mutable | | set_canvas_height | canvas ~CanvasElement, height Int | void | mutable | | set_canvas_size | canvas ~CanvasElement, width Int, height Int | void | mutable | | to_data_url | canvas CanvasElement | String, Error! | shared | | to_data_url_type | canvas CanvasElement, mime_type String | String, Error! | shared | | to_data_url_quality | canvas CanvasElement, mime_type String, quality Float | String, Error! | shared |

Image queries

| Function | Parameters | Returns | Access | |---|---|---|---| | image_width | image CanvasImage | Int | shared | | image_height | image CanvasImage | Int | shared | | image_natural_width | image CanvasImage | Int | shared | | image_natural_height | image CanvasImage | Int | shared | | image_is_loaded | image CanvasImage | Bool | shared |

Context state

| Function | Parameters | Returns | Access | |---|---|---|---| | save | ctx ~Canvas2d | void | mutable | | restore | ctx ~Canvas2d | void | mutable | | reset | ctx ~Canvas2d | void | mutable | | is_context_lost | ctx Canvas2d | Bool | shared |

Rectangles

| Function | Parameters | Returns | Access | |---|---|---|---| | clear_rect | ctx ~Canvas2d, x Float, y Float, width Float, height Float | void | mutable | | fill_rect | ctx ~Canvas2d, x Float, y Float, width Float, height Float | void | mutable | | stroke_rect | ctx ~Canvas2d, x Float, y Float, width Float, height Float | void | mutable |

Fill and stroke style

| Function | Parameters | Returns | Access | |---|---|---|---| | set_fill_style | ctx ~Canvas2d, color String | void | mutable | | set_stroke_style | ctx ~Canvas2d, color String | void | mutable | | set_fill_gradient | ctx ~Canvas2d, gradient CanvasGradient | void | mutable | | set_stroke_gradient | ctx ~Canvas2d, gradient CanvasGradient | void | mutable | | set_fill_pattern | ctx ~Canvas2d, pattern CanvasPattern | void | mutable | | set_stroke_pattern | ctx ~Canvas2d, pattern CanvasPattern | void | mutable |

Compositing

| Function | Parameters | Returns | Access | |---|---|---|---| | set_global_alpha | ctx ~Canvas2d, alpha Float | void | mutable | | set_global_composite_operation | ctx ~Canvas2d, operation String | void | mutable |

Line style

| Function | Parameters | Returns | Access | |---|---|---|---| | set_line_width | ctx ~Canvas2d, width Float | void | mutable | | set_line_cap | ctx ~Canvas2d, line_cap String | void | mutable | | set_line_join | ctx ~Canvas2d, line_join String | void | mutable | | set_miter_limit | ctx ~Canvas2d, limit Float | void | mutable | | set_line_dash | ctx ~Canvas2d, dash Float, gap Float | void | mutable | | set_line_dash_solid | ctx ~Canvas2d | void | mutable | | set_line_dash_offset | ctx ~Canvas2d, offset Float | void | mutable |

Text rendering settings

| Function | Parameters | Returns | Access | |---|---|---|---| | set_font | ctx ~Canvas2d, font String | void | mutable | | set_text_align | ctx ~Canvas2d, align String | void | mutable | | set_text_baseline | ctx ~Canvas2d, baseline String | void | mutable | | set_direction | ctx ~Canvas2d, direction String | void | mutable | | set_letter_spacing | ctx ~Canvas2d, spacing String | void | mutable | | set_word_spacing | ctx ~Canvas2d, spacing String | void | mutable | | set_font_kerning | ctx ~Canvas2d, kerning String | void | mutable | | set_font_stretch | ctx ~Canvas2d, stretch String | void | mutable | | set_font_variant_caps | ctx ~Canvas2d, caps String | void | mutable | | set_text_rendering | ctx ~Canvas2d, rendering String | void | mutable | | set_lang | ctx ~Canvas2d, lang String | void | mutable |

Image smoothing, filter and shadow

| Function | Parameters | Returns | Access | |---|---|---|---| | set_image_smoothing_enabled | ctx ~Canvas2d, enabled Bool | void | mutable | | set_image_smoothing_quality | ctx ~Canvas2d, quality String | void | mutable | | set_filter | ctx ~Canvas2d, filter String | void | mutable | | set_shadow_color | ctx ~Canvas2d, color String | void | mutable | | set_shadow_blur | ctx ~Canvas2d, blur Float | void | mutable | | set_shadow_offset | ctx ~Canvas2d, x Float, y Float | void | mutable |

Path construction

| Function | Parameters | Returns | Access | |---|---|---|---| | begin_path | ctx ~Canvas2d | void | mutable | | move_to | ctx ~Canvas2d, x Float, y Float | void | mutable | | line_to | ctx ~Canvas2d, x Float, y Float | void | mutable | | close_path | ctx ~Canvas2d | void | mutable | | rect | ctx ~Canvas2d, x Float, y Float, width Float, height Float | void | mutable | | round_rect | ctx ~Canvas2d, x Float, y Float, width Float, height Float, radius Float | Error! | mutable | | arc | ctx ~Canvas2d, x Float, y Float, radius Float, start_angle Float, end_angle Float | Error! | mutable | | arc_counterclockwise | ctx ~Canvas2d, x Float, y Float, radius Float, start_angle Float, end_angle Float | Error! | mutable | | arc_to | ctx ~Canvas2d, x1 Float, y1 Float, x2 Float, y2 Float, radius Float | Error! | mutable | | quadratic_curve_to | ctx ~Canvas2d, cpx Float, cpy Float, x Float, y Float | void | mutable | | bezier_curve_to | ctx ~Canvas2d, cp1x Float, cp1y Float, cp2x Float, cp2y Float, x Float, y Float | void | mutable | | ellipse | ctx ~Canvas2d, x Float, y Float, radius_x Float, radius_y Float, rotation Float, start_angle Float, end_angle Float | Error! | mutable | | ellipse_counterclockwise | ctx ~Canvas2d, x Float, y Float, radius_x Float, radius_y Float, rotation Float, start_angle Float, end_angle Float | Error! | mutable |

Fill, stroke and clip

| Function | Parameters | Returns | Access | |---|---|---|---| | fill | ctx ~Canvas2d | void | mutable | | fill_even_odd | ctx ~Canvas2d | void | mutable | | stroke | ctx ~Canvas2d | void | mutable | | clip | ctx ~Canvas2d | void | mutable | | clip_even_odd | ctx ~Canvas2d | void | mutable | | is_point_in_path | ctx Canvas2d, x Float, y Float | Bool | shared | | is_point_in_stroke | ctx Canvas2d, x Float, y Float | Bool | shared |

Transformations

| Function | Parameters | Returns | Access | |---|---|---|---| | translate | ctx ~Canvas2d, x Float, y Float | void | mutable | | rotate | ctx ~Canvas2d, angle Float | void | mutable | | scale | ctx ~Canvas2d, x Float, y Float | void | mutable | | transform | ctx ~Canvas2d, a Float, b Float, c Float, d Float, e Float, f Float | void | mutable | | set_transform | ctx ~Canvas2d, a Float, b Float, c Float, d Float, e Float, f Float | void | mutable | | reset_transform | ctx ~Canvas2d | void | mutable |

Text drawing

| Function | Parameters | Returns | Access | |---|---|---|---| | fill_text | ctx ~Canvas2d, text String, x Float, y Float | void | mutable | | fill_text_max_width | ctx ~Canvas2d, text String, x Float, y Float, max_width Float | void | mutable | | stroke_text | ctx ~Canvas2d, text String, x Float, y Float | void | mutable | | stroke_text_max_width | ctx ~Canvas2d, text String, x Float, y Float, max_width Float | void | mutable | | measure_text | ctx Canvas2d, text String | CanvasTextMetrics | shared |

Text metrics

| Function | Parameters | Returns | Access | |---|---|---|---| | text_width | metrics CanvasTextMetrics | Float | shared | | text_actual_bounding_box_left | metrics CanvasTextMetrics | Float | shared | | text_actual_bounding_box_right | metrics CanvasTextMetrics | Float | shared | | text_actual_bounding_box_ascent | metrics CanvasTextMetrics | Float | shared | | text_actual_bounding_box_descent | metrics CanvasTextMetrics | Float | shared | | text_font_bounding_box_ascent | metrics CanvasTextMetrics | Float | shared | | text_font_bounding_box_descent | metrics CanvasTextMetrics | Float | shared |

Gradients

| Function | Parameters | Returns | Access | |---|---|---|---| | create_linear_gradient | ctx Canvas2d, x0 Float, y0 Float, x1 Float, y1 Float | CanvasGradient, Error! | shared | | create_radial_gradient | ctx Canvas2d, x0 Float, y0 Float, r0 Float, x1 Float, y1 Float, r1 Float | CanvasGradient, Error! | shared | | create_conic_gradient | ctx Canvas2d, start_angle Float, x Float, y Float | CanvasGradient, Error! | shared | | add_color_stop | gradient ~CanvasGradient, offset Float, color String | Error! | mutable |

Patterns

| Function | Parameters | Returns | Access | |---|---|---|---| | create_pattern | ctx Canvas2d, image CanvasImage, repetition String | CanvasPattern, Error! | shared | | create_canvas_pattern | ctx Canvas2d, canvas CanvasElement, repetition String | CanvasPattern, Error! | shared |

Image drawing

| Function | Parameters | Returns | Access | |---|---|---|---| | draw_image | ctx ~Canvas2d, image CanvasImage, x Float, y Float | Error! | mutable | | draw_image_scaled | ctx ~Canvas2d, image CanvasImage, x Float, y Float, width Float, height Float | Error! | mutable | | draw_image_cropped | ctx ~Canvas2d, image CanvasImage, source_x Float, source_y Float, source_width Float, source_height Float, x Float, y Float, width Float, height Float | Error! | mutable | | draw_canvas | ctx ~Canvas2d, canvas CanvasElement, x Float, y Float | Error! | mutable | | draw_canvas_scaled | ctx ~Canvas2d, canvas CanvasElement, x Float, y Float, width Float, height Float | Error! | mutable |

Image drawing functions fail with Error! when the image has not finished loading.

Image data

| Function | Parameters | Returns | Access | |---|---|---|---| | get_image_data | ctx Canvas2d, x Int, y Int, width Int, height Int | CanvasImageData, Error! | shared | | create_image_data | ctx Canvas2d, width Int, height Int | CanvasImageData, Error! | shared | | create_image_data_from | ctx Canvas2d, image_data CanvasImageData | CanvasImageData, Error! | shared | | put_image_data | ctx ~Canvas2d, image_data CanvasImageData, x Float, y Float | Error! | mutable | | put_image_data_dirty | ctx ~Canvas2d, image_data CanvasImageData, x Float, y Float, dirty_x Float, dirty_y Float, dirty_width Float, dirty_height Float | Error! | mutable | | image_data_width | image_data CanvasImageData | Int | shared | | image_data_height | image_data CanvasImageData | Int | shared |

Pixel access

| Function | Parameters | Returns | Access | |---|---|---|---| | image_data_get_red | image_data CanvasImageData, x Int, y Int | Int, Error! | shared | | image_data_get_green | image_data CanvasImageData, x Int, y Int | Int, Error! | shared | | image_data_get_blue | image_data CanvasImageData, x Int, y Int | Int, Error! | shared | | image_data_get_alpha | image_data CanvasImageData, x Int, y Int | Int, Error! | shared | | image_data_set_pixel | image_data ~CanvasImageData, x Int, y Int, red Int, green Int, blue Int, alpha Int | Error! | mutable | | image_data_clear_pixel | image_data ~CanvasImageData, x Int, y Int | Error! | mutable |

Pixel getters and setters fail with Error! when coordinates fall outside the image data bounds. Channel values clamp to 0 through 255.

Access and return contracts

Functions that mutate the context take ~Canvas2d (mutable access). Query functions take Canvas2d (shared access). The same pattern applies to ~CanvasElement, ~CanvasGradient and ~CanvasImageData. Fresh values from creation functions satisfy mutable parameters without ~. Existing places require explicit ~ at the call site.

All parameters stay positional-only. Named arguments are not supported because binding-backed packages do not expose source-function features.

Opaque type rules

  • Do not construct opaque types with struct syntax.
  • Do not inspect opaque type fields.
  • Opaque types have no source-visible methods. Use the free functions.
  • The @html package provides a Canvas wrapper struct with receiver methods for a more ergonomic drawing API.

Backend behaviour

The JS backend fully supports @web/canvas. When canvas functions are reachable, the build emits the canvas.js runtime asset, a generated glue module and an import map entry for @moth/runtime.

The Wasm backend rejects reachable @web/canvas calls before lowering. Canvas support requires a browser JS environment.

Teardown

@web/canvas defines no teardown, close or disposal functions. Opaque handles are managed by the host JavaScript runtime.

Unsupported source forms

  • Direct symbol-path imports such as import @web/canvas/get_canvas face rejection. Use grouped or namespace imports.
  • Named arguments are not supported. Binding-backed calls stay positional-only.
  • The package does not expose receiver methods, source-defined types or constants.
  • Opaque types cannot be constructed or inspected from Moth source.

Deferred surfaces

@web/canvas ships as a skeleton. Deferred surfaces include async image-loading helpers, toBlob and captureStream, raw typed-array and arbitrary line-dash array access, Path2D, DOMMatrix, OffscreenCanvas, ImageBitmap, video sources and WebGL. These will arrive as the language and external package ABI mature. See progress matrix for current status.

Related concepts