//! The sketch library: compiled into every app and reloaded with it. //! //! An app is an ordinary Zig module. Every declaration is optional: //! //! pub const name = "my sketch"; //! pub const width = 960; //! pub const height = 600; //! pub const State = struct { ... }; // persisted and snapshotted: no pointers //! pub const Session = struct { ... }; // survives reloads, never saved //! pub const commands = .{"hello"}; // console completions //! pub fn init(state: *State, host: sk.Host) void //! pub fn update(state: *State, in: *const sk.Input) void //! pub fn draw(state: *const State, session: *Session, f: *sk.Frame) void //! pub fn command(state: *State, session: *Session, c: *sk.Console, line: []const u8) !bool //! //! `update` must be deterministic: the host replays recorded input through it. //! `draw` presents state as pictures and sound, and may only change `Session`. //! Geometry and colors are duck-typed: see `shape`. const std = @import("std"); pub const abi = @import("abi"); pub const shape = @import("shape.zig"); pub const Key = abi.Key; pub const Camera = @import("camera.zig").Camera; pub const tween = @import("tween.zig"); pub const web = @import("web.zig"); pub const Rect = abi.Rect; pub const Color = abi.Color; pub const Event = abi.Event; pub const Input = abi.Input; pub const Mode = abi.Mode; pub const Host = abi.Host; pub const Image = abi.Image; pub const Audio = abi.Audio; pub const Cursor = abi.Cursor; pub const Voice = abi.Voice; /// What `draw` receives: input, host services, allocators and the command list. pub const Frame = struct { ctx: *const abi.Context, in: *const Input, host: Host, /// Frame lifetime. arena: std.mem.Allocator, /// Session lifetime; survives reloads. gpa: std.mem.Allocator, pub fn init(ctx: *const abi.Context) Frame { return .{ .ctx = ctx, .in = ctx.input, .host = ctx.host, .arena = ctx.arena, .gpa = ctx.gpa }; } pub fn emit(f: *Frame, command: abi.Command) void { f.ctx.commands.append(f.arena, command) catch f.host.log("frame arena full: command dropped"); } pub fn clear(f: *Frame, color: anytype) void { f.emit(.{ .clear = shape.color(color) }); } pub fn fill(f: *Frame, r: anytype, color: anytype) void { f.emit(.{ .rect = .{ .dst = shape.rect(r), .color = shape.color(color) } }); } /// `options` may set `.src` (a rect within the image) and `.tint` (a color). pub fn image(f: *Frame, img: Image, dst: anytype, options: anytype) void { const O = @TypeOf(options); f.emit(.{ .image = .{ .image = img, .dst = shape.rect(dst), .src = if (@hasField(O, "src")) shape.rect(options.src) else .{}, .tint = if (@hasField(O, "tint")) shape.color(options.tint) else .white, } }); } /// `bytes` must live until the frame is consumed: literals, `arena` and /// session memory all do. pub fn text(f: *Frame, x: f32, y: f32, scale: f32, bytes: []const u8, color: anytype) void { f.emit(.{ .text = .{ .x = x, .y = y, .scale = scale, .color = shape.color(color), .bytes = bytes } }); } pub fn print(f: *Frame, x: f32, y: f32, scale: f32, color: anytype, comptime fmt: []const u8, args: anytype) void { f.text(x, y, scale, f.format(fmt, args), color); } /// Formats into the frame arena. pub fn format(f: *Frame, comptime fmt: []const u8, args: anytype) []const u8 { return std.fmt.allocPrint(f.arena, fmt, args) catch "?"; } /// A rect, or `null` to stop clipping. pub fn clip(f: *Frame, r: anytype) void { f.emit(.{ .clip = if (@TypeOf(r) == @TypeOf(null)) null else shape.rect(r) }); } pub fn canvas(f: *Frame, w: u32, h: u32) void { f.emit(.{ .canvas = .{ .w = w, .h = h } }); } pub fn cursor(f: *Frame, kind: Cursor) void { f.emit(.{ .cursor = kind }); } pub fn voice(f: *Frame, v: Voice) void { f.emit(.{ .voice = v }); } pub fn audio(f: *Frame, key: u32, samples: []const f32, options: struct { clear: bool = false }) void { f.emit(.{ .audio = .{ .key = key, .samples = samples, .clear = options.clear } }); } pub fn pixels(f: *Frame, img: Image, w: u32, h: u32, rgba: []const u8, options: struct { premultiplied: bool = false }) void { f.emit(.{ .pixels = .{ .image = img, .w = w, .h = h, .rgba = rgba, .premultiplied = options.premultiplied } }); } /// Runs GPU work described as data (see `abi.gpu`) into `pass.image`. pub fn gpu(f: *Frame, pass: abi.gpu.Pass) void { f.emit(.{ .gpu = pass }); } pub fn quit(f: *Frame) void { f.emit(.quit); } }; /// What `command` receives: somewhere to answer, and the current input. pub const Console = struct { host: Host, in: *const Input, pub fn log(c: *Console, message: []const u8) void { c.host.log(message); } pub fn print(c: *Console, comptime fmt: []const u8, args: anytype) void { c.host.print(fmt, args); } }; /// The entry points of `App`, for a host that links it statically. pub fn sketch(comptime App: type) abi.Sketch { const G = Glue(App); return .{ .info = G.info, .defaults = G.defaults, .init = G.init, .update = G.update, .draw = G.draw, .command = G.command }; } /// Exports `App` under `abi.Sketch.symbols`, for a hot-reloaded library. pub fn exportSketch(comptime App: type) void { const G = Glue(App); const names = abi.Sketch.symbols; @export(&G.info, .{ .name = names.info }); @export(&G.defaults, .{ .name = names.defaults }); @export(&G.init, .{ .name = names.init }); @export(&G.update, .{ .name = names.update }); @export(&G.draw, .{ .name = names.draw }); @export(&G.command, .{ .name = names.command }); } pub fn Glue(comptime App: type) type { return struct { pub const State = if (@hasDecl(App, "State")) App.State else struct {}; pub const Session = if (@hasDecl(App, "Session")) App.Session else struct {}; pub const description: abi.Info = .{ .abi = abi.hash, .name = if (@hasDecl(App, "name")) App.name else "sketch", .width = if (@hasDecl(App, "width")) App.width else 960, .height = if (@hasDecl(App, "height")) App.height else 600, .state = abi.layout.of(State, .forbidden), .session = abi.layout.of(Session, .host_only), .commands = if (@hasDecl(App, "commands")) &App.commands else &.{}, }; fn state(ptr: [*]u8) *State { return @ptrCast(@alignCast(ptr)); } fn session(ptr: [*]u8) *Session { return @ptrCast(@alignCast(ptr)); } fn arity(comptime func: anytype) usize { return @typeInfo(@TypeOf(func)).@"fn".params.len; } pub fn info() callconv(.c) *const abi.Info { return &description; } pub fn defaults(which: abi.Memory, ptr: [*]u8) callconv(.c) void { switch (which) { .state => state(ptr).* = .{}, .session => session(ptr).* = .{}, } } pub fn init(ctx: *const abi.Context, s: [*]u8) callconv(.c) void { if (!@hasDecl(App, "init")) return; switch (comptime arity(App.init)) { 1 => App.init(state(s)), else => App.init(state(s), ctx.host), } } pub fn update(ctx: *const abi.Context, s: [*]u8) callconv(.c) void { if (@hasDecl(App, "update")) App.update(state(s), ctx.input); } pub fn draw(ctx: *const abi.Context, s: [*]const u8, ss: [*]u8) callconv(.c) void { if (!@hasDecl(App, "draw")) return; var f: Frame = .init(ctx); const current: *const State = @ptrCast(@alignCast(s)); switch (comptime arity(App.draw)) { 2 => App.draw(current, &f), else => App.draw(current, session(ss), &f), } } pub fn command(ctx: *const abi.Context, s: [*]u8, ss: [*]u8, line: *const []const u8) callconv(.c) bool { if (!@hasDecl(App, "command")) return false; var c: Console = .{ .host = ctx.host, .in = ctx.input }; return switch (comptime arity(App.command)) { 3 => App.command(state(s), &c, line.*), else => App.command(state(s), session(ss), &c, line.*), } catch |err| { c.print("{t}. Type help for usage.", .{err}); return true; }; } }; } test { _ = abi.layout; _ = shape; _ = @import("camera.zig"); _ = tween; }