Native images and drawing

Canvas is part of BASIL’s embedded standard library. Use its public names directly, without an import, a .blib, or an external image/font library. The implementation is maintained BASIL source; programs emit only reachable code and immutable tables. See the complete API , format profiles , fonts/text , compiler contracts , and measured integration .

image = NewCanvas(64, 32)
ClearCanvas(BYREF image, RGB(20, 30, 40))
SetPixel(BYREF image, 0, 0, RGBA(255, 0, 0, 128))
copy = CloneCanvas(image)
SetPixel(BYREF copy, 0, 0, RGB(0, 255, 0))
PRINT GetPixel(image, 0, 0).Red
PRINT GetPixel(copy, 0, 0).Green
PRINT CanvasWidth(DecodePNG(EncodePNG(image)))

Run the asset-free drawing example to produce a PNG, BMP and JPEG, reload the PNG and create a thumbnail. File output can use SaveImage(image, "picture.png"); LoadImage(path) identifies supported input by signature. Direct DecodePNG/EncodePNG and corresponding codec APIs avoid dynamic format dispatch. EncodeImage(image) defaults to PNG; a literal or CONST format can select one writer. Filename-driven saving and generic loading retain their possible codecs. WriteFileAtomic(path, EncodePNG(image)) explicitly selects a single writer for a small file-producing program.

Ownership and coordinates

Canvas is an opaque resource owning straight, row-major RGBA8 pixels, four bytes per pixel without row padding. Coordinates start at the top left; X grows right, Y grows down. Pixel coordinates and rectangles use zero-based integer positions; geometry uses pixel-edge DOUBLE coordinates. Colors have BYTE Red/Green/Blue/Alpha fields; RGB supplies alpha 255. NewCanvas initializes every channel to zero, including alpha. CanvasFromRGBA checks the exact byte count and independently owns its input unless explicitly transferred.

Ordinary parameters borrow. Mutation uses BYREF; the checker excludes aliases that could invalidate the borrow, including across suspension. Assignment cannot implicitly copy a Canvas. CloneCanvas creates an independent owner and CanvasBytes returns an independent byte snapshot. Scope, failure and cancellation cleanup release owned storage automatically. A task can receive an explicit TAKE image; resource-containing lists and source-free libraries use the same ownership rules. There is no hidden reference counting or shared mutation.

GetPixel/SetPixel reject out-of-range coordinates. Drawing clips to the target. CopyWithinCanvas handles overlapping self-copies; passing the same owner as a separate source and mutable destination is an invalid conflicting borrow. Operations returning a new image leave the source unchanged on failure. In-place operations do not promise general rollback; prepared text validates its outlines before drawing.

Available operations

Nearest, Bilinear, Area, Bicubic and Lanczos3 sampling are available. Filtering works in premultiplied color to avoid transparent-edge fringes, then produces straight RGBA8. Pure permutations/lossless copies preserve hidden RGB at alpha 0. Antialiasing offers Off, Standard (4×4), and High (8×8) coverage; strokes support caps, joins, dashes and checked miter limits.

CanvasError carries Message, Offset (default -1), and Format (default empty). Malformed/unsupported input and configured limits are recoverable errors. File operations also preserve IoError; numeric/index/string helper failures retain their declared types. A function must catch or declare escaping errors, as with other BASIL APIs. Allocation failure remains fatal. Pixel, encoded-size and work limits are logical bounds, not a whole-process memory reservation or deadline. See the API for each signature and default.