@asdf-overlay/core 1.2.5 → 2.0.0

package/index.d.ts

@@ -0,0 +1,6 @@
+export * from './native';
+
+/** 
+ * Utility function to get the default DLL directory path.
+ */
+declare export function defaultDllDir(): string;

package/index.js

@@ -0,0 +1,11 @@
+const { EventEmitter } = require('node:events');
+
+// @ts-check
+module.exports = require('./native');
+
+function defaultDllDir() {
+  return __dirname;
+}
+module.exports.defaultDllDir = defaultDllDir;
+
+module.exports.Overlay.EventEmitter = EventEmitter;

package/native.d.ts

@@ -0,0 +1,305 @@
+import { EventEmitter } from 'node:events';
+
+export declare type OverlayEventEmitter = EventEmitter<{
+  /**
+  * A window has been added.
+  */
+  window_added: [id: number, width: number, height: number],
+
+  /**
+   * A window has been resized.
+   */
+  window_resized: [id: number, width: number, height: number],
+
+  /**
+   * Cursor input from a window.
+   */
+  window_cursor_input: [id: number, input: CursorInput],
+
+  /**
+   * Keyboard input from a window.
+   */
+  window_keyboard_input: [id: number, input: KeyboardInput],
+
+  /**
+   * Window is destroyed.
+   */
+  window_destroyed: [id: number],
+
+  /**
+   * A surface has been added.
+   */
+  surface_added: [id: bigint, width: number, height: number, info: SurfaceInfo],
+
+  /**
+   * A surface has been resized.
+   */
+  surface_resized: [id: bigint, width: number, height: number],
+
+  /**
+   * A surface has been destroyed.
+   */
+  surface_destroyed: [id: bigint],
+
+  /**
+   * Input blocking is interrupted and turned off.
+   */
+  input_blocking_ended: [id: number],
+  
+  /**
+   * Tracing span has been entered.
+   */
+  tracing_enter: [metadata: TracingMetadata],
+
+  /**
+   * A tracing event has been emitted.
+   */
+  tracing_event: [metadata: TracingMetadata, message?: string],
+
+  /**
+   * Tracing span has been exited.
+   */
+  tracing_exit: [],
+
+  /**
+   * An error has occured on ipc connection.
+   */
+  error: [err: unknown],
+
+  /**
+   * Ipc disconnected.
+   */
+  disconnected: [],
+}>;
+export declare class Overlay {
+  /** Attach overlay to target process */
+  static attach(this: this, dllDir: string, pid: number, timeout?: number | undefined | null): Promise<Overlay>
+  get event(): OverlayEventEmitter
+  /** Update overlay surface. */
+  updateHandle(id: bigint, update: UpdateSharedHandle): Promise<void>
+  /** Update overlay position relative to window */
+  setPosition(id: bigint, x: number, y: number): Promise<void>
+  /** Set blocking cursor. */
+  setBlockingCursor(cursor?: Cursor | undefined | null): Promise<void>
+  /** Listen to window input without blocking */
+  listenInput(id: number, cursor: boolean, keyboard: boolean): Promise<void>
+  /** Block window input and listen them. */
+  blockInput(block: boolean): Promise<void>
+  /** Detach and destroy overlay */
+  detach(): void
+}
+
+/** Represent a surface for overlay */
+export declare class OverlaySurface {
+  /** Create a new overlay surface. */
+  constructor(luid?: GpuLuid | undefined | null)
+  /** Clear the surface. */
+  clear(): void
+  /** Update surface using D3D11 NT shared texture. */
+  updateNtShtex(width: number, height: number, handle: Buffer, rect?: CopyRect | undefined | null): UpdateSharedHandle | null
+  /** Update surface using D3D11 KMT shared texture. */
+  updateKmtShtex(width: number, height: number, handle: Buffer, rect?: CopyRect | undefined | null): UpdateSharedHandle | null
+  /** Update surface using bitmap buffer. The size of overlay is `width x (data.byteLength / 4 / width)` */
+  updateBitmap(width: number, data: Buffer): UpdateSharedHandle | null
+}
+
+export interface CopyRect {
+  dstX: number
+  dstY: number
+  src: Rect
+}
+
+export declare enum Cursor {
+  Default = 0,
+  Help = 1,
+  Pointer = 2,
+  Progress = 3,
+  Wait = 4,
+  Cell = 5,
+  Crosshair = 6,
+  Text = 7,
+  VerticalText = 8,
+  Alias = 9,
+  Copy = 10,
+  Move = 11,
+  NotAllowed = 12,
+  Grab = 13,
+  Grabbing = 14,
+  ColResize = 15,
+  RowResize = 16,
+  EastWestResize = 17,
+  NorthSouthResize = 18,
+  NorthEastSouthWestResize = 19,
+  NorthWestSouthEastResize = 20,
+  ZoomIn = 21,
+  ZoomOut = 22,
+  UpArrow = 23,
+  Pin = 24,
+  Person = 25,
+  Pen = 26,
+  Cd = 27,
+  PanMiddle = 28,
+  PanMiddleHorizontal = 29,
+  PanMiddleVertical = 30,
+  PanEast = 31,
+  PanNorth = 32,
+  PanNorthEast = 33,
+  PanNorthWest = 34,
+  PanSouth = 35,
+  PanSouthEast = 36,
+  PanSouthWest = 37,
+  PanWest = 38
+}
+
+/** Cursor buttons. */
+export type CursorAction =  'Left'|
+'Right'|
+'Middle'|
+'Back'|
+'Forward';
+
+/** Describe a cursor input. */
+export interface CursorInput {
+  /** X position relative to window. */
+  x: number
+  /** Y position relative to window. */
+  y: number
+  kind: CursorInputKind
+}
+
+export type CursorInputKind =
+  | { type: 'Enter' }
+  | { type: 'Leave' }
+  | { type: 'Move' }
+  | { type: 'Action', action: CursorAction, state: CursorInputState }
+  | { type: 'Scroll', axis: ScrollAxis, delta: number }
+
+/** Cursor input state. */
+export type CursorInputState =
+  | { type: 'Pressed', /** Consecutive click count. */
+clickCount: number }
+| { type: 'Released' }
+
+export interface GpuLuid {
+  low: number
+  high: number
+}
+
+/** Describe a IME event. */
+export type Ime =
+  | { type: 'Enabled', /** Initial IME language in ETF language tag(BCP 47) format. */
+  lang: string, /** Initial IME conversion mode */
+conversion: number }
+| { type: 'Changed', /** Changed IME language in ETF language tag(BCP 47) format. */
+lang: string }
+| { type: 'ConversionChanged', /** Changed IME conversion mode. */
+conversion: number }
+| { type: 'CandidateChanged', list: ImeCandidateList }
+| { type: 'CandidateClosed' }
+| { type: 'Compose', /** Composing text. */
+text: string, /** Current caret index in composing text. */
+caret: number }
+| { type: 'Commit', /** Committed text. */
+text: string }
+| { type: 'Disabled' }
+
+/** IME candidate list. */
+export interface ImeCandidateList {
+  /** Start index of current page. */
+  pageStartIndex: number
+  /** Count of candidate item per page. */
+  pageSize: number
+  /** Currently selected candidate index. */
+  selectedIndex: number
+  /** Candidate list. */
+  candidates: Array<string>
+}
+
+export declare enum ImeConversion {
+  None = 0,
+  /** IME converts to native langauge. */
+  Native = 1,
+  /** IME composes in full-width characters. */
+  Fullshape = 2,
+  /** Conversion is disabled. */
+  NoConversion = 4,
+  /** Converting to hanja. */
+  HanjaConvert = 8,
+  /** Converting to katakana. */
+  Katakana = 16
+}
+
+/** Utility function to create `Key` using key code and optional extended flag. */
+export declare function key(code: number, extended?: boolean | undefined | null): Key
+
+/** Describe a virtual key code. */
+export interface Key {
+  /** A Windows Virtual-Key code. */
+  code: number
+  /**
+   * Whether if this key is an extended key.
+   *
+   * This is usually true for right-side modifier keys, numpad keys, and arrow keys.
+   */
+  extended: boolean
+}
+
+export type KeyboardInput =
+  | { type: 'Key', key: Key, state: KeyInputState }
+  | { type: 'Char', /** Input character (1 character). */
+ch: string }
+| { type: 'Ime', /** An IME event. */
+ime: Ime }
+
+/** Key input state. */
+export type KeyInputState = /** The key is pressed down. */
+'Pressed'|
+/** The key is released. */
+'Released';
+
+export type LogLevel =  'Trace'|
+'Debug'|
+'Info'|
+'Warn'|
+'Error';
+
+export interface Rect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/** Cursor scroll axis. */
+export type ScrollAxis =  'X'|
+'Y';
+
+export interface SurfaceInfo {
+  /** Surface type. */
+  ty: SurfaceType
+  /** GPU LUID of the surface. */
+  gpuId: GpuLuid
+}
+
+export type SurfaceType =
+  | { type: 'Opengl', windowId: number }
+  | { type: 'Direct3D9', windowId: number }
+  | { type: 'Direct3D11', windowId?: number }
+  | { type: 'Direct3D12', windowId?: number }
+  | { type: 'Vulkan', windowId: number }
+
+export interface TracingMetadata {
+  /** Metadata tracing level. */
+  level: LogLevel
+  /** The time in milliseconds when the tracing event occurred. */
+  time: number
+  /** The module path of the tracing event, if available. */
+  modulePath?: string
+  /** The line number of the tracing event, if available. */
+  line?: number
+}
+
+export type UpdateSharedHandle =
+  | { type: 'Kmt', field0: number }
+  | { type: 'Nt', field0: number }
+  | { type: 'None' }