Document orientation policy and emulator-testing pitfalls in CLAUDE.md

Capture two things future sessions need to know up front: (1) the
activity is locked to portrait and the camera image stays in the
device frame on purpose — eight releases of orientation-tracking
attempts (v1.1.6 → v1.1.13) all got reverted, and per-orientation
correctness now lives in the EXIF tag rather than the GL pipeline; (2)
the Pixel 6 emulator's default virtual scene is too symmetric to
verify rotation visually, `emu rotate` decrements rather than
increments, and there is a startup window where camera bitmaps look
black.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -86,6 +86,21 @@ Bitmaps emitted to `StateFlow`s are **never eagerly recycled** immediately after
 - 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.
+
 ## Permissions
 
 | Permission | Purpose | Notes |

app/src/main/AndroidManifest.xml

@@ -31,7 +31,7 @@
         <activity
             android:name=".MainActivity"
             android:exported="true"
-            android:screenOrientation="fullSensor"
+            android:screenOrientation="portrait"
             android:configChanges="orientation|screenSize|screenLayout|keyboardHidden"
             android:windowSoftInputMode="adjustNothing"
             android:theme="@style/Theme.TiltShiftCamera">

app/src/main/java/no/naiv/tiltshift/camera/ImageCaptureHandler.kt

@@ -24,6 +24,7 @@ import kotlin.coroutines.resume
 import kotlin.math.cos
 import kotlin.math.sin
 import kotlin.math.sqrt
+import no.naiv.tiltshift.util.OrientationDetector
 
 /**
  * Handles capturing photos with the tilt-shift effect applied.
@@ -121,10 +122,19 @@ class ImageCaptureHandler(
                 var thumbnail: Bitmap? = null
                 try {
                     thumbnail = createThumbnail(captureResult.processed)
+                    // Camera bitmap is in the device's portrait frame (CameraX
+                    // rotated the sensor 90° because the activity is locked to
+                    // portrait). Tag the EXIF with the user's physical tilt
+                    // when they pressed the shutter so viewers display the
+                    // photo right-side-up regardless of how the phone was held.
+                    val exifOrientation = OrientationDetector.degreesToExifOrientation(
+                        OrientationDetector.rotationToDegrees(deviceRotation),
+                        isFrontCamera
+                    )
                     val result = photoSaver.saveBitmapPair(
                         original = captureResult.original,
                         processed = captureResult.processed,
-                        orientation = ExifInterface.ORIENTATION_NORMAL,
+                        orientation = exifOrientation,
                         location = location
                     )
                     if (result is SaveResult.Success) {

app/src/main/java/no/naiv/tiltshift/effect/TiltShiftRenderer.kt

@@ -6,7 +6,6 @@ import android.opengl.GLES11Ext
 import android.opengl.GLES20
 import android.opengl.GLSurfaceView
 import android.util.Log
-import android.view.Surface
 import java.nio.ByteBuffer
 import java.nio.ByteOrder
 import java.nio.FloatBuffer
@@ -70,32 +69,26 @@ class TiltShiftRenderer(
     @Volatile
     private var vertexBufferDirty: Boolean = false
 
-    // Texture coordinates for the back camera, indexed by Surface.ROTATION_*.
+    // Texture coordinates rotated 90° for portrait mode (back camera)
-    // The base orientation (index 0) applies the 90° CCW rotation that maps
+    // (Camera sensors are landscape-oriented, we rotate to portrait)
-    // the landscape sensor frame to a portrait display. Indices 1/2/3 layer
+    private val texCoordsBack = floatArrayOf(
-    // additional CCW rotations on top so the activity's rotation is
+        1f, 1f,  // Bottom left of screen  -> bottom right of texture
-    // compensated and world-up stays at clip-space-top.
+        1f, 0f,  // Bottom right of screen -> top right of texture
-    private val texCoordsBackByRotation = arrayOf(
+        0f, 1f,  // Top left of screen     -> bottom left of texture
-        floatArrayOf(1f, 1f, 1f, 0f, 0f, 1f, 0f, 0f), // ROTATION_0
+        0f, 0f   // Top right of screen    -> top left of texture
-        floatArrayOf(1f, 0f, 0f, 0f, 1f, 1f, 0f, 1f), // ROTATION_90
-        floatArrayOf(0f, 0f, 0f, 1f, 1f, 0f, 1f, 1f), // ROTATION_180
-        floatArrayOf(0f, 1f, 1f, 1f, 0f, 0f, 1f, 0f)  // ROTATION_270
     )
 
-    // Front camera variants: same as back, but horizontally mirrored
+    // Texture coordinates for front camera (mirrored + rotated)
-    // for the natural selfie view.
+    // Front camera needs horizontal mirror for natural selfie view
-    private val texCoordsFrontByRotation = arrayOf(
+    private val texCoordsFront = floatArrayOf(
-        floatArrayOf(0f, 1f, 0f, 0f, 1f, 1f, 1f, 0f), // ROTATION_0
+        0f, 1f,  // Bottom left of screen
-        floatArrayOf(0f, 0f, 1f, 0f, 0f, 1f, 1f, 1f), // ROTATION_90
+        0f, 0f,  // Bottom right of screen
-        floatArrayOf(1f, 0f, 1f, 1f, 0f, 0f, 0f, 1f), // ROTATION_180
+        1f, 1f,  // Top left of screen
-        floatArrayOf(1f, 1f, 0f, 1f, 1f, 0f, 0f, 0f)  // ROTATION_270
+        1f, 0f   // Top right of screen
     )
 
     @Volatile
-    private var displayRotation: Int = Surface.ROTATION_0
+    private var currentTexCoords = texCoordsBack
-
-    @Volatile
-    private var currentTexCoords = texCoordsBackByRotation[Surface.ROTATION_0]
 
     @Volatile
     private var updateTexCoordBuffer = false
@@ -212,7 +205,8 @@ class TiltShiftRenderer(
     fun setFrontCamera(front: Boolean) {
         if (isFrontCamera != front) {
             isFrontCamera = front
-            refreshTexCoords()
+            currentTexCoords = if (front) texCoordsFront else texCoordsBack
+            updateTexCoordBuffer = true
         }
     }
 
@@ -224,27 +218,6 @@ class TiltShiftRenderer(
         }
     }
 
-    /**
-     * Updates the active display rotation. The texture-coordinate buffer is
-     * rebuilt so the camera image stays world-aligned as the activity rotates
-     * with the device under screenOrientation="fullSensor", and the
-     * crop-to-fill math picks the correct effective aspect ratio.
-     */
-    fun setDisplayRotation(rotation: Int) {
-        if (displayRotation != rotation) {
-            displayRotation = rotation
-            refreshTexCoords()
-            vertexBufferDirty = true
-        }
-    }
-
-    private fun refreshTexCoords() {
-        val table = if (isFrontCamera) texCoordsFrontByRotation else texCoordsBackByRotation
-        val idx = displayRotation.coerceIn(0, table.size - 1)
-        currentTexCoords = table[idx]
-        updateTexCoordBuffer = true
-    }
-
     fun release() {
         shader.release()
         surfaceTexture?.release()
@@ -281,22 +254,16 @@ class TiltShiftRenderer(
     /**
      * Recomputes camera vertex positions to achieve crop-to-fill.
      *
-     * The camera sensor is landscape; after the orientation-dependent texcoord
+     * The camera sensor is landscape; after the 90° rotation applied via texture coordinates,
-     * rotation, the effective dimensions seen on screen are either swapped
+     * the effective portrait dimensions are (cameraHeight × cameraWidth). We scale the vertex
-     * (portrait orientations) or kept (landscape orientations). We scale the
+     * quad so the camera frame fills the surface without stretching — the GPU clips the overflow.
-     * vertex quad so the camera frame fills the surface without stretching —
-     * the GPU clips the overflow.
      */
     private fun recomputeVertices() {
         var scaleX = 1f
         var scaleY = 1f
 
         if (cameraWidth > 0 && cameraHeight > 0 && surfaceWidth > 0 && surfaceHeight > 0) {
-            val isPortrait = displayRotation == Surface.ROTATION_0 ||
+            val cameraRatio = cameraHeight.toFloat() / cameraWidth
-                displayRotation == Surface.ROTATION_180
-            val effectiveW = if (isPortrait) cameraHeight else cameraWidth
-            val effectiveH = if (isPortrait) cameraWidth else cameraHeight
-            val cameraRatio = effectiveW.toFloat() / effectiveH
             val screenRatio = surfaceWidth.toFloat() / surfaceHeight
 
             if (cameraRatio > screenRatio) {

app/src/main/java/no/naiv/tiltshift/ui/CameraScreen.kt

@@ -164,14 +164,6 @@ fun CameraScreen(
         }
     }
 
-    // Forward device rotation to renderer so the camera image stays
-    // world-aligned as the activity rotates with the device.
-    val currentRotation by viewModel.currentRotation.collectAsState()
-    LaunchedEffect(currentRotation, renderer) {
-        renderer?.setDisplayRotation(currentRotation)
-        glSurfaceView?.requestRender()
-    }
-
     // Start camera when surface texture is available
     LaunchedEffect(surfaceTexture) {
         surfaceTexture?.let {

version.properties

@@ -1,4 +1,4 @@
 versionMajor=1
 versionMinor=1
-versionPatch=12
+versionPatch=15
-versionCode=14
+versionCode=17