Orbis/README.md

Orbis

A modern Android application showcasing real-time GPU-accelerated graphics rendering using WebGPU. The app displays an animated, procedurally-generated sphere with interactive controls for visual customization.

Features

• WebGPU Rendering — GPU-accelerated graphics using the modern androidx.webgpu API
• Raymarching Shader — Real-time sphere tracing with signed distance functions (SDF)
• Procedural Animation — Noise-based surface displacement for organic, fluid-like motion
• Dynamic Lighting — Fresnel reflections, environment mapping, and Blinn-Phong specular
• Interactive Controls — Real-time adjustment of color (RGBA) and displacement amplitude
• Live FPS Counter — Performance monitoring overlay

Architecture

Orbis
├── app/                          # Main application entry point
│   ├── MainActivity.kt
│   ├── OrbisApplication.kt
│   └── di/AppModule.kt
│
├── feature/orb/                  # Orb rendering feature
│   ├── ui/
│   │   ├── OrbScreen.kt          # Main composable with controls
│   │   ├── OrbSurface.kt         # WebGPU surface integration
│   │   └── OrbViewModel.kt       # State management
│   ├── service/
│   │   └── OrbRenderServiceImpl.kt   # WebGPU renderer
│   ├── util/CubemapGenerator.kt  # Procedural environment map
│   └── assets/
│       ├── shaders/Orb.wgsl      # WGSL raymarching shader
│       └── textures/noise_map.png
│
└── core/ui/                      # Shared design system
    ├── Theme.kt                  # OrbisTheme
    ├── Color.kt                  # Color palette
    ├── Typography.kt             # Text styles
    └── components/               # Reusable UI components

Tech Stack

Category	Technology
Language	Kotlin 2.3.0
UI	Jetpack Compose (BOM 2026.01.00)
Graphics	WebGPU (androidx.webgpu)
Shaders	WGSL (WebGPU Shading Language)
DI	Koin 4.1.1
Min SDK	24
Target SDK	36

Getting Started

Prerequisites

• Android Studio Ladybug or later
• JDK 17
• Android device or emulator with API 24+

Build

# Clone the repository
git clone https://github.com/your-username/orbis.git
cd orbis

# Build debug APK
./gradlew assembleDebug

# Install on connected device
./gradlew installDebug

Run Tests

# Unit tests
./gradlew test

# Instrumented tests (requires device/emulator)
./gradlew connectedAndroidTest

Lint

./gradlew lint

Shader Pipeline

The rendering uses a raymarching approach with the following stages:

1. Ray Generation — Compute ray direction from screen UV coordinates
2. Sphere Tracing — March along ray using SDF, with early-out intersection test
3. Surface Displacement — Sample animated noise texture for organic deformation
4. Lighting — Combine diffuse, specular, Fresnel, and environment reflections
5. Background — Radial gradient fallback for missed rays

Performance Optimizations

• 60% resolution scaling
• 32 raymarching iterations (reduced for mobile)
• Single noise sample per ray
• Tetrahedral normal computation (4 samples vs 6)
• VSync synchronization via Choreographer

Configuration

Theme and component generation is handled by the Lumo plugin, configured in lumo.properties.