Include timestamp in `frame-event` to allow throttled rendering

[SebastienGllmt]

Often times for animations you want to be able to throttle rendering at some specific speed (ex: 60fps). However, there is no clear way to achieve this with wasi-gfx

Notably, the get-frame returns an empty object

subscribe-frame: func() -> pollable;
get-frame: func() -> option<frame-event>;

record frame-event {
  /// TODO: This field doesn't mean anything.
  /// Can't have empty record. Would like to have a way around this.
  nothing: bool,
}

Notably, from a Javascript host, you actually can get the timestamp from requestAnimationFrame as the first argument to the callback as per the docs

subscribeFrame() {
    const pollable = new Pollable();
    const onFrame = () => { // <- note: timestamp argument ignored
        this.frameEvent = {
            nothing: false,
        };
        pollable.resolve(); // <- we could be passing the timestamp in here
        requestAnimationFrame(onFrame);
    };
    requestAnimationFrame(onFrame);
    return pollable;
}

Without the timestamp argument, requestAnimationFrame will run depending on the user's monitor's refresh rate (so your animation may run over 2x faster for some users!)

Alternative solution

Although from the Javascript host the timestamp is easy to get, maybe that's not the same for every host (although it would be a bit surprising to have a host that can't tell its own clock time)

An alternative, to ensure the host has a clock functionality, would be to rely on wasi-clocks. Although this works, there are two issues with this:

1. Hard hit desired fps. requestAnimationFrame for example runs depending on the user's monitor, so if you want your animation to run at 20fps, it won't work well if the user's monitor is 144hz as 144 is not a multiple of 20. This means you need to round, causing some frames to be slightly longer/shorter than others
2. Hard to synchronize updates between multiple wasi-gfx apps running. requestAnimationFrame gives the same timestamp to all listeners, whereas wasi-clock skews based on render time of other apps (ex: imagine you have two apps A and B. A takes 5ms to render. That means that B's wasi-clock will be 5ms later than what A saw)

[SebastienGllmt]

I created the following workaround for anybody also stuck on this: use the fact that the wasi:clocks implementation has a subscribe_duration that gives a pollable event after a certain duration has passed

How to add it to your wasi-gfx (if you're basing it on the wasi-gfx JS example)

1. Add it to your wit.deps (be sure to use 0.2.0 to compatibility with the wasi-gfx 0.0.1 version dependencies)

[clocks]
url = "https://github.com/WebAssembly/wasi-clocks/archive/refs/tags/v0.2.0.tar.gz"
prefix = "wasi-clocks-0.2.0/wit"

You can now add it to your wit-bindgen block with "wasi:clocks/monotonic-clock@0.2.0": ::wasi::clocks::monotonic_clock,

2. Add the host definition for wasi:clocks to your project

You can't use the jco implementation because for some reason their implementation doesn't use poll (which is not compliant to the spec). You can use this implementation I wrote based on theirs instead

// theoretically, this should be taken from a "poll" implementation
import { Pollable } from './gfx.js';

/**
 * Taken from https://github.com/bytecodealliance/jco/blob/main/packages/preview2-shim/lib/browser/clocks.js
 * but modified to use Pollable properly
 */
export const monotonicClock = {
  resolution() {
      // usually we dont get sub-millisecond accuracy in the browser
      // Note: is there a better way to determine this?
      return 1e6;
  },
  now() {
      // performance.now() is in milliseconds, but we want nanoseconds
      return BigInt(Math.floor(performance.now() * 1e6));
  },
  subscribeInstant(instant) {
      instant = BigInt(instant);
      const now = this.now();
      if (instant <= now) {
          return this.subscribeDuration(0);
      }
      return this.subscribeDuration(instant - now);
  },
  subscribeDuration(_duration) {
      _duration = BigInt(_duration);
      const pollable = new Pollable();
      setTimeout(() => {
        pollable.resolve();
      }, Number(_duration / BigInt(1e6)));
      return pollable;
  },
};

export const wallClock = {
  now() {
      let now = Date.now(); // in milliseconds
      const seconds = BigInt(Math.floor(now / 1e3));
      const nanoseconds = (now % 1e3) * 1e6;
      return { seconds, nanoseconds };
  },
  resolution() {
      return { seconds: 0n, nanoseconds: 1e6 };
  },
};

3. Add the custom wasi:clocks implementation to your jco bindings

I put mine in ../../lib/clock.js, but you can pick your own path
'--map', 'wasi:clocks/monotonic-clock=../../lib/clock.js#monotonicClock',

4. Register the pollable event in your Rust code

/// throttle the animation to a constant refresh rate
const TARGET_FPS: u64 = 30; // events per second
const NS_PER_SECOND: u64 = 1_000_000_000;
const DURATION_PER_FRAME: u64 = NS_PER_SECOND / TARGET_FPS;

// spec doesn't guarantee monotonic_clock starts at 0, so we manually adjust
let initial_time = ::wasi::clocks::monotonic_clock::now();

// TODO: change to subscribe_frame once https://github.com/WebAssembly/wasi-gfx/issues/60 is fixed
let mut frame_pollable = ::wasi::clocks::monotonic_clock::subscribe_duration(DURATION_PER_FRAME);

loop {
    let pollables = vec![
        &frame_pollable,
        // any other pollable you have
    ];
    if poll_result.contains(&0) { // new frame
        // start a timer for the next frame
        frame_pollable = ::wasi::clocks::monotonic_clock::subscribe_duration(DURATION_PER_FRAME);
    }
}

Warnings

Unlike subscribe_frame, this won't pause when the tab isn't focused

[MendyBerger]

I agree that we should add this, mostly because we're trying to match the web on this