@overwolf/ow-electron-packages-types 1.1.10 → 1.1.11-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@overwolf/ow-electron-packages-types",
-    "version": "1.1.10",
+    "version": "1.1.11-beta.0",
     "description": "Type definition file for autocompletion and documentation purposes for ow-electron packages",
     "license": "MIT",
     "types": "types.d.ts",

package/types.d.ts

@@ -697,6 +697,17 @@ interface EncoderInfoBase {
    * A human-readable name for the encoder (e.g., shown in UI).
    */
   readonly name: string;
+
+  /**
+   * Optional map of encoder-specific configuration properties, keyed by
+   * setting name (e.g. `bitrate`, `rate_control`). Each property describes a
+   * setting that can be adjusted for this encoder.
+   *
+   * Reported for both video and audio encoders.
+   *
+   * @see {@link EncoderProperty}
+   */
+  readonly properties?: Record<string, EncoderProperty>;
 }
 
 /**
@@ -706,14 +717,22 @@ interface EncoderInfoBase {
  * Provides metadata to help display options in a UI or validate configuration.
  *
  * @example
- * const bitrateProperty: EncoderProperty = {
- *   default: 4500,
- *   description: 'Target video bitrate in kbps.',
- *   values: {
- *     3000: 'Low quality',
- *     4500: 'Medium quality (default)',
- *     6000: 'High quality'
- *   }
+ * // An enum-like setting - `values` lists every accepted value.
+ * const rateControl: EncoderProperty = {
+ *   default: 'CBR',
+ *   description: 'Rate Control',
+ *   values: ['CBR', 'CQP', 'VBR', 'CQVBR'],
+ *   valuesDesc: ['CBR', 'CQP', 'VBR', 'CQVBR']
+ * };
+ *
+ * @example
+ * // A numeric range setting - no `values`; the range is min/max/step.
+ * const bitrate: EncoderProperty = {
+ *   default: 10000,
+ *   description: 'Bitrate',
+ *   min: 50,
+ *   max: 4294967,
+ *   step: 50
  * };
  */
 interface EncoderProperty {
@@ -728,8 +747,14 @@ interface EncoderProperty {
   readonly description: string;
 
   /**
-   * Optional array of possible values for this property.
+   * The complete set of accepted values for this property, present only for
+   * enum-like settings (e.g. `rate_control`, `preset`, `profile`, `tune`).
    * Useful for dropdowns or presets.
+   *
+   * Numeric range settings such as `bitrate`, `max_bitrate` or `keyint_sec`
+   * do **not** report `values` - they describe their range through `min`,
+   * `max` and `step` instead. An absent or single-entry `values` array
+   * therefore does not mean the setting is restricted to one option.
    */
   readonly values?: (string | number)[];
 
@@ -738,6 +763,29 @@ interface EncoderProperty {
    * Helps provide additional context for each option.
    */
   readonly valuesDesc?: string[];
+
+  /**
+   * The smallest value this setting accepts.
+   *
+   * Reported for numeric settings only (`bitrate`, `keyint_sec`, `cqp`, ...);
+   * enum-like settings use `values` instead.
+   */
+  readonly min?: number;
+
+  /**
+   * The largest value this setting accepts.
+   *
+   * Reported for numeric settings only.
+   */
+  readonly max?: number;
+
+  /**
+   * The granularity between accepted values.
+   *
+   * Reported for numeric settings only. A `bitrate` with a `step` of 50
+   * accepts 50, 100, 150 and so on.
+   */
+  readonly step?: number;
 }
 
 /**
@@ -752,7 +800,10 @@ interface EncoderProperty {
  * const audioEncoder: AudioEncoderInfo = {
  *   codec: 'aac',
  *   name: 'FFmpeg AAC Encoder',
- *   type: 'ffmpeg_aac'
+ *   type: 'ffmpeg_aac',
+ *   properties: {
+ *     bitrate: { default: 128, description: 'Bitrate' }
+ *   }
  * };
  */
 interface AudioEncoderInfo extends EncoderInfoBase {
@@ -769,8 +820,9 @@ interface AudioEncoderInfo extends EncoderInfoBase {
 /**
  * Information for a supported video encoder.
  *
- * This interface extends `EncoderInfoBase` and adds specific information
- * about the video encoder type and any configurable encoder properties.
+ * This interface extends `EncoderInfoBase` and adds the specific video encoder
+ * type identifier. Configurable encoder settings are reported through the
+ * inherited `properties` map.
  *
  * @extends EncoderInfoBase
  *
@@ -780,14 +832,11 @@ interface AudioEncoderInfo extends EncoderInfoBase {
  *   name: 'NVIDIA NVENC H.264',
  *   type: 'obs_nvenc_h264_tex',
  *   properties: {
- *     bitrate: {
- *       default: 6000,
- *       description: 'Target video bitrate in kbps.',
- *       values: {
- *         4000: 'Low quality',
- *         6000: 'Medium quality',
- *         8000: 'High quality'
- *       }
+ *     bitrate: { default: 10000, description: 'Bitrate' },
+ *     rate_control: {
+ *       default: 'CBR',
+ *       description: 'Rate Control',
+ *       values: ['CBR', 'CQP', 'VBR', 'CQVBR']
  *     }
  *   }
  * };
@@ -795,19 +844,10 @@ interface AudioEncoderInfo extends EncoderInfoBase {
 interface VideoEncoderInfo extends EncoderInfoBase {
   /**
    * The identifier for the specific video encoder type.
-   * 
+   *
    * @see {@link kSupportedEncodersTypes}
    */
   readonly type: kSupportedEncodersTypes;
-
-  /**
-   * Optional map of encoder-specific configuration properties.
-   * Each property defines a setting that can be adjusted,
-   * such as bitrate, profile, or keyframe interval.
-   * 
-   * @see {@link EncoderProperty}
-   */
-  readonly properties?: Record<string, EncoderProperty>;
 }
 
 
@@ -911,7 +951,7 @@ interface AudioInformation {
  *   adapterIndex: 0,
  *   id: 'MONITOR\\GSM5B10\\{4d36e96e-e325-11ce-bfc1-08002be10318}_0',
  *   altId: 'DISPLAY1',
- *   dpi: 96,
+ *   dpi: 1.25,
  *   attachedToDesktop: true,
  *   friendlyName: 'LG UltraFine 4K',
  *   refreshRate: 60,
@@ -937,7 +977,8 @@ interface MonitorInfo {
   readonly altId: string;
 
   /**
-   * The DPI (dots per inch) value of the monitor.
+   * Display scale factor (system DPI / 96), not a DPI value.
+   * `1` = 100%, `1.25` = 125%, `2` = 200%.
    */
   readonly dpi: number;
 
@@ -1477,7 +1518,13 @@ type kAMDEncoderProfile264 =
  * | `'CBR'`      | Constant Bitrate. Maintains a consistent bitrate throughout the recording. Useful for streaming and bandwidth-limited scenarios.           |
  * | `'CQP'`      | Constant Quantization Parameter. Prioritizes visual quality by keeping a consistent quantization level. File sizes may vary significantly. |
  * | `'VBR'`      | Variable Bitrate. Adjusts bitrate dynamically based on scene complexity. Provides better compression but less predictability in file size. |
- * | `'Lossless'` | Encodes without compression loss. Produces very high-quality output at the cost of large file sizes.                                       |
+ * | `'CQVBR'`    | Constrained Quality VBR. Targets a quality level (`target_quality`) while respecting `max_bitrate`.                                        |
+ * | `'lossless'` | Encodes without compression loss. Produces very high-quality output at the cost of large file sizes.                                       |
+ *
+ * These values are **case-sensitive**: NVENC compares `CQP` and `lossless`
+ * exactly as spelled here. Any value it does not recognize falls back to `CBR`
+ * silently, with no error - so pass these strings verbatim and do not
+ * upper- or lower-case them.
  *
  * @example
  * const rateControl: kNVENCEncoderRateControl = 'CQP';
@@ -1502,10 +1549,18 @@ type kNVENCEncoderRateControl =
   | 'VBR'
 
   /**
-   * `Lossless` — Encodes without compression loss.
+   * `CQVBR` — Constrained Quality VBR. Targets the quality level given by
+   * `target_quality` while keeping within `max_bitrate`.
+   */
+  | 'CQVBR'
+
+  /**
+   * `lossless` — Encodes without compression loss.
    * Produces very high-quality output at the cost of large file sizes.
+   *
+   * Lower-case by design: NVENC matches this value case-sensitively.
    */
-  | 'Lossless';
+  | 'lossless';
 
 /**
  * Specifies the multipass encoding mode for NVIDIA's NVENC encoder.
@@ -5412,6 +5467,11 @@ interface OverlayWindowOptions
    * ignored when either condition is not met, falling back to the
    * shared-memory (CPU copy) path.
    *
+   * There is no need to wait for {@link GameWindowInfo.isSharedTextureAvailable} before
+   * creating the window. While the game's support is still unknown the window starts on the
+   * shared-texture path, and switches to the CPU copy path if the game turns out not to
+   * support it.
+   *
    * The rendering path follows the active game: when the overlay moves to a
    * different game, a shared-texture window automatically falls back to the
    * shared-memory (CPU copy) path on a game that does not support shared
@@ -5719,6 +5779,11 @@ interface InjectionError {
  * - Screen display information.
  * - Bounding rectangle of the game window.
  *
+ * Not available at injection time: the injected client reports the window only once the
+ * game's graphics device initializes, a few seconds after `game-injected`. Until then
+ * {@link ActiveGameInfo.gameWindowInfo} is `undefined`. The first `game-window-changed`
+ * event delivers it and is the earliest point where every field below holds a real value.
+ *
  * @example
  * ```ts
  * overlay.on('game-window-changed', (windowInfo, gameInfo, reason) => {
@@ -5787,7 +5852,8 @@ interface GameWindowInfo {
    * This is a capability probe only &mdash; to decide whether the path can actually be used
    * on this machine, gate on {@link GameWindowInfo.isSharedTextureAvailable} instead.
    *
-   * `undefined` until the game is injected and its graphics API is detected.
+   * `undefined` until the game's graphics device initializes, a few seconds after
+   * `game-injected`; the first `game-window-changed` event carries the resolved value.
    *
    * @since 2.0.0
    */
@@ -5795,7 +5861,11 @@ interface GameWindowInfo {
 
   /**
    * Indicates whether shared-texture (GPU) overlay rendering can actually be used with this
-   * game &mdash; gate `useSharedTexture` window creation on it.
+   * game.
+   *
+   * Not a precondition for creating a window: a `useSharedTexture` window may be created
+   * before this value resolves, and the overlay corrects the rendering path on its own. Read
+   * it to observe the outcome, or to branch when the window behaves differently on each path.
    *
    * `true` when the game's graphics API supports it
    * ({@link GameWindowInfo.isSharedTextureSupported}), no GPU adapter mismatch was detected,
@@ -5804,7 +5874,8 @@ interface GameWindowInfo {
    * `false` mid-game: the copy-failure verdict is reached only after frames were sent and
    * repeatedly failed to draw.
    *
-   * `undefined` until the game is injected and its graphics API is detected.
+   * `undefined` until the game's graphics device initializes, a few seconds after
+   * `game-injected`; the first `game-window-changed` event carries the resolved value.
    *
    * @see {@link https://dev.overwolf.com/ow-electron/reference/examples/overlay | Overlay examples}
    *
@@ -5862,6 +5933,10 @@ interface ActiveGameInfo {
   readonly gameInfo: GameInfo;
   /**
    * Window-specific details for the running game.
+   *
+   * `undefined` between injection and the first `game-window-changed` event: the injected
+   * client reports the window only once the game's graphics device initializes.
+   *
    * @see {@link GameWindowInfo}.
    */
   readonly gameWindowInfo: GameWindowInfo;
@@ -6395,6 +6470,11 @@ interface IOverwolfOverlayApi extends EventEmitter {
   /**
    * Fires when the game window focus state changes.
    *
+   * Also fires for a game whose injection was dismissed
+   * ({@link GameLaunchEvent.dismiss}). That window info carries position, size and focus
+   * only, with no graphics or shared-texture fields, so it is not a substitute for the first
+   * `game-window-changed`.
+   *
    * @param eventName - `game-focus-changed`
    * @param listener - Callback with window info, game info, and focus state.
    * @see {@link GameWindowInfo}.
@@ -6410,7 +6490,9 @@ interface IOverwolfOverlayApi extends EventEmitter {
   ): this;
 
   /**
-   * Fires when the game window is resized or changes position.
+   * Fires when the game window is resized or changes position, and once when the injected
+   * client first reports the window. That first event is the earliest point where
+   * {@link GameWindowInfo} is available.
    *
    * @param eventName - `game-window-changed`
    * @param listener - Callback with window info, game info, and optional reason.
@@ -6427,6 +6509,22 @@ interface IOverwolfOverlayApi extends EventEmitter {
     ) => void,
   ): this;
 
+  /**
+   * Fires when the injected game's window is destroyed, which on many games
+   * happens seconds before the process exits. `game-exit` still follows and
+   * remains the authoritative end-of-session event.
+   *
+   * Not emitted for OOPO games.
+   *
+   * @param eventName - `game-window-destroyed`
+   * @param listener - Callback with the game info of the destroyed window.
+   * @see {@link GameInfo}.
+   */
+  on(
+    eventName: 'game-window-destroyed',
+    listener: (gameInfo: GameInfo) => void,
+  ): this;
+
   /**
    * Fires when the game input interception capability changes.
    *