@illgrenoble/webx-client 1.12.0 → 1.13.0

package/README.md

@@ -24,8 +24,6 @@ WebX is a Remote Desktop technology allowing an X11 desktop to be rendered in a
 
 WebX's principal differentiation to other Remote Desktop technologies is that it manages individual windows within the display rather than treating the desktop as a single image. A couple of advantages with a window-based protocol is that window movement events are efficiently passed to clients (rather than graphically updating regions of the desktop) and similarly it avoids <em>tearing</em> render effects during the movement. WebX aims to optimise the flow of data from the window region capture, the transfer of data and client rendering.
 
-> The full source code is openly available and the technology stack can be (relatively) easily demoed but it should be currently considered a work in progress.
-
 The WebX remote desktop stack is composed of a number of different projects:
 - [WebX Engine](https://github.com/ILLGrenoble/webx-engine) The WebX Engine is the core of WebX providing a server that connects to an X11 display obtaining window parameters and images. It listens to X11 events and forwards event data to connected clients. Remote clients similarly interact with the desktop and the actions they send to the WebX Engine are forwarded to X11.
 - [WebX Router](https://github.com/ILLGrenoble/webx-router) The WebX Router manages multiple WebX sessions on single host, routing traffic between running WebX Engines and the WebX Relay. It authenticates session creation requests and spawns Xorg, window manager and WebX Engine processes.

package/dist/WebXClient.d.ts

@@ -2,7 +2,7 @@ import { WebXTunnel } from './tunnel';
 import { WebXDisplay } from './display';
 import { WebXKeyboard, WebXMouse, WebXMouseState } from './input';
 import { WebXDebugImageMessageHandler, WebXHandler } from './tracer';
-import { Blob } from "buffer";
+import { WebXOptions } from "./WebXOptions";
 /**
  * Configuration options for the WebXClient.
  */
@@ -20,6 +20,7 @@ export interface WebXClientConfig {
  */
 export declare class WebXClient {
     private _tunnel;
+    private _options?;
     private readonly _windowImageFactory;
     private readonly _cursorFactory;
     private _tracers;
@@ -63,8 +64,9 @@ export declare class WebXClient {
      * Creates a new instance of the WebXClient.
      *
      * @param _tunnel The WebXTunnel instance used for communication with the WebX Engine.
+     * @param _options The WebXOptions to set, for example, display properties
      */
-    constructor(_tunnel: WebXTunnel);
+    constructor(_tunnel: WebXTunnel, _options?: WebXOptions);
     /**
      * Connects to the WebX Engine and initializes the communication tunnel.
      *

package/dist/WebXEngine.d.ts

@@ -1,4 +1,8 @@
 import { WebXVersion } from "./utils";
+/**
+ * Stores information about the version of the WebX Engine.
+ * This information is received when connecting to the server.
+ */
 export declare class WebXEngine {
     static version: WebXVersion;
 }

package/dist/WebXOptions.d.ts

@@ -0,0 +1,7 @@
+import { WebXDisplayOptions } from "./display";
+/**
+ * Stores configuration options for the WebX client
+ */
+export type WebXOptions = {
+    display?: WebXDisplayOptions;
+};

package/dist/display/WebXDisplay.d.ts

@@ -4,9 +4,9 @@ import { WebXWindow } from './WebXWindow';
 import { WebXSubImage, WebXWindowProperties } from '../common';
 import { WebXCursorFactory } from './WebXCursorFactory';
 import { WebXCanvasRenderer } from '../renderer';
-import { Blob } from "buffer";
 import { WebXWindowImageFactory } from "./WebXWindowImageFactory";
 import { WebXTexture } from "../texture";
+import { WebXDisplayOptions } from "./WebXDisplayOptions";
 /**
  * Manages the rendering of the WebX remote desktop using WebGL.
  *
@@ -18,9 +18,12 @@ export declare class WebXDisplay {
     private readonly _scene;
     private readonly _camera;
     private readonly _renderer;
+    private readonly _filter;
     private readonly _screen;
+    private readonly _isWebGL;
     private readonly _screenWidth;
     private readonly _screenHeight;
+    private readonly _options;
     private readonly _windowImageFactory;
     private readonly _containerElement;
     private _windows;
@@ -92,8 +95,9 @@ export declare class WebXDisplay {
      * @param screenHeight The height of the screen.
      * @param windowImageFactory The factory used for obtaining window images.
      * @param cursorFactory The cursor factory used for managing cursors.
+     * @param options The display options
      */
-    constructor(containerElement: HTMLElement, screenWidth: number, screenHeight: number, windowImageFactory: WebXWindowImageFactory, cursorFactory: WebXCursorFactory);
+    constructor(containerElement: HTMLElement, screenWidth: number, screenHeight: number, windowImageFactory: WebXWindowImageFactory, cursorFactory: WebXCursorFactory, options?: WebXDisplayOptions);
     /**
      * Displays the screen by adding it to the scene.
      */

package/dist/display/WebXDisplayOptions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stores generic configuration options for display filters
+ */
+export type WebXFilterOptions = {
+    name?: string;
+    params?: any;
+};
+/**
+ * Stores configuration settings used by the WebX Display
+ */
+export type WebXDisplayOptions = {
+    backgroundColor?: string | number;
+    forceCanvas?: boolean;
+    disableStencil?: boolean;
+    filter?: string | WebXFilterOptions;
+};

package/dist/display/WebXDisplayOverlay.d.ts

@@ -1,10 +1,48 @@
 import { WebXCursor } from "./WebXCursor";
+/**
+ * WebXDisplayOverlay
+ *
+ * Manages an absolute-positioned overlay element that hosts the WebX cursor canvas.
+ * The overlay is initially hidden and can be toggled via the `visible` setter.
+ */
 export declare class WebXDisplayOverlay {
     private _cursor;
+    /**
+     * The underlying overlay DOM element.
+     */
     private readonly _overlayElement;
+    /**
+     * Accessor for the overlay DOM element.
+     *
+     * @returns The root overlay HTMLElement used to host overlay content.
+     */
     get overlayElement(): HTMLElement;
+    /**
+     * Show or hide the overlay.
+     *
+     * @param visible - `true` to show the overlay, `false` to hide it.
+     */
     set visible(visible: boolean);
+    /**
+     * Create a new WebXDisplayOverlay.
+     *
+     * @param _cursor - The WebXCursor instance whose canvas will be appended to the overlay.
+     */
     constructor(_cursor: WebXCursor);
+    /**
+     * Update per-frame overlay logic.
+     *
+     * Call this from the application's render loop if the overlay needs per-frame updates
+     * (positioning, visibility logic, etc.). Currently a no-op.
+     */
     update(): void;
+    /**
+     * Create and configure the overlay HTMLElement.
+     *
+     * The element is positioned absolutely to cover its container, uses a high z-index,
+     * and starts hidden with overflow clipped.
+     *
+     * @returns A configured `div` element to use as the display overlay.
+     */
     private _createDisplayOverlayElement;
 }

package/dist/display/WebXMaterial.d.ts

@@ -1,13 +1,69 @@
 import { Color, ShaderMaterial, Texture } from 'three';
+/**
+ * WebXMaterial
+ *
+ * A custom ShaderMaterial that supports an optional diffuse map, alpha map, and stencil
+ * texture. It exposes convenience getters/setters for these textures and synchronizes
+ * texture transforms (matrix) with the shader uniforms before rendering.
+ */
 export declare class WebXMaterial extends ShaderMaterial {
+    /**
+     * Diffuse texture (RGB) used to modulate the material color.
+     */
     get map(): Texture;
+    /**
+     * Set the diffuse texture. Assigning a texture updates the `map` uniform value.
+     */
     set map(value: Texture);
+    /**
+     * Alpha texture used to control per-pixel opacity (uses the `g` channel).
+     */
     get alphaMap(): Texture;
+    /**
+     * Set the alpha texture. Assigning a texture updates the `alphaMap` uniform value.
+     */
     set alphaMap(value: Texture);
+    /**
+     * Stencil texture used to discard fragments where stencil.r < 0.5.
+     */
     get stencilMap(): Texture;
+    /**
+     * Set the stencil texture. Toggles the `USE_STENCILMAP` shader define when a texture
+     * is present or removed.
+     *
+     * @param value - Texture to use as stencil or `null` to disable stencil testing.
+     */
     set stencilMap(value: Texture);
+    /**
+     * Material base color (multiplicative with `map` if present).
+     */
     get color(): Color;
+    /**
+     * Set the material color by copying the provided `Color`.
+     *
+     * @param value - New base color.
+     */
     set color(value: Color);
+    /**
+     * Create a new WebXMaterial.
+     *
+     * Options in `params`:
+     * - `color` (Color | number | string): Optional initial color; forwarded to `this.color.set`.
+     *
+     * The material is configured with:
+     * - custom vertex and fragment shaders
+     * - uniforms for textures and transforms
+     * - `transparent: true` to allow alpha blending
+     * - `side: BackSide` suitable for inside-out rendering surfaces
+     *
+     * @param params - Optional initialization parameters.
+     */
     constructor(params?: any);
+    /**
+     * Lifecycle hook called before rendering the material.
+     *
+     * Synchronizes texture matrices to the shader uniforms when the textures' `matrixAutoUpdate`
+     * flags are enabled. This allows UV transforms applied to `Texture`s to be used by the shader.
+     */
     onBeforeRender(): void;
 }

package/dist/display/filter/WebXCRTFilterMaterial.d.ts

@@ -0,0 +1,36 @@
+import { WebXFilterMaterial } from "./WebXFilterMaterial";
+import { Texture } from "three";
+/**
+ * WebXCRTFilterMaterial
+ *
+ * Shader-based post-process material emulating CRT/tube display effects:
+ * curvature, scanlines, vignette, noise/flicker, chromatic aberration,
+ * brightness/contrast adjustment and phosphor glow. Extends `WebXFilterMaterial`
+ * and exposes a `tDiffuse` setter plus an `update()` method for time-based animation.
+ */
+export declare class WebXCRTFilterMaterial extends WebXFilterMaterial {
+    /**
+     * Start time used to drive `time` uniform (in seconds).
+     * @private
+     */
+    private _startTime;
+    /**
+     * Set the source texture for the filter (`tDiffuse` uniform).
+     *
+     * @param value - Three.js `Texture` containing the scene to be filtered.
+     */
+    set tDiffuse(value: Texture);
+    /**
+     * Construct a new CRT filter material.
+     *
+     * @param params - Optional parameter overrides for the filter uniforms.
+     */
+    constructor(params?: any);
+    /**
+     * Update per-frame state for the material.
+     *
+     * Updates the `time` uniform based on the elapsed time since construction.
+     * Called by the owning `WebXFilter` before rendering the filter pass.
+     */
+    update(): void;
+}

package/dist/display/filter/WebXFilter.d.ts

@@ -0,0 +1,55 @@
+import * as THREE from "three";
+import { Camera, Scene } from "three";
+import { WebXFilterMaterial } from "./WebXFilterMaterial";
+/**
+ * WebXFilter
+ *
+ * Helper that renders a provided scene into an offscreen render target and then
+ * applies a full-screen filter material to that texture providing a post-processing
+ * effect to the entire screen.
+ */
+export declare class WebXFilter {
+    /**
+     * Renderer used for both offscreen and final compositing passes.
+     */
+    private _renderer;
+    /**
+     * Scene containing the single mesh used to draw the filter pass.
+     *
+     * Present only when a `filterMaterial` was supplied in the constructor.
+     */
+    private readonly _sceneScreen;
+    /**
+     * Material that performs the post-process/filtering step.
+     */
+    private readonly _filterMaterial;
+    /**
+     * Render target used to capture the main scene before the filter is applied.
+     * May be `null` if no `filterMaterial` was provided.
+     */
+    private readonly _rtTexture;
+    /**
+     * Create a new WebXFilter.
+     *
+     * When `filterMaterial` is provided:
+     * - An offscreen `WebGLRenderTarget` is created with the given width/height.
+     * - The filter material's `tDiffuse` is set to the render target's texture (the fully rendered scene of windows)
+     *
+     * @param renderer - WebGL renderer used to perform rendering.
+     * @param screenWidth - Width to use for the offscreen render target and screen plane.
+     * @param screenHeight - Height to use for the offscreen render target and screen plane.
+     * @param filterMaterial - Optional filter material; when omitted the filter pass is disabled.
+     */
+    constructor(renderer: THREE.WebGLRenderer, screenWidth: number, screenHeight: number, filterMaterial?: WebXFilterMaterial);
+    /**
+     * Render the scene with optional post-processing filter. If the scene is dirty then all the webx windows
+     * are redrawn. The rendering is done on the render texture if present or the default framebuffer otherwise.
+     * When filtering is enabled, the sceneScreen is present and the full scene is rendered using the
+     * filter post-processing shader to the WebGL canvas.
+     *
+     * @param scene - The main scene to render into the offscreen target.
+     * @param camera - Camera used for both the main render and the filter pass.
+     * @param isSceneDirty - When true the main scene will be re-rendered.
+     */
+    render(scene: Scene, camera: Camera, isSceneDirty: boolean): void;
+}

package/dist/display/filter/WebXFilterFactory.d.ts

@@ -0,0 +1,31 @@
+import { WebXFilter } from "./WebXFilter";
+import { WebGLRenderer } from "three";
+/**
+ * WebXFilterFactory
+ *
+ * Factory for creating `WebXFilter` instances. Chooses a filter material by name
+ * and constructs a `WebXFilter` configured with the provided renderer and screen
+ * dimensions. If an unknown filter name is supplied the returned `WebXFilter`
+ * will be created without a filter material (no post-process applied).
+ */
+export declare class WebXFilterFactory {
+    /**
+     * Build a `WebXFilter` configured with a named filter material.
+     *
+     * @param renderer - Three.js WebGLRenderer used for rendering passes.
+     * @param screenWidth - Width in pixels for the offscreen render target and screen plane.
+     * @param screenHeight - Height in pixels for the offscreen render target and screen plane.
+     * @param name - Name of the filter to create (e.g. `test`, `crt`).
+     * @param params - Optional parameters forwarded to the chosen filter material constructor.
+     * @returns A `WebXFilter` configured with the selected filter material, or a `WebXFilter` with no filter if the name is unknown.
+     */
+    static Build(renderer: WebGLRenderer, screenWidth: number, screenHeight: number, name: string, params: any): WebXFilter;
+    /**
+     * Create an instance of a filter material by name.
+     *
+     * @param name - Filter name identifier.
+     * @param params - Optional parameters passed to the filter material constructor.
+     * @returns An instance of the requested filter material, or `null` if the name is unknown.
+     */
+    private static _createFilterMaterial;
+}

package/dist/display/filter/WebXFilterMaterial.d.ts

@@ -0,0 +1,41 @@
+import { ShaderMaterial, ShaderMaterialParameters, Texture } from 'three';
+/**
+ * WebXFilterMaterial
+ *
+ * Abstract base class for post-process filter materials used by `WebXFilter`.
+ * Subclasses should provide a shader-based material that consumes a `tDiffuse`
+ * texture and updates any time-dependent or parameter-driven uniforms in `update()`.
+ *
+ * This class extends Three's `ShaderMaterial` to inherit shader and rendering
+ * behavior while enforcing a minimal API required by the filter pipeline.
+ */
+export declare abstract class WebXFilterMaterial extends ShaderMaterial {
+    /**
+     * Construct a new WebXFilterMaterial.
+     *
+     * The constructor is protected because this class is abstract and intended to
+     * be subclassed. Subclasses should call `super(parameters)` to initialize the
+     * underlying `ShaderMaterial` with their shader, uniforms and parameters.
+     *
+     * @param parameters - Optional `ShaderMaterialParameters` forwarded to the `ShaderMaterial` constructor.
+     */
+    protected constructor(parameters?: ShaderMaterialParameters);
+    /**
+     * Update per-frame/stateful data used by the material.
+     *
+     * Called by the owning `WebXFilter` before the filter pass is rendered. Implementations
+     * should update time-based uniforms, animation state, or any derived values needed
+     * by the shader.
+     */
+    abstract update(): void;
+    /**
+     * Set the diffuse/source texture for the filter.
+     *
+     * The filter pipeline will provide the texture containing the previously rendered
+     * scene (usually an offscreen render target). Implementations must assign the
+     * provided `Texture` to the shader uniform used as the input (commonly named `tDiffuse`).
+     *
+     * @param value - Texture containing the scene to be filtered.
+     */
+    abstract set tDiffuse(value: Texture);
+}

package/dist/display/filter/WebXTestFilterMaterial.d.ts

@@ -0,0 +1,41 @@
+import { WebXFilterMaterial } from "./WebXFilterMaterial";
+import { Texture } from "three";
+/**
+ * WebXTestFilterMaterial
+ *
+ * Simple test filter material used by the WebX filter pipeline. It extends
+ * `WebXFilterMaterial` and provides a shader that animates channel mixing
+ * driven by a `time` uniform.
+ *
+ * The material expects a `tDiffuse` texture (the source scene) and updates
+ * the `time` uniform each frame in `update()` to animate the effect.
+ *
+ * @extends WebXFilterMaterial
+ */
+export declare class WebXTestFilterMaterial extends WebXFilterMaterial {
+    /**
+     * Set the diffuse/source texture for the filter.
+     *
+     * The texture is assigned to the shader uniform `tDiffuse`.
+     *
+     * @param value - Texture containing the scene to be filtered.
+     */
+    set tDiffuse(value: Texture);
+    /**
+     * Create a new WebXTestFilterMaterial.
+     *
+     * Accepts an optional `params` object. If `params.map` is provided it will be
+     * used as the initial `tDiffuse` texture. The material defines a `time`
+     * uniform used to animate the color-mixing effect.
+     *
+     * @param params - Optional parameters (e.g. `{ map: Texture }`).
+     */
+    constructor(params?: any);
+    /**
+     * Update per-frame state for the material.
+     *
+     * Updates the `time` uniform to a value in the range \[0,1\] based on the
+     * current time to produce a smooth oscillation.
+     */
+    update(): void;
+}

package/dist/display/filter/index.d.ts

@@ -0,0 +1,5 @@
+export * from './WebXFilterMaterial';
+export * from './WebXTestFilterMaterial';
+export * from './WebXCRTFilterMaterial';
+export * from './WebXFilter';
+export * from './WebXFilterFactory';

package/dist/display/index.d.ts

@@ -1 +1,2 @@
 export * from './WebXDisplay';
+export * from './WebXDisplayOptions';

package/dist/index.d.ts

@@ -7,4 +7,5 @@ export * from './texture';
 export * from './tracer';
 export * from './tunnel';
 export * from './WebXClient';
+export * from './WebXOptions';
 export * from './WebXConnectionHandler';

package/dist/renderer/WebXCanvasRenderer.d.ts

@@ -1,5 +1,4 @@
 import { Camera, ColorRepresentation, Object3D, Texture, Vector2 } from 'three';
-import { Blob } from "buffer";
 /**
  * The `WebXCanvasRenderer` class is responsible for rendering a desktop-like environment
  * using HTML elements. It integrates with the Three.js library using 3D objects (meshes, materials, textures)

package/dist/texture/WebXTexture.d.ts

@@ -1,18 +1,67 @@
-export declare const SRGBColorSpace = "srgb";
-export declare const LinearSRGBColorSpace = "srgb-linear";
+/**
+ * WebXTexture
+ *
+ * Lightweight container for image or raw pixel data that can be transferred
+ * between threads (via postMessage) when backed by an ImageBitmap or ArrayBuffer.
+ *
+ * Holds either an `image` (ImageBitmap | HTMLImageElement) or raw `data` (Uint8ClampedArray).
+ */
 export declare class WebXTexture {
+    /**
+     * Image source when available. May be an ImageBitmap (transferable) or a
+     * regular HTMLImageElement.
+     */
     image: ImageBitmap | HTMLImageElement;
+    /**
+     * Raw pixel data (RGBA) when using typed array backing instead of an image.
+     */
     data: Uint8ClampedArray;
-    colorSpace: string;
+    /**
+     * Whether the texture data should be flipped vertically when uploaded.
+     */
     flipY: boolean;
+    /**
+     * Pixel width of the texture.
+     */
     width: number;
+    /**
+     * Pixel height of the texture.
+     */
     height: number;
+    /**
+     * Create a new WebXTexture.
+     *
+     * The `data` parameter accepts an object with optional fields:
+     * - `image` - an ImageBitmap or HTMLImageElement to use as the texture source.
+     * - `data` - a Uint8ClampedArray with raw pixel data (used when `image` is absent).
+     * - `width`/`height` - dimensions to use when `image` is not provided.
+     *
+     * When `image` is provided it takes precedence for `width`/`height`.
+     *
+     * @param data - Initialization object for the texture.
+     */
     constructor(data: {
         image?: ImageBitmap | HTMLImageElement;
         data?: Uint8ClampedArray;
         width?: number;
         height?: number;
     });
+    /**
+     * Determine whether the texture contents are transferable (can be sent via
+     * postMessage as a Transferable).
+     *
+     * Returns true if the texture is backed by an ImageBitmap or by a typed
+     * array (`data`).
+     */
     isTransferable(): boolean;
-    get transferable(): Transferable;
+    /**
+     * Retrieve the Transferable object for posting to another thread.
+     *
+     * - If backed by an ImageBitmap, the ImageBitmap itself is returned.
+     * - If using raw `data`, the underlying ArrayBuffer is returned.
+     * - Otherwise returns `null`.
+     *
+     * @returns The Transferable object or `null` if not transferable.
+     */
+    get transferable(): Transferable | null;
 }

package/dist/texture/WebXTextureFactory.d.ts

@@ -9,10 +9,9 @@ export declare class WebXTextureFactory {
      *
      * @param imageData The raw image data as a Uint8Array.
      * @param mimetype The MIME type of the image data (e.g., "image/png").
-     * @param colorSpace The color space of the image data (e.g., "srgb").
      * @returns A promise that resolves to the created texture.
      */
-    createTextureFromArray(imageData: Uint8Array, mimetype: string, colorSpace: string): Promise<WebXTexture>;
+    createTextureFromArray(imageData: Uint8Array, mimetype: string): Promise<WebXTexture>;
     /**
      * Creates a texture from a Blob object.
      *