camera

tape
@profile(t1);
import camera from "camera";
import gfx from "gfx";
import ui from "ui";
import io from "io";

var cam: camera.Camera;
var frames: i64 = 0;

fn on_frame(h: i64) {
    let f: ?*const gfx.Surface = cam.frame();
    if (f == null) { return; }
    frames = frames + 1;
    // look for the code in f!: the surface stays valid until the next frame()
}

component App {
    view {
        ui.Column {
            ui.Watch { handle: cam.handle(); on_ready: on_frame; }
        }
    }
}

pub fn main() -> i32 {
    cam = camera.open("", 1280, 720) or {
        io.println("no camera: {err}");
        return 1;
    };
    let size: gfx.Point = cam.size();
    io.println("capturing at {size.x}x{size.y}");
    ui.run(App {}, 480, 320, "Scan") or { return 1; };
    cam.close();
    return 0;
}

camera.open turns a camera on and starts capturing; frame() hands you the newest picture as a gfx.Surface. Watch the camera’s handle() with ui.Watch (or ui.watch, or screen.poll_watches without a window) and take the frame in the callback: the handle is ready while a new frame waits.

FunctionDoes
camera.list() -> Vec_Device or CameraErrorThe cameras: each a Device { id, name }, the default first. Nothing is turned on
camera.open(device: []const u8, width: i64, height: i64) -> Camera or CameraErrorOpens the camera with that id ("" the default) and starts it
c.size() -> gfx.PointThe frames’ size in pixels (x the width, y the height)
c.frame() -> ?*const gfx.SurfaceThe newest frame since the last call, or null when none has come since; never waits
c.handle() -> i64A handle for ui.watch: ready while a new frame waits
c.close()Turns the camera off and releases it and its frame

The size you ask for is a wish: the camera’s mode nearest to it is used, and size() tells you which. Ask for what you need: 640x480 is plenty for a QR code on a phone’s screen, and smaller frames come faster.

Frames

Frames are latest-only. The camera captures on its own (the system’s thread or callback) into a buffer of the library’s; a newer frame replaces one you have not taken, so a slow handler skips frames rather than falling behind, and frame() gives each frame at most once.

The surface frame() returns is the camera’s: don’t free it. It stays valid until your next frame() or close(); copy it if you need it longer. It is an Rgbx surface (an Argb one, opaque, for a camera that sends JPEG frames). Cameras send YUV or JPEG; camera converts them for you with yuv and image.

When a camera stops delivering (unplugged, or taken by the system), frame() returns null from then on and the handle is no longer ready.

Errors

CameraError:

VariantWhen
UnsupportedThis system has no camera support (Uusi; a Windows without Media Foundation)
DeniedThe user or the system does not allow this program to use the camera
BusyAnother program is using the camera
NotFoundThere is no camera with that id, or no camera at all
FailedThe camera could not be started

Camera access

  • Windows has no dialog: Settings, Privacy & security, Camera, “Let desktop apps access your camera” allows every desktop program or none. When it is off, open returns Denied.
  • macOS asks the user once, in a dialog that names your app. open shows it the first time and waits for the answer; if the user refuses (or has refused before), open returns Denied, and only System Settings, Privacy & Security, Camera can allow it again. The dialog gives the reason your app’s bundle states: your app’s Info.plist needs NSCameraUsageDescription (as recording needs NSMicrophoneUsageDescription), and an app bundle without it is stopped by the system when it opens the camera. tape build does not make app bundles yet, so a program you run from a terminal is asked about as the terminal (“Terminal would like to access the camera”).
  • Linux asks nothing: whoever may open /dev/video* (usually the video group) uses the camera; anyone else gets Denied.

Platforms

  • Windows: Media Foundation’s source reader. Frames come as NV12 or YUY2; a camera that only sends JPEG or H.264 is decoded by Windows. Device ids are the cameras’ symbolic links.
  • macOS: AVFoundation (AVCaptureSession), frames in BGRA. Device ids are the cameras’ unique ids.
  • Linux: V4L2. Device ids are the /dev/video* paths; frames come as YUYV, or as JPEG (MJPEG) when the camera offers a size nearer the one you asked for only that way (many offer their large sizes only as JPEG).
  • Uusi: no cameras: list and open return Unsupported.

The library is camera100 (.dll, .dylib, .so), next to tape; tape build copies it beside your program.

Last modified: