# 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.

<p align="center">
  <video src="media/orbis.mp4" width="300" />
</p>

## 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

```bash
# 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

```bash
# Unit tests
./gradlew test

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

### Lint

```bash
./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`.