feat(widgets): FpsWidget (#9607)

Author: ibgreen-openai

docs/api-reference/widgets/fps-widget.md

@@ -0,0 +1,28 @@
+# FpsWidget
+
+Displays the measured frames per second (FPS) as reported by the attached
+`Deck` instance.
+
+```ts
+import {FpsWidget} from '@deck.gl/widgets';
+```
+
+## Usage
+
+```ts
+new Deck({
+  widgets: [new FpsWidget({placement: 'top-right'})]
+});
+```
+
+## Properties
+
+The `FpsWidget` accepts the generic [`WidgetProps`](./overview.md#widgetprops) and
+supports one additional option:
+
+### `placement` (String)
+
+- Default: `'top-left'`
+- Position of the widget within the view. One of `top-left`, `top-right`, `bottom-left`,
+  `bottom-right`.
+

docs/table-of-contents.json

@@ -319,6 +319,7 @@
           "api-reference/widgets/fullscreen-widget",
           "api-reference/widgets/reset-view-widget",
           "api-reference/widgets/screenshot-widget",
+          "api-reference/widgets/fps-widget",
           "api-reference/widgets/loading-widget",
           "api-reference/widgets/theme-widget",
           "api-reference/widgets/info-widget"

modules/widgets/src/fps-widget.tsx

@@ -0,0 +1,67 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Widget, WidgetProps} from '@deck.gl/core';
+import type {WidgetPlacement, Deck} from '@deck.gl/core';
+
+/** Properties for the FpsWidget. */
+export type FpsWidgetProps = WidgetProps & {
+  /** Widget positioning within the view. Default 'top-left'. */
+  placement?: WidgetPlacement;
+};
+
+/**
+ * Displays the average frames per second reported by the Deck instance.
+ */
+export class FpsWidget extends Widget<FpsWidgetProps> {
+  static defaultProps: Required<FpsWidgetProps> = {
+    ...Widget.defaultProps,
+    id: 'fps',
+    placement: 'top-left'
+  };
+
+  className = 'deck-widget-fps';
+  placement: WidgetPlacement = 'top-left';
+
+  private _lastFps: number = -1;
+
+  constructor(props: FpsWidgetProps = {}) {
+    super(props, FpsWidget.defaultProps);
+    this.placement = props.placement ?? this.placement;
+  }
+
+  setProps(props: Partial<FpsWidgetProps>): void {
+    if (props.placement) {
+      this.placement = props.placement;
+    }
+    super.setProps(props);
+  }
+
+  onRenderHTML(rootElement: HTMLElement): void {
+    const fps = this._getFps();
+    rootElement.innerText = `FPS:\n${fps}`;
+    rootElement.style.backgroundColor = 'white';
+    rootElement.style.fontFamily = 'monospace';
+    rootElement.style.fontSize = '8px';
+    rootElement.style.fontWeight = '700'; // Make font bolder on click
+  }
+
+  onRedraw({}: {viewports: any[]; layers: any[]}): void {
+    const fps = this._getFps();
+    if (fps !== this._lastFps) {
+      this._lastFps = fps;
+      this.updateHTML();
+    }
+  }
+
+  onAdd({}: {deck: Deck<any>; viewId: string | null}): void {
+    this._lastFps = this._getFps();
+    this.updateHTML();
+  }
+
+  _getFps(): number {
+    // @ts-expect-error protected
+    return Math.round(this.deck.metrics.fps ?? 0);
+  }
+}

modules/widgets/src/index.ts

@@ -15,6 +15,7 @@ export {GeolocateWidget as _GeolocateWidget} from './geolocate-widget';
 export {FullscreenWidget} from './fullscreen-widget';
 export {ScreenshotWidget} from './screenshot-widget';
 export {LoadingWidget as _LoadingWidget} from './loading-widget';
+export {FpsWidget as _FpsWidget} from './fps-widget';
 export {ThemeWidget as _ThemeWidget} from './theme-widget';
 export {InfoWidget as _InfoWidget} from './info-widget';
 export {SplitterWidget as _SplitterWidget} from './splitter-widget';
@@ -28,6 +29,7 @@ export type {ScreenshotWidgetProps} from './screenshot-widget';
 export type {ResetViewWidgetProps} from './reset-view-widget';
 export type {GeolocateWidgetProps} from './geolocate-widget';
 export type {LoadingWidgetProps} from './loading-widget';
+export type {FpsWidgetProps} from './fps-widget';
 export type {ScaleWidgetProps} from './scale-widget';
 export type {ThemeWidgetProps} from './theme-widget';
 export type {InfoWidgetProps} from './info-widget';

test/apps/widgets-example-9.2/app.ts

@@ -14,7 +14,7 @@ import {
   _ScaleWidget,
   _LoadingWidget,
   _ThemeWidget,
-  _InfoWidget,
+  _FpsWidget,
   _InfoWidget,
   _SplitterWidget,
   _TimelineWidget,
@@ -98,6 +98,7 @@ const deck = new Deck({
     new FullscreenWidget(),
     new ScreenshotWidget(),
     new ResetViewWidget(),
+    new _FpsWidget(),
     new _LoadingWidget(),
     new _ScaleWidget({placement: 'bottom-right'}),
     new _GeolocateWidget({viewId: 'left-map'}),