reduce gamepad poll cost

Author: niedzielski

src/demo/index.ts

@@ -14,7 +14,7 @@ const v = new V.Void({
   description,
   loader: new Loader()
 })
-v.setPoller(((V.debug?.seconds ? 1 : 60) * 1000) as V.Millis, () =>
+v.setInterval(((V.debug?.seconds ? 1 : 60) * 1000) as V.Millis, () =>
   V.millisUntilNext(new Date(), V.debug?.seconds ? 'Sec' : 'Min')
 )
 await v.register('add')

src/demo/level/loader.ts

@@ -59,7 +59,7 @@ export class Loader implements V.Loader {
       looper: v.looper,
       pageBlocks: 10
     })
-    v.setPoller(((V.debug?.seconds ? 1 : 60) * 1000) as V.Millis, () =>
+    v.setInterval(((V.debug?.seconds ? 1 : 60) * 1000) as V.Millis, () =>
       V.millisUntilNext(new Date(), V.debug?.seconds ? 'Sec' : 'Min')
     )
 

src/input/gamepad.ts

@@ -32,21 +32,26 @@ export class Gamepad {
   }
 
   update(): void {
-    this.bits = 0
-    if (!isSecureContext) return
+    this.bits = this.#read()
+  }
+
+  #read(): number {
+    if (!isSecureContext) return 0
+    let bits = 0
     for (const pad of navigator.getGamepads()) {
       if (!pad) continue
-      for (const [index, axis] of pad.axes.entries() ?? []) {
-        const lessMore = this.bitByAxis[index]
+      for (const [i, axis] of pad.axes.entries()) {
+        const lessMore = this.bitByAxis[i]
         if (!lessMore) continue
         const bit = axis < 0 ? lessMore[0] : axis === 0 ? 0 : lessMore[1]
-        this.bits |= Math.abs(axis) >= 0.5 ? bit : 0
+        bits |= Math.abs(axis) >= 0.5 ? bit : 0
       }
-      for (const [index, btn] of pad.buttons.entries() ?? []) {
-        const bit = this.bitByButton[index]
+      for (const [i, btn] of pad.buttons.entries()) {
+        const bit = this.bitByButton[i]
         if (bit == null) continue
-        this.bits |= btn.pressed ? bit : 0
+        bits |= btn.pressed ? bit : 0
       }
     }
+    return bits
   }
 }

src/looper.test.ts

@@ -1,5 +1,5 @@
 import {afterEach, beforeEach, test} from 'node:test'
-import {Looper} from './looper.ts'
+import {Looper, type LoopReason} from './looper.ts'
 import {assert} from './test/assert.ts'
 import {TestEvent} from './test/test-event.ts'
 import type {Millis} from './types/time.ts'
@@ -27,7 +27,9 @@ afterEach(() => {
 test('Looper', async ctx => {
   using framer = new Looper()
   let frame = 0
-  framer.onFrame = () => ++frame
+  framer.onFrame = (_millis, _reason) => {
+    ++frame
+  }
 
   await ctx.test('init', () => assert(frame, 0))
 
@@ -39,27 +41,27 @@ test('Looper', async ctx => {
 
   await ctx.test('onFrame()', () => {
     performance.now = () => 8 as Millis
-    framer.requestFrame()
+    framer.requestFrame('Render')
     performance.now = () => 24 as Millis // millis = 24 - 8 = 16
     onFrame!()
     assert(frame, 1)
     assert(framer.age, 16 as Millis)
     performance.now = () => 40 as Millis
-    framer.requestFrame()
+    framer.requestFrame('Render')
     performance.now = () => 56 as Millis // millis = 56 - 40 = 16
     onFrame!()
     assert(frame, 2)
     assert(framer.age, 32 as Millis)
     performance.now = () => 72 as Millis
-    framer.requestFrame()
+    framer.requestFrame('Render')
     performance.now = () => 88 as Millis // millis = 88 - 72 = 16
     onFrame!()
     assert(frame, 3)
     assert(framer.age, 48 as Millis)
   })
 
   await ctx.test('hidden', () => {
-    framer.requestFrame()
+    framer.requestFrame('Render')
     doc.hidden = true
     doc.dispatchEvent(TestEvent('visibilitychange'))
     assert(onFrame, undefined)
@@ -75,3 +77,82 @@ test('Looper', async ctx => {
     assert(framer.age, 64 as Millis) // 48 + 16
   })
 })
+
+test('poll reason', async ctx => {
+  using framer = new Looper()
+  let frame = 0
+  let lastReason: LoopReason | undefined
+  let skip: 'Skip' | undefined
+  framer.onFrame = (_millis, reason) => {
+    ++frame
+    lastReason = reason
+    return skip
+  }
+  framer.register('add')
+
+  await ctx.test('requestFrame(Render) passes Render reason', () => {
+    performance.now = () => 0 as Millis
+    framer.requestFrame('Render')
+    performance.now = () => 16 as Millis
+    onFrame!()
+    assert(frame, 1)
+    assert(lastReason, 'Render')
+  })
+
+  await ctx.test('requestFrame(Poll) passes Poll reason', () => {
+    performance.now = () => 16 as Millis
+    framer.requestFrame('Poll')
+    performance.now = () => 32 as Millis
+    onFrame!()
+    assert(frame, 2)
+    assert(lastReason, 'Poll')
+  })
+
+  await ctx.test('upgrade poll to render', () => {
+    performance.now = () => 32 as Millis
+    framer.requestFrame('Poll')
+    // non-poll call upgrades pending poll.
+    framer.requestFrame('Render')
+    performance.now = () => 48 as Millis
+    onFrame!()
+    assert(frame, 3)
+    assert(lastReason, 'Render')
+  })
+
+  await ctx.test('poll does not upgrade to poll', () => {
+    performance.now = () => 48 as Millis
+    framer.requestFrame('Poll')
+    // another poll call doesn't schedule a second rAF.
+    framer.requestFrame('Poll')
+    performance.now = () => 64 as Millis
+    onFrame!()
+    assert(frame, 4)
+    assert(lastReason, 'Poll')
+  })
+
+  await ctx.test('cancel clears reason', () => {
+    performance.now = () => 64 as Millis
+    framer.requestFrame('Poll')
+    framer.register('remove')
+    assert(onFrame, undefined)
+    // re-register and request normal frame.
+    framer.register('add')
+    performance.now = () => 80 as Millis
+    framer.requestFrame('Render')
+    performance.now = () => 96 as Millis
+    onFrame!()
+    assert(frame, 5)
+    assert(lastReason, 'Render')
+  })
+
+  await ctx.test('skip does not accumulate age', () => {
+    performance.now = () => 96 as Millis
+    framer.requestFrame('Poll')
+    const ageBefore = framer.age
+    skip = 'Skip'
+    performance.now = () => 112 as Millis
+    onFrame!()
+    skip = undefined
+    assert(framer.age, ageBefore)
+  })
+})

src/looper.ts

@@ -1,17 +1,15 @@
 import type {Millis} from './types/time.ts'
 import {debug} from './utils/debug.ts'
 
-/**
- * frame manager. passes frame requests when not hidden. callers should request
- * frames when an update occurs or a check for an update occurs. eg, gamepads
- * must be polled.
- *
- * when registered, restoring visibility triggers an automatic request.
- */
+export type LoopReason = 'Poll' | 'Render'
+
 export class Looper {
   /** duration of frames observed. */
   age: Millis = 0
-  onFrame: ((millis: Millis) => void) | undefined
+  onFrame:
+    | ((millis: Millis, reason: LoopReason) => 'Skip' | undefined)
+    | undefined
+  #reason: LoopReason = 'Render'
   #req: number = 0
   #registered: boolean = false
   #start: Millis = 0
@@ -25,7 +23,8 @@ export class Looper {
     return this
   }
 
-  requestFrame(): void {
+  requestFrame(reason: LoopReason): void {
+    this.#reason = this.#reason === 'Render' ? this.#reason : reason
     if (this.#req || document.hidden || !this.#registered) return
     this.#start = performance.now()
     this.#req = requestAnimationFrame(this.#onFrame)
@@ -41,10 +40,14 @@ export class Looper {
   }
 
   #onFrame = (): void => {
-    const millis = (performance.now() - this.#start) as Millis
-    this.age = (this.age + millis) as Millis
+    const now = performance.now()
+    const millis = (now - this.#start) as Millis
     this.#req = 0
-    this.onFrame?.(millis)
+    this.age += millis
+    const reason = this.#reason
+    this.#reason = 'Poll'
+    if (this.onFrame && this.onFrame(millis, reason) === 'Skip')
+      this.age -= millis
   }
 
   #onVisibility = (ev: Event): void => {
@@ -53,7 +56,7 @@ export class Looper {
       this.#cancel()
       if (debug?.looper) console.debug('[looper] paused')
     } else {
-      this.requestFrame()
+      this.requestFrame('Poll')
       if (debug?.looper) console.debug('[looper] resumed')
     }
   }

src/void.ts

@@ -11,7 +11,7 @@ import type {CamConfig} from './level/level.ts'
 import {type ComponentHook, parseLevel} from './level/level-parser.ts'
 import type {LevelSchema} from './level/level-schema.ts'
 import type {Loader} from './level/loader.ts'
-import {Looper} from './looper.ts'
+import {Looper, type LoopReason} from './looper.ts'
 import type {PoolOpts} from './mem/pool.ts'
 import type {PoolMap} from './mem/pool-map.ts'
 import {SpritePool} from './mem/sprite-pool.ts'
@@ -55,7 +55,7 @@ export class Void {
   #backgroundRGBA: number
   #invalid: boolean = false
   readonly #pixelRatioObserver: PixelRatioObserver = new PixelRatioObserver()
-  #poller: DelayInterval | undefined
+  #interval: DelayInterval | undefined
   #registered: boolean = false
   /** may trigger an initial force update. */
   readonly #resizeObserver = new ResizeObserver(() => this.onResize())
@@ -103,7 +103,7 @@ export class Void {
       })
     }
 
-    this.looper.onFrame = millis => this.onFrame(millis)
+    this.looper.onFrame = (millis, reason) => this.onFrame(millis, reason)
 
     this.loader = opts.loader
 
@@ -124,9 +124,9 @@ export class Void {
     this.#backgroundRGBA = rgba
   }
 
-  clearPoller(): void {
-    this.#poller?.register('remove')
-    this.#poller = undefined
+  clearInterval(): void {
+    this.#interval?.register('remove')
+    this.#interval = undefined
   }
 
   configCam(config: Readonly<CamConfig>): void {
@@ -172,21 +172,24 @@ export class Void {
   }
 
   /** update input, update canvas, update cam, update world, then render. */
-  onFrame(millis: Millis): void {
+  onFrame(millis: Millis, reason: LoopReason): 'Skip' | undefined {
     this.tick.ms = millis
     this.tick.s = (millis / 1000) as Secs
     if (document.hidden) return
     this.input.update(millis)
 
-    this.requestFrame() // request frame before in case update cancels.
+    // request frame before in case update cancels. next reason is 'Render' when
+    // input.
+    const nextReason = this.requestFrame()
+    if (reason === 'Poll' && nextReason !== 'Render') return 'Skip'
 
     this.#invalid = false
     this.loader.update(this)
 
     this.cam.postupdate()
   }
 
-  onPoll(): void {
+  onInterval(): void {
     this.requestFrame('Force')
   }
 
@@ -202,8 +205,8 @@ export class Void {
     else this.#resizeObserver.unobserve(this.canvas.parentElement!)
     this.#pixelRatioObserver.register(op)
 
-    if (op === 'add') this.looper.requestFrame()
-    this.#poller?.register(op)
+    if (op === 'add') this.requestFrame('Force')
+    this.#interval?.register(op)
 
     await loadImage(this.#atlasImage)
     this.renderer.loadAtlas(this.#atlasImage)
@@ -214,17 +217,22 @@ export class Void {
     this.#registered = op === 'add'
   }
 
-  requestFrame(force?: 'Force'): void {
-    if (force || this.renderer.always || this.input.anyOn || this.input.gamepad)
-      this.looper.requestFrame()
+  requestFrame(force?: 'Force'): LoopReason | undefined {
+    let reason: LoopReason | undefined
+    if (force || this.input.invalid || this.input.anyOn || this.renderer.always)
+      reason = 'Render'
+    else if (this.input.gamepad) reason = 'Poll'
+
+    if (reason) this.looper.requestFrame(reason)
+    return reason
   }
 
-  setPoller(period: Millis, delay?: () => Millis): void {
-    this.#poller?.register('remove')
-    this.#poller = new DelayInterval(delay ?? (() => 0), period, () =>
-      this.onPoll()
+  setInterval(period: Millis, delay?: () => Millis): void {
+    this.#interval?.register('remove')
+    this.#interval = new DelayInterval(delay ?? (() => 0), period, () =>
+      this.onInterval()
     )
-    if (this.#registered) this.#poller.register('add')
+    if (this.#registered) this.#interval.register('add')
   }
 
   async [Symbol.asyncDispose](): Promise<void> {