canvas

The built-in canvas pixel buffer is deprecated; see what it did and how to move the same code to std:img.

canvas(width, height, background) is a built-in in-memory pixel buffer that you could fill, resize and export. It is deprecated: img does everything it did and also draws shapes and text, applies filters, reads and writes files, and reads and sets single pixels. Every canvas method gives a deprecation warning. Existing code keeps working, and a canvas converts to an image with toImage(), so you can move over a piece at a time. For new code, use img.new.

What a canvas does#

A canvas is made with a size and a background colour ("#rgb", "#rrggbb", "#rrggbbaa" or {r, g, b, a}). Its size can be 0, up to 100000 pixels a side and 100 megapixels. A bad colour or size throws ValueError.

auto c = canvas(4, 2, "#ffffff")
log c.width() c.height() c.pixels()   // 4 2 8
c.fill("#ff0000")                     // every pixel red
c.clear()                             // back to the background, white
c.stretch(8, 4)                       // resize in place, nearest pixel
log c.toURL()                         // a "data:image/png;base64,..." string

c.toArray() returns the pixels as channel values. A canvas can't read or set one pixel, and it can't draw.

Moving to img#

canvas.toImage() returns a copy as an *img.Image, so the two don't affect each other. It throws ValueError for a canvas with no pixels, since an image is at least 1 by 1.

auto c = canvas(4, 2, "#ffffff")
*img.Image pic = c.toImage()

Everything else maps to a method of the image:

The same steps with img run without a warning, and the image can be saved too:

import "std:img"

*img.Image pic = img.new(4, 2, {fill: "#ffffff"})
log pic.width() pic.height() pic.width() * pic.height()

pic.fill("#ff0000")
log pic.pixel(1, 1)

pic.fill("#ffffff")
auto bigger = pic.resize(8, 4, {filter: "nearest"})
log bigger.width() bigger.height()
log bigger.toDataURL().unwrap().startsWith("data:image/png;base64,")
log pic.pixels().len

import "std:img"

*img.Image pic = img.new(1, 1)
log pic.width() pic.height()

import "std:img"

*img.Image pic = img.new(1, 1)
log pic.width() pic.height()

3 2