Android camera app that applies a real-time tilt-shift (miniature/diorama) blur effect to the camera preview and to imported gallery images. Built with Kotlin, Jetpack Compose, CameraX, and OpenGL ES 2.0.
## What it does
- Live camera preview with GPU-accelerated tilt-shift blur via GLSL fragment shader
- Gallery import with CPU-based preview that updates in real time as you adjust parameters
- Supports both **linear** (band) and **radial** (elliptical) blur modes
- Gesture controls: drag to position, pinch to resize, two-finger rotate
- Slider panel for precise control of blur, falloff, size, angle, aspect ratio
- Multi-lens support on devices with multiple back cameras
LocationProvider.kt # FusedLocationProvider flow (accepts coarse or fine)
OrientationDetector.kt # Device rotation for EXIF
HapticFeedback.kt # Null-safe vibration wrapper
```
### Rendering pipeline
- **Camera preview**: OpenGL ES 2.0 via `GLSurfaceView` + `TiltShiftRenderer`. Camera frames arrive as `GL_TEXTURE_EXTERNAL_OES` from a `SurfaceTexture`. The fragment shader (`tiltshift_fragment.glsl`) applies blur per-fragment using precomputed `uCosAngle`/`uSinAngle` uniforms and an unrolled 9-tap Gaussian kernel.
- **Gallery preview**: CPU-based. A 1024px-max downscaled source is kept in `galleryPreviewSource`. `CameraViewModel.startPreviewLoop()` uses `collectLatest` on blur params (with 80ms debounce) to reactively recompute the preview via `ImageCaptureHandler.applyTiltShiftPreview()`.
- **Final save**: Full-resolution CPU pipeline — stack blur at 1/4 scale, gradient mask at 1/4 scale with bilinear upscale, per-pixel compositing. Camera captures save both original + processed; gallery imports save only the processed version (original already on device).
**IMPORTANT:** Always run `./bump-version.sh [major|minor|patch]` before `assembleRelease`. The version is tracked in `version.properties` and read by `build.gradle.kts`. Commit the bumped `version.properties` before or with the release.
Signing config is loaded from `local.properties` (not committed).
## Key design decisions and patterns
### Bitmap lifecycle (important!)
Bitmaps emitted to `StateFlow`s are **never eagerly recycled** immediately after replacement. Compose may still be drawing the old bitmap in the current frame. Instead:
- A `pendingRecyclePreview` / `pendingRecycleThumbnail` field holds the bitmap from the *previous* update
- On the *next* update, the pending bitmap is recycled (Compose has had a full frame to finish)
- Final cleanup happens in `cancelGalleryPreview()` (which `join()`s the preview job first) and `onCleared()`
### Thread safety
-`galleryPreviewSource` is `@Volatile` (accessed from Main thread, IO dispatcher, and cancel path)
-`TiltShiftRenderer.currentTexCoords` is `@Volatile` (written by UI thread, read by GL thread)
-`cancelGalleryPreview()` cancels + `join()`s the preview job before recycling the source bitmap, because `applyTiltShiftEffect` is a long CPU loop with no suspension points
- GL resources are released via `glSurfaceView.queueEvent {}` (must run on GL thread)
-`CameraManager.captureExecutor` is shut down in `release()` to prevent thread leaks
### Error handling
-`bitmap.compress()` return value is checked; failure reported to user
-`loadBitmapFromUri()` logs all null-return paths (stream open, dimensions, decode)
- Error/success dismiss indicators use cancellable `Job` tracking to prevent race conditions
-`writeExifToUri()` returns boolean and logs at ERROR level on failure
### Orientation policy (do not change without asking)
- Activity is `screenOrientation="portrait"` in the manifest. The GL surface and Compose layout therefore never rotate.
- The camera passthrough uses a fixed 90° texcoord rotation (`texCoordsBack`/`texCoordsFront`). There is no `setTargetRotation`/`setDisplayRotation`/`getTransformMatrix`-based rotation tracking — past attempts (v1.1.6 through v1.1.13) all introduced subtle bugs and were reverted.
- The camera image lives in the device's portrait frame and visually follows the phone as it tilts. Per-orientation correctness comes from the EXIF orientation tag written at capture (`OrientationDetector.degreesToExifOrientation(rotationToDegrees(deviceRotation), isFrontCamera)`), not from rotating the bitmap.
-`OrientationEventListener` (`viewModel.currentRotation`) is for EXIF only. It is **not** the same as `Display.rotation`: it fires at the 45° tilt threshold while the activity rotates later, so it must not drive anything that has to stay in sync with the GL surface.
-`SurfaceTexture.getTransformMatrix()` with a custom `SurfaceProvider` does not change on `Preview.targetRotation` updates; rebinding doesn't reliably help either. Don't go down that road again.
### Local Android testing
- AVD: `tilfluktsrom` (Pixel 6, API 35, Google APIs) at `~/.android/avd/`. Boot with `emulator -avd tilfluktsrom -no-snapshot-save -gpu swiftshader_indirect -no-audio`.
-`adb -s emulator-5554 emu rotate` cycles `ROTATION_0 → 3 → 2 → 1 → 0` (decrements by 90°), not the other way.
- The default virtual scene is too rotationally symmetric to verify which way is "up". For orientation testing, pass `-virtualscene-poster wall=/path/to/marker.png` and ensure the scene camera faces the wall, or just don't trust emulator screenshots as proof of correct orientation.
- Camera bitmaps captured at startup tend to look black for a few seconds while CameraX rebinds. Wait ≥10 s after `am start` before screenshotting.
- Do NOT use the `TodoWrite` tool in this project. Issue tracking and progress is managed with **dcat** as specified in `AGENTS.md` — see that file for the full workflow (`dcat prime --opinionated`, `dcat list --agent-only`, status transitions, closing rules, etc.).
