@openglobus/og 0.28.7 → 1.0.0-rc10

package/lib/utils/TerrainWorker.d.ts

@@ -1,6 +1,7 @@
 import { BaseWorker } from "./BaseWorker";
 import { Segment } from "../segment/Segment";
 import type { NumberArray6 } from "../bv/Sphere";
+import { NumberArray3 } from "../math/Vec3";
 interface TerrainInfo {
     segment: Segment;
     elevations: Float32Array;
@@ -9,13 +10,12 @@ export interface ITerrainWorkerData {
     id: number;
     normalMapNormals: Float32Array | null;
     normalMapVertices: Float64Array | null;
-    normalMapVerticesHigh: Float32Array | null;
-    normalMapVerticesLow: Float32Array | null;
     terrainVertices: Float64Array | null;
     terrainVerticesHigh: Float32Array | null;
     terrainVerticesLow: Float32Array | null;
     noDataVertices: Uint8Array | null;
     bounds: NumberArray6;
+    relativeCenter: NumberArray3;
 }
 type MessageEventExt = MessageEvent & {
     data: ITerrainWorkerData;

package/lib/utils/TextureAtlas.d.ts

@@ -10,6 +10,7 @@ import type { WebGLTextureExt } from "../webgl/Handler";
  * @class
  * @param {number} [width=1024] - Texture atlas width, if it hasn't 1024 default.
  * @param {number} [height=1024] - Texture atlas height, if it hasn't 1024 default.
+ * @param {string|number} [colorSpace="linear"] - Texture atlas color space. Available values: "linear", "srgb", 0, 1.
  */
 declare class TextureAtlas {
     /**
@@ -34,7 +35,11 @@ declare class TextureAtlas {
     protected _images: HTMLImageElementExt[];
     protected _btree: TextureAtlasNode | null;
     protected _imagesCacheManager: ImagesCacheManager;
-    constructor(width?: number, height?: number);
+    protected _colorSpace: number;
+    protected _internalFormat: number | null;
+    constructor(width?: number, height?: number, colorSpace?: string | number);
+    static getColorSpace(colorSpace?: string | number): number;
+    protected _updateInternalFormat(): void;
     /**
      * Returns atlas javascript image object.
      * @public
@@ -87,7 +92,7 @@ declare class TextureAtlas {
      * Creates atlas gl texture.
      * @public
      */
-    createTexture(img?: HTMLImageElement | null, internalFormat?: number): void;
+    createTexture(img?: HTMLImageElement | null): void;
     /**
      * Asynchronous function that loads and creates image to the image cache, and call success callback when it's done.
      * @public

package/lib/utils/TextureResourceManager.d.ts

@@ -0,0 +1,162 @@
+import type { Handler, ImageSource, WebGLTextureExt } from "../webgl/Handler";
+interface TextureResourceEntry {
+    key: string;
+    texture: WebGLTextureExt;
+    refCount: number;
+}
+export interface RendererTextureRequest {
+    image: ImageSource;
+    resourceKey?: string;
+    sourceUri?: string;
+    mimeType?: string;
+    byteLength?: number;
+    internalFormat?: number | null;
+    texParami?: number | null;
+}
+/**
+ * Manages shared WebGL textures with reference counting.
+ * Reuses textures for the same resource key and deletes them when no owners remain.
+ */
+export declare class TextureResourceManager {
+    protected _handler: Handler;
+    protected _entriesByKey: Map<string, TextureResourceEntry>;
+    protected _keysByTexture: WeakMap<WebGLTextureExt, string>;
+    protected _objectKeys: WeakMap<ImageSource, number>;
+    protected _objectKeyCounter: number;
+    /**
+     * @param handler WebGL handler used to create and delete textures.
+     */
+    constructor(handler: Handler);
+    /**
+     * Returns an existing texture for the same resource or creates a new one.
+     * Increases reference count for reused textures.
+     * @param params Texture source and GPU creation parameters.
+     * @returns Managed WebGL texture or null if creation failed.
+     */
+    acquireTexture(params: RendererTextureRequest): WebGLTextureExt | null;
+    /**
+     * Releases one texture reference.
+     * Deletes GPU texture only when the reference count reaches zero.
+     * @param texture Managed texture previously returned by acquireTexture.
+     */
+    releaseTexture(texture: WebGLTextureExt | null | undefined): void;
+    /**
+     * Deletes all managed GPU textures and clears manager state.
+     */
+    clear(): void;
+    /**
+     * Returns number of unique managed texture entries.
+     * @returns Number of entries in the manager.
+     */
+    getEntryCount(): number;
+    /**
+     * Returns debug statistics for managed textures.
+     * @returns Object with number of entries and total reference count.
+     */
+    getStats(): {
+        entries: number;
+        refs: number;
+    };
+    /**
+     * Builds a stable texture resource key.
+     *
+     * The key is composed of two logical parts:
+     *
+     * 1. Source image identity
+     *    Describes where the original image comes from or how it can be uniquely identified.
+     *
+     *    Supported prefixes:
+     *
+     *    - res:
+     *      A precomputed resource key provided by the GLTF parser.
+     *      This is the preferred path for GLTF/GLB textures.
+     *
+     *      Example:
+     *      res:gltf-image|bytes:9a4c1f20|mime:image/png|len:24576
+     *
+     *    - uri:
+     *      A normalized external image URI.
+     *      Used when the texture comes from an external image file.
+     *      The URI should be resolved relative to the GLTF file path.
+     *
+     *      Example:
+     *      uri:https://example.com/models/tree/textures/baseColor.png
+     *
+     *    - fp:
+     *      A content fingerprint calculated from image pixels.
+     *      This is an expensive fallback path because it may require canvas readback.
+     *      It can also fail for cross-origin images.
+     *
+     *      Example:
+     *      fp:7f21ab09
+     *
+     *    - obj:
+     *      A last-resort object identity key.
+     *      Used only when no resourceKey, URI, or content fingerprint is available.
+     *      This avoids accidental sharing between unrelated images.
+     *
+     *      Example:
+     *      obj:3
+     *
+     * 2. GPU texture creation parameters.
+     *    Describes how the source image is uploaded to WebGL.
+     *    The same source image may require different GPU textures if creation parameters differ.
+     *
+     *    Supported fields:
+     *
+     *    - fmt:
+     *      Internal texture format passed to Handler.createTextureDefault(...).
+     *      If absent, "fmt:default" means the default internal format is used.
+     *
+     *      Example:
+     *      fmt:default
+     *      fmt:6408
+     *
+     *    - wrap:
+     *      Texture wrapping/filtering parameter passed to Handler.createTextureDefault(...).
+     *      If absent, "wrap:default" means the default texture parameter is used.
+     *
+     *      Example:
+     *      wrap:default
+     *      wrap:10497
+     *
+     *    - mime:
+     *      MIME type of the original image, if available.
+     *      Used as an additional discriminator and for debugging.
+     *
+     *      Example:
+     *      mime:image/png
+     *
+     *    - len:
+     *      Original image byte length, if available.
+     *      Used as an additional cheap discriminator, but not as the primary identity.
+     *
+     *      Example:
+     *      len:24576
+     *
+     * Important:
+     *
+     * - GLTF texture/image name is intentionally not used as a primary identity key.
+     *   Names may be missing, duplicated, or different for the same binary image.
+     *
+     * - The preferred identity source is resourceKey from the GLTF parser.
+     *
+     * - The fallback order is:
+     *   resourceKey -> normalized URI -> content fingerprint -> object identity.
+     *
+     * - The final key must distinguish not only the source image, but also the GPU upload
+     *   parameters that may affect the resulting WebGLTexture.
+     */
+    protected _buildResourceKey(params: RendererTextureRequest): string;
+    protected _getObjectKey(image: ImageSource): number;
+    protected _getExternalImageUri(image: ImageSource): string | null;
+    protected _fingerprintImage(image: ImageSource): {
+        hash: string;
+        byteLength: number;
+    } | null;
+    protected _getImageSize(image: ImageSource): {
+        width: number;
+        height: number;
+    } | null;
+}
+export {};

package/lib/utils/VectorTileCreator.d.ts

@@ -1,4 +1,4 @@
-import { Framebuffer } from '../webgl/Framebuffer';
+import { Framebuffer } from "../webgl/Framebuffer";
 import { Handler } from "../webgl/Handler";
 import { Material } from "../layer/Material";
 import { Planet } from "../scene/Planet";

package/lib/utils/colorSpace.d.ts

@@ -0,0 +1,9 @@
+import { Vec3 } from "../math/Vec3";
+import type { NumberArray3 } from "../math/Vec3";
+export declare const LINEAR = 0;
+export declare const SRGB = 1;
+export declare function getColorSpace(colorSpace?: string | number, defaultColorSpace?: number): number;
+export declare function srgbToLinearArr(arr: NumberArray3): NumberArray3;
+export declare function srgbToLinear3v(v: Vec3): NumberArray3;
+export declare function srgbToLinear(v: number): number;
+export declare function linearToSrgbArr(arr: NumberArray3): NumberArray3;

package/lib/utils/gltf/gltfParser.d.ts

@@ -1,6 +1,6 @@
 import { Entity } from "../../entity";
 import { Object3d } from "../../Object3d";
-import { GltfData, Mesh } from "./types";
+import { GltfData, Mesh, MimeType } from "./types";
 export declare class Gltf {
     private gltf;
     private static _dracoDecoderModule;
@@ -9,13 +9,20 @@ export declare class Gltf {
     private _materials;
     private _images;
     meshes: Mesh[];
-    constructor(gltf: GltfData);
+    protected _gltfBaseUri?: string;
+    constructor(gltf: GltfData, gltfBaseUri?: string);
     getObjects3d(): Object3d[];
     toEntities(): Entity[];
     private _nodeToEntity;
     meshToEntity(mesh: Mesh, parent?: Entity): Entity;
     private _initImages;
     private _getImage;
+    private _getTextureImage;
+    protected _buildImageResourceKey(mimeType?: MimeType, bufferViewIndex?: number, sourceUri?: string, rawUri?: string): string | undefined;
+    protected _getBufferViewBytes(bufferViewIndex: number): Uint8Array;
+    protected _hashBytes(bytes: Uint8Array): string;
+    protected _hashString(value: string): string;
+    protected _isDataUri(uri: string): boolean;
     private _initMaterials;
     private _initMeshes;
     private _buildPrimitive;

package/lib/utils/gltf/types.d.ts

@@ -1,4 +1,5 @@
 import { Object3d } from "../../Object3d";
+import type { TypedArray } from "../shared";
 export interface GltfData {
     bin: ArrayBuffer[];
     gltf: GltfMetadata;
@@ -22,6 +23,21 @@ export interface GltfMetadata {
                 texCoord?: number;
             };
         };
+        extensions?: {
+            KHR_materials_pbrSpecularGlossiness?: {
+                diffuseFactor?: number[];
+                diffuseTexture?: {
+                    index: number;
+                    texCoord?: number;
+                };
+                specularFactor?: number[];
+                glossinessFactor?: number;
+                specularGlossinessTexture?: {
+                    index: number;
+                    texCoord?: number;
+                };
+            };
+        };
         normalTexture?: {
             index: number;
             texCoord?: number;
@@ -80,7 +96,7 @@ export interface GltfPrimitive {
 }
 export type PrimitiveAttributes = {
     POSITION: number;
-    NORMAL: number;
+    NORMAL?: number;
 } & Record<string, number>;
 export interface GltfNode {
     camera?: number;
@@ -141,10 +157,10 @@ export interface Mesh {
 }
 export interface Primitive {
     name: string;
-    indices?: ArrayBufferLike;
-    vertices: ArrayBufferLike;
-    normals: ArrayBufferLike;
-    texCoords?: ArrayBufferLike;
+    indices?: TypedArray;
+    vertices: TypedArray;
+    normals?: TypedArray;
+    texCoords?: TypedArray;
     material?: Material;
     mode: PrimitiveMode;
     object3d?: Object3d;
@@ -153,7 +169,10 @@ export interface Material {
     name: string;
     baseColorFactor?: number[];
     baseColorTexture?: Texture;
+    metallicFactor?: number;
+    roughnessFactor?: number;
     metallicRoughnessTexture?: Texture;
+    specularGlossinessTexture?: Texture;
     normalTexture?: NormalTexture;
     occlusionTexture?: OcclusionTexture;
     emissiveTexture?: Texture;

package/lib/utils/shared.d.ts

@@ -20,6 +20,8 @@ export declare function isEmpty(v: any): boolean;
  */
 export declare function isUndef(obj?: any): boolean;
 export declare function isUndefExt(obj: any, defVal: any): any;
+export declare function fnv1a32(bytes: Uint8Array | Uint8ClampedArray): string;
+export declare function normalizeUri(src: string, baseUri?: string): string;
 export declare function stamp(obj: any): number;
 export declare function isString(s: any): boolean;
 export declare function rgbToStringHTML(rgb: NumberArray3 | Vec3): string;
@@ -55,6 +57,7 @@ export declare function htmlColorToRgb(htmlColor: string): Vec3;
 export declare function stringTemplate(template: string, params?: any): string;
 /**
  * Replace template substrings between '${...}' tokens.
+ * Also supports escaped '\${...}' tokens emitted by GLSL bundlers.
  * @param {string} template - String with templates in "${" and "}"
  * @param {Object} params - Template named object with subsrtings.
  * @returns {string} -
@@ -74,8 +77,9 @@ export declare function parseHTML(htmlStr: string): HTMLElement[];
 export declare function print2d(id: string, text: string, x: number, y: number): void;
 export declare function isNumber(value: any): boolean;
 export declare function defaultString(str?: string, def?: string): string;
-export declare function createVector3(v?: number | Vec3 | Vec2 | NumberArray3 | NumberArray2 | null, def?: Vec3): Vec3;
-export declare function createVector4(v?: Vec4 | NumberArray4 | null, def?: Vec4): Vec4;
+export declare function createVec2(v?: number | Vec2 | NumberArray2 | null, def?: Vec2): Vec2;
+export declare function createVec3(v?: number | Vec3 | Vec2 | NumberArray3 | NumberArray2 | null, def?: Vec3): Vec3;
+export declare function createVec4(v?: Vec4 | NumberArray4 | null, def?: Vec4): Vec4;
 export declare function createColorRGBA(c?: string | NumberArray4 | Vec4 | null, def?: Vec4): Vec4;
 export declare function createColorRGB(c?: string | NumberArray3 | Vec3 | null, def?: Vec3): Vec3;
 export declare function createExtent(e?: Extent | [[number, number], [number, number]] | null, def?: Extent): Extent;
@@ -193,6 +197,7 @@ export type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array
  * @param {TypedArray | number[]} b
  */
 export declare function concatTypedArrays(a: TypedArray, b: TypedArray | number[]): TypedArray;
+export declare function insertTypedArray<T extends TypedArray>(arr: T, starting: number, insert: T | number[]): T;
 /**
  * Concatenates two the same  arrays
  * @param {TypedArray | number[]} [a=[]] - First array
@@ -238,7 +243,7 @@ export declare function spliceTypedArray<T extends TypedArray>(arr: T, starting:
 /**
  * Returns 64-bit triangle coordinate array from inside of the source triangle array.
  * @static
- * @param {TypedArray | number[]} sourceArr - Source array
+ * @param {TypedArray | number[]} srcArr - Source array
  * @param {number} gridSize - Source array square matrix size
  * @param {number} i0 - First row index source array matrix
  * @param {number} j0 - First column index
@@ -246,7 +251,7 @@ export declare function spliceTypedArray<T extends TypedArray>(arr: T, starting:
  * @return {Float64Array} Triangle coordinates array from the source array.
  * @TODO: optimization
  */
-export declare function getMatrixSubArray64(sourceArr: TypedArray | number[], gridSize: number, i0: number, j0: number, size: number): Float64Array;
+export declare function getMatrixSubArray64(srcArr: TypedArray | number[], gridSize: number, i0: number, j0: number, size: number): Float64Array;
 /**
  * Returns 32-bit triangle coordinate array from inside of the source triangle array.
  * @static
@@ -262,7 +267,7 @@ export declare function getMatrixSubArray32(sourceArr: TypedArray | number[], gr
  * Returns two float32 triangle coordinate arrays from inside of the source triangle array.
  * @TODO: optimization
  */
-export declare function getMatrixSubArrayBoundsExt(sourceArr: TypedArray | number[], sourceArrHigh: TypedArray | number[], sourceArrLow: TypedArray | number[], noDataVertices: TypedArray | number[] | undefined, gridSize: number, i0: number, j0: number, size: number, outArr: TypedArray | number[], outArrHigh: TypedArray | number[], outArrLow: TypedArray | number[], outBounds: any, outNoDataVertices: TypedArray | number[]): void;
+export declare function getMatrixSubArrayBoundsExt(srcArr: TypedArray | number[], noDataVertices: TypedArray | number[] | undefined, gridSize: number, i0: number, j0: number, size: number, srcRelativeCenter: Vec3, dstRelativeCenter: Vec3, outArr: TypedArray | number[], outArrHigh: TypedArray | number[], outArrLow: TypedArray | number[], outBounds: any, outNoDataVertices: TypedArray | number[]): void;
 export declare function cloneArray(items: any[]): any[];
 /**
  * Promise for load images
@@ -271,6 +276,8 @@ export declare function cloneArray(items: any[]): any[];
  * @returns {Promise<Image>} Returns promise.
  */
 export declare function loadImage(url: string): Promise<HTMLImageElement>;
+export declare function ensureImageReady(image: HTMLImageElement): Promise<boolean>;
+export declare function prepareTextureImage(image: HTMLImageElement): Promise<HTMLImageElement | HTMLCanvasElement | null>;
 /**
  * Gets image is loaded
  * @param {HTMLImageElement} image

package/lib/utils/textureResourceMeta.d.ts

@@ -0,0 +1,9 @@
+export declare const OG_TEXTURE_RESOURCE_META_KEY: unique symbol;
+export interface ITextureResourceMeta {
+    resourceKey?: string;
+    sourceUri?: string;
+    mimeType?: string;
+    byteLength?: number;
+}
+export declare function getTextureResourceMeta(target: object | null | undefined): ITextureResourceMeta | undefined;
+export declare function setTextureResourceMeta(target: object | null | undefined, meta: ITextureResourceMeta | undefined): void;

package/lib/webgl/BaseFramebuffer.d.ts

@@ -6,6 +6,7 @@ export interface IBaseFramebufferParams {
     depthComponent?: string;
     size?: number;
     filter?: string;
+    sharedDepthFramebuffer?: BaseFramebuffer | null;
 }
 export declare class BaseFramebuffer {
     static __counter__: number;
@@ -13,6 +14,7 @@ export declare class BaseFramebuffer {
     handler: Handler;
     _fbo: WebGLFramebuffer | null;
     protected _depthRenderbuffer: WebGLRenderbuffer | null;
+    protected _sharedDepthFramebuffer: BaseFramebuffer | null;
     _width: number;
     _height: number;
     protected _depthComponent: string;
@@ -21,8 +23,13 @@ export declare class BaseFramebuffer {
     protected _useDepth: boolean;
     protected _filter: string;
     constructor(handler: Handler, options?: IBaseFramebufferParams);
+    static blitTo(destFramebuffer: BaseFramebuffer, sourceFramebuffer: BaseFramebuffer, glAttachmentIndex: number | null, glMask: number, glFilter: number): void;
+    blitDepthFrom(sourceFramebuffer: BaseFramebuffer, glFilter?: number): void;
     get width(): number;
     get height(): number;
+    get depthRenderbuffer(): WebGLRenderbuffer | null;
+    get sharedDepthFramebuffer(): BaseFramebuffer | null;
+    get sharedDepthRenderbuffer(): WebGLRenderbuffer | null;
     /**
      * Sets framebuffer viewport size.
      * @public
@@ -40,6 +47,34 @@ export declare class BaseFramebuffer {
      */
     isComplete(): boolean;
     checkStatus(): number;
+    /**
+     * Checks active framebuffer completeness and logs readable status on failure.
+     * @public
+     * @param {string} [message] - Warning message prefix.
+     * @returns {boolean} `true` when active framebuffer is complete.
+     */
+    validateComplete(message?: string): boolean;
+    /**
+     * Binds a 2D texture to the active framebuffer color attachment.
+     * @public
+     * @param {WebGLTexture} texture - Output texture.
+     * @param {number} [glAttachment=COLOR_ATTACHMENT0] - GL color attachment.
+     */
+    bindOutputTexture(texture: WebGLTexture, glAttachment?: number): void;
+    /**
+     * Binds a texture array layer to the active framebuffer color attachment.
+     * Activate framebuffer before calling this method.
+     * @public
+     * @param {WebGLTexture | null} texture - Output texture array.
+     * @param {number} layer - Array layer index.
+     * @param {number} [colorAttachmentIndex=0] - Color attachment index.
+     * @param {number} [level=0] - Mipmap level.
+     */
+    bindOutputTextureLayer(texture: WebGLTexture | null, layer: number, colorAttachmentIndex?: number, level?: number): void;
+    /**
+     * Converts framebuffer status enum to readable text.
+     */
+    statusToText(status: number): string;
     /**
      * Activate framebuffer frame to draw.
      * @public

package/lib/webgl/Framebuffer.d.ts

@@ -5,8 +5,6 @@ import type { TypedArray } from "../utils/shared";
 import type { NumberArray4 } from "../math/Vec4";
 export interface ITargetParams {
     internalFormat?: string;
-    format?: string;
-    type?: string;
     attachment?: string;
     filter?: string;
     readAsync?: boolean;
@@ -20,8 +18,8 @@ export interface IFrameBufferParams extends IBaseFramebufferParams {
 type TypedArrayConstructor = Uint8ArrayConstructor | Float32ArrayConstructor;
 interface ITarget {
     internalFormat: string;
-    format: string;
-    type: string;
+    pixelFormat: string;
+    pixelType: string;
     attachment: string;
     filter: string;
     pixelBufferIndex: number;
@@ -52,6 +50,11 @@ export declare class Framebuffer extends BaseFramebuffer {
     pixelBuffers: IPixelBuffer[];
     protected _skipFrame: boolean;
     constructor(handler: Handler, options?: IFrameBufferParams);
+    static getTargetReadParams(internalFormat: string): {
+        pixelFormat: string;
+        pixelType: string;
+        TypeArrayConstructor: TypedArrayConstructor;
+    };
     static createTargets(targets?: ITargetParams[]): ITarget[];
     destroy(): void;
     /**
@@ -60,25 +63,23 @@ export declare class Framebuffer extends BaseFramebuffer {
      * @override
      */
     init(): void;
+    protected _attachExternalDepthRenderbuffer(depthRenderbuffer: WebGLRenderbuffer | null): void;
     /**
      * Check your constructor has targets like this
      * targets: [{
-     *  internalFormat: "RGBA",
-     *  type: "UNSIGNED_BYTE",
+     *  internalFormat: "RGBA8",
      *  attachment: "COLOR_ATTACHMENT",
      *  readAsync: true
      * }],
      **/
     readPixelBuffersAsync: (callback?: (buf: this) => void) => void;
-    getPixelBufferData(targetIndex?: number): TypedArray | null;
-    protected _createPixelBuffer(target: ITarget): void;
     /**
-     * Bind buffer texture.
-     * @public
-     * @param {WebGLTexture} texture - Output texture.
-     * @param {number} [glAttachment=0] - color attachment index.
+     * Synchronously reads all configured async pixel buffers for the current framebuffer state.
+     * Use when the same-frame CPU readback is required.
      */
-    bindOutputTexture(texture: WebGLTexture, glAttachment?: number): void;
+    readPixelBuffers(): void;
+    getPixelBufferData(targetIndex?: number): TypedArray | null;
+    protected _createPixelBuffer(target: ITarget): void;
     /**
      * Gets pixel RGBA color from framebuffer by coordinates.
      * @public