Spatial Module Reference: Roles and Responsibilities

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danielitoCode/Spatial/llms.txt

Use this file to discover all available pages before exploring further.

// build.gradle.kts (app module)
dependencies {
    implementation("com.elitec:spatial-compose:<version>")
    implementation("com.elitec:spatial-compose-runtime-adapter:<version>")
    implementation("com.elitec:spatial-units:<version>")
}

​

spatial-compose

• Scene composable — Android view hosting, render-host lifecycle, gesture modifier wiring, scene graph collection, and frame submission
• Element.Cube, Element.Sphere, Element.Plane — declarative primitive element composables
• Modifier3D — declarative 3D transform DSL (.size(), .position(), .rotateY(), etc.)
• CameraState — @Stable Compose state holder for yaw, pitch, and zoom, backed by mutableStateOf
• rememberCameraState — Compose remember-style factory for CameraState
• rememberSceneGraph — internal scene graph collection using CompositionLocalProvider
• SceneNode — internal @Immutable data class pairing a PrimitiveShape with a Modifier3D
• Scene3D.kt root-package facade — re-exports all stable symbols as typealias and thin delegation

​

spatial-compose-runtime-adapter

• DefaultSceneRenderHostFactory — object implementing SceneRenderHostFactory; the single value you pass to Scene(renderHostFactory = ...) in almost every app
• SpatialRuntimeSceneRenderHost — concrete SceneRenderHost that owns a SpatialGlRenderTarget, a SpatialCamera, and a SpatialRuntime
• Wires ChoreographerFrameScheduler for vsync-aligned frame requests
• Manages render host lifecycle: onInitialize() at construction, dispose() on AndroidView.onRelease
• Forwards updateScene(nodes), updateCamera(snapshot), and requestFrame() calls to SpatialRuntime

​

spatial-runtime

• SpatialRuntime — SpatialRenderLoopContract implementation; owns RenderBackend, FrameScheduler, and CameraRuntimeContract references
• requestFrame(nodes, cameraSnapshot) — schedules a vsync-aligned frame callback via FrameScheduler; on callback, calls renderFrame(frameTimeNanos, nodes, cameraSnapshot) which syncs the camera snapshot and calls RenderBackend.render(RenderFrame(...))
• onOrbitGesture(OrbitGestureDelta) — translates gesture deltas into CameraDelta and applies them through the camera runtime
• onPinchGesture(PinchZoomDelta) — translates pinch scale deltas into zoom CameraDelta
• onInitialize() / onShutdown() — lifecycle management for the render loop
• Keeps rendering and camera state synchronized across threads without exposing GL details to callers

​

spatial-units

• Meter value type and .meters extension property
• Centimeter value type and .cm extension property
• Angle value type and .deg extension property (converting to radians internally)
• Unit conversion utilities for cross-unit arithmetic
• Enforces spatial consistency: Modifier3D.size(2f.meters) cannot accidentally receive a raw degree value

// Correct — typed units prevent unit confusion
Modifier3D.Default
    .size(2f.meters)
    .position(0f.meters, 0f.meters, (-5f).meters)

val cameraState = rememberCameraState(
    yaw = 20f.deg,
    pitch = (-12f).deg,
    zoom = 1.25f,
)

​

spatial-core

• RenderableNode — processed scene node ready for the renderer; carries meshId, modelMatrix (FloatArray(16)), and MaterialData
• MaterialData — flat-color RGBA contract (r, g, b, a floats)
• LightData — directional light metadata (direction, intensity, color); Core #1 does not evaluate lighting in shaders — this type is contract-only
• CameraSnapshot — immutable value capturing yaw, pitch, zoom, version, and CameraUpdateSource for thread-safe cross-layer transfer
• SpatialRenderLoopContract — platform-agnostic render loop interface (onInitialize, onFrame, onShutdown)
• FrameSnapshot — carries frameTimeNanos for timing-accurate frame callbacks

​

spatial-camera

• SpatialCamera — CameraRuntimeContract implementation; stateful orbit camera with pitch clamping and zoom bounds
• CameraRuntimeContract — interface defining applyDelta, orbitTo, zoomTo, jumpTo, animateTo, syncSnapshot, and snapshot
• CameraDelta — value type for incremental yaw, pitch, and zoom-scale changes
• GestureMotionPolicy — controls whether deltas are applied raw or through damping/inertia
• CameraAnimationSpec — Instant vs Tween(durationMs, easing) animation policies
• Orbit, pan, zoom, damping, inertia, and smooth cinematic transitions

​

spatial-motion

• MotionSpec — Adaptive, Quick, Deliberate, Instant motion profiles exposed in the public API
• resolveCameraMotionPlan — computes an appropriate duration and easing curve given start state, target state, and a MotionSpec; uses angular distance and zoom delta to scale duration adaptively
• Animation timeline primitives: interpolation, spring systems, and easing functions
• toCameraMotionProfile() — converts a public MotionSpec to an internal CameraMotionProfile used by the camera runtime

​

spatial-gesture

• Multi-touch recognition and pointer tracking
• Orbit gesture detection — translates finger drag delta into OrbitGestureDelta(deltaYaw, deltaPitch)
• Pinch-zoom detection — translates two-finger spread/pinch into PinchZoomDelta(scaleDelta)
• Velocity tracking and gesture smoothing to reduce jitter
• MotionEvent handling and event delegation

​

spatial-renderer

• SpatialGlRenderer — GLSurfaceView.Renderer implementation; compiles GLSL shaders, manages vertex and index buffer objects, resolves mesh IDs, and issues glDrawElements / glDrawArrays per RenderableNode
• SpatialGlRenderTarget — owns the GLSurfaceView, creates and configures the renderer, and exposes the View for embedding in AndroidView
• PrimitiveMeshRegistry — maps string mesh IDs ("cube", "sphere", "plane") to MeshData; buffers are uploaded to GPU on onSurfaceCreated
• ChoreographerFrameScheduler — schedules frame callbacks aligned to the display vsync via Choreographer.postFrameCallback
• Vertex shader: MVP transform (uProjectionMatrix * uViewMatrix * uModelMatrix * aPosition)
• Fragment shader: flat-color output (fragColor = uColor) — no lighting evaluation in Core #1
• orbitDistanceForVisualZoom — converts visual zoom magnitude to orbital camera distance (baseDistance / zoom)

​

spatial-scene

• Node hierarchy representation
• Transform propagation through parent-child relationships
• Scene graph traversal algorithms
• Visibility management per node
• Dirty flag tracking to avoid redundant transform recalculation
• Parent-child relationship management

​

spatial-geometry

• Cube mesh generation (8 vertices, 12 triangles, indexed)
• Sphere mesh generation (UV sphere with configurable segments)
• Plane mesh generation (quad with UV coordinates)
• Cylinder mesh generation
• Normal vector calculation per mesh
• UV coordinate generation for future texture support
• MeshData — carries vertices: FloatArray, indices: IntArray, and drawMode

​

spatial-material

• Flat-color material definition for Core #1 — color passed directly to the fragment shader as uColor
• MaterialData production for RenderableNode construction
• Material binding contracts for the renderer pipeline
• Lighting property metadata (shape, direction, color, intensity) — active light evaluation is outside Core #1 scope
• Foundation interfaces for future texture materials and shader metadata

​

spatial-light

• LightData contract (defined in spatial-core) — directional light direction, intensity, and RGB color
• Light helper factories for creating directional light metadata instances
• Establishes the interface shape that future renderer backends will implement for real shaded lighting

​

spatial-math

• Vec2, Vec3, Vec4 — 2D, 3D, and 4D vector types with arithmetic operators
• Quaternion — unit quaternion for rotation representation and interpolation (SLERP)
• Matrix4 — 4×4 transformation matrix with multiplication, inversion, and transpose
• Projection math utilities (perspective, orthographic)