Class GPUMemoryManagerInternal

Owns GPU-resident, dynamically editable storage for tiles, geometry, and mesh attributes.

Owned by a ViewManager, used by MeshManager, RenderManager, and PickManager.

GPUMemoryManager implements a data-texture + batch based memory system to support rendering and picking for large scenes with frequent updates.

It is responsible for:

  • Allocating and managing the data textures that encode per-tile camera/pick matrices (per view).
  • Creating and tracking GPUMemoryBatch instances, which own GPU storage for geometry and mesh data.
  • Providing a stable handle (GPUMemoryMeshHandle) used by higher-level managers to update mesh state (transform, per-view visibility, render pass, color/opacity, etc.).
  • Uploading pending changes to the GPU via uploadChanges.
  • Tracking and reporting GPU memory usage statistics.

Tiled Coordinate System, RTC (Relative To Center), and GPU Matrix Textures

Large-scale 3D scenes require high-precision rendering, which is achieved by partitioning world space into "tiles". Each tile defines a local coordinate system centered at a specific world position, allowing geometry within the tile to be transformed relative to its center (RTC: Relative To Center). This approach minimizes floating-point precision errors when rendering large or distant objects.

Key Components

  • GPUTile:

    • Represents a single tile in world space.
    • Stores its center position and per-view RTC matrices (for both camera and picking).
    • Tracks usage count for efficient allocation and reuse.

  • GPUTileManager:

    • Allocates, synchronizes, and manages the lifecycle of all tiles.
    • Computes and updates RTC view and pick matrices for each tile as cameras move.
    • Maintains a mapping from world positions to tiles, and manages tile indices for GPU data textures.
    • Uploads updated RTC matrices to MatrixTexture objects for use in shaders.

  • MatrixTexture:

    • Stores RTC matrices for all tiles and views in a GPU-friendly format.
    • Updated by the GPUTileManager whenever camera/view state changes.

  • DataTextures.viewTileCameraMatrixTexture:

    • An array of MatrixTexture objects, one per view.
    • Each texture contains the RTC view matrices for all tiles in that view.
    • Automatically updated when a camera moves, ensuring the GPU always has the latest RTC transforms.

  • DataTextures.viewTilePickMatrixTexture:

    • An array of MatrixTexture objects, one per view.
    • Each texture contains the RTC pick matrices for all tiles in that view, used for accurate object picking.
    • Updated as needed before picking operations.

Matrix Conversion and GPU Upload

  • When a tile is created or a camera/view changes, the system computes an RTC view matrix for each tile and view.
  • The RTC view matrix is derived by combining the camera's view matrix with a translation that recenters the world origin at the tile's center.
  • These RTC matrices are packed into MatrixTexture objects and uploaded to the GPU as data textures.
  • Model matrices for objects are also converted to RTC form before upload, ensuring all transformations are relative to the tile center.

Shader Usage

  • In the vertex shader, the RTC view and model matrices are fetched from the appropriate MatrixTexture using the tile and view indices.
  • Vertex positions are transformed using these RTC matrices, maintaining high precision even for large coordinates.
  • This enables accurate rendering and picking across vast scenes without floating-point artifacts.

Workflow Summary

  1. Geometry is assigned to a tile based on its world position.
  2. The tile's RTC matrices are computed and stored in MatrixTexture objects.
  3. When the camera moves, RTC view matrices are updated and re-uploaded to the GPU.
  4. Shaders use the RTC matrices to transform geometry, ensuring high-precision rendering and picking.

Remarks

  • The manager currently assumes a maximum of 4 views for tile matrix tables.
  • GPUTile allocation/placement and per-view camera/pick matrices are coordinated by GPUTileManager.

Implements

Constructors

constructor

Properties

dataTextures

Accessors

itemSizesInBytes

Methods

addMesh cameraViewMatrixUpdated createBatch destroy getAllocatedBytes getDrawArraysParamsForMesh getGeometryAtIndex getMemoryUsage getMeshAtIndex getNumTiles getTile getUsedBytes hasMemoryForMesh init moveTile putTile removeMesh sceneMaterialPatternChanged setMeshAttribs setMeshClippable setMeshCulled setMeshMatrix setMeshRenderPass setMeshViewAttribs setMeshVisible setViewPickMatrix updateSceneTexture uploadChanges webglContextRestored

Constructors

constructor

Properties

dataTextures

dataTextures: DataTextures = null

Data texture bundle exposed for internal consumers (eg. render passes/shaders).

Populated after init succeeds. Set back to null after destroy.

Accessors

StaticitemSizesInBytes

Methods

addMesh

cameraViewMatrixUpdated

createBatch

destroy

getAllocatedBytes

getDrawArraysParamsForMesh

getGeometryAtIndex

getMemoryUsage

getMeshAtIndex

getNumTiles

getTile

getUsedBytes

hasMemoryForMesh

init

  • init(): SDKResult<void>

    Allocates GPU memory and initializes tile-related data textures for this manager.

    Creates:

    • viewTileCameraMatrixTexture[0..3] mapping tileIndex -> camera view matrix per view
    • viewTilePickMatrixTexture[0..3] mapping tileIndex -> pick matrix per view
    • A GPUTileManager for tile allocation and matrix updates
    • The dataTextures bundle used by render code

    Returns SDKResult<void>

    SDKResult that is ok:true when initialization succeeds, or ok:false when texture allocation fails (typically due to GPU memory limits).

    Remarks

    If allocation fails part-way through, already-allocated textures are destroyed before returning.

moveTile

putTile

removeMesh

sceneMaterialPatternChanged

  • sceneMaterialPatternChanged(material: SceneMaterial): boolean

    Re-encodes the per-batch pattern-table slots for a SceneMaterial whose linePattern or hatchPattern was just updated. Every batch that has allocated a slot for this material on either its line-pattern or hatch-pattern texture overwrites that slot with the new entries; batches that don't reference the material at all skip cheaply via a single Map.get.

    Returns true when at least one batch re-encoded a slot, which lets the caller decide whether to nudge a re-render (the dirty texel buffer also drives an upload on next frame).

    Parameters

    Returns boolean

setMeshAttribs

setMeshClippable

setMeshCulled

setMeshMatrix

setMeshRenderPass

setMeshViewAttribs

  • setMeshViewAttribs(
        meshHandle: GPUMemoryMeshHandle,
        viewIndex: number,
        params: {
            clippable?: boolean;
            color?: Vec3;
            opacity?: number;
            pickable?: boolean;
        },
    ): void

    Sets per-view attributes for a mesh.

    Parameters

    • meshHandle: GPUMemoryMeshHandle

      Mesh handle returned by addMesh.

    • viewIndex: number

      Target view index.

    • params: { clippable?: boolean; color?: Vec3; opacity?: number; pickable?: boolean }

      Per-view attributes.

      • Optionalclippable?: boolean

        Whether the mesh participates in clipping.

      • Optionalcolor?: Vec3

        RGB color encoded as bytes 0..255 (packed on upload).

      • Optionalopacity?: number

        Opacity in range 0..1.

      • Optionalpickable?: boolean

        Whether the mesh can be picked.

    Returns void

    Throws

    SDKInternalException If the mesh handle references an invalid batch.

setMeshVisible

setViewPickMatrix

updateSceneTexture

  • updateSceneTexture(
        sceneTexture: { id: string; image?: any; imageData?: any },
    ): boolean

    Walks every batch and re-uploads the SceneTexture's pixels into any atlas that holds it. Returns true if at least one atlas was refreshed.

    Wired to the Scene.events.onSceneTextureImageDataChanged flow — lets callers (e.g. the heat-map brush) mutate SceneTexture.imageData in place and have the GPU side stay in sync without a finalize/rebuild cycle.

    Parameters

    • sceneTexture: { id: string; image?: any; imageData?: any }

    Returns boolean

uploadChanges

webglContextRestored

Settings

Member Visibility

On This Page

Tiled Coordinate System, RTC (Relative To Center), and GPU Matrix Textures
Constructors
Properties
Accessors
Methods