depthlift 0.2.0

Convert any 2D image into a live 3D parallax scene with on-device depth estimation. Inspired by iOS depth effects.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.2.0 — 2026-04-29

Added

• IOSStyleGyroController — Premium iPhone-like gyroscope motion engine with:
  • Ticker-based frame updates (not direct stream updates) for jitter-free 60 FPS
  • lerpDouble smoothing with configurable factor (default 0.05)
  • Decay-based drift prevention (returns to centre naturally)
  • Configurable sensitivity, smoothing, maxOffset, and decay
  • Factory constructors: .iosNatural(), .cinematic(), .intense()
  • pause() / resume() for app lifecycle management
• DepthPreset.iosNatural — New preset matching iPhone wallpaper depth feel
• 3-tier input fallback — Gyroscope → Pointer drag → Float animation (automatic)
• PointerController — Touch/mouse drag fallback with low-pass smoothing
• FloatAnimationController — Idle Lissajous breathing animation fallback
• DepthLiftInputManager — Orchestrates all three input sources seamlessly
• InputMode enum — gyroscope, pointer, float (exported for consumer use)

Fixed

• Critical: Invisible rendering on Android — The render loop was running on a separate Thread while the EGL context was bound to the glHandler thread. EGL contexts are thread-local, so all GL draw calls silently produced no output. Fixed by using Handler.postDelayed to keep the render loop on the same thread as the EGL context.
• EGL surface compatibility — Added EGL_RECORDABLE_ANDROID flag for Flutter SurfaceTexture interop on Samsung and other chipsets.
• Gyroscope crash on devices without sensor — Added isGyroAvailable guard on iOS (CoreMotion) and null sensor check on Android (SensorManager).
• Unhandled exception from gyroscopeEventStream() — Wrapped in try/catch with 500ms timeout to detect silent failures on emulators.

Changed

• Android rendering architecture — DepthRenderer now accepts the GL Handler and uses Handler.postDelayed for the render loop instead of spawning a raw Thread.
• EGL configuration — Upgraded to EGLExt.EGL_OPENGL_ES3_BIT_KHR with RGBA8888 and automatic fallback.
• AndroidManifest.xml — Sensor feature declared with android:required="false" to avoid Play Store rejection on devices without gyroscope.
• iOS plugin — Added setDepthMap handler, proper cleanup of gyro on detachFromEngine.

Platform requirements

• Android: minSdkVersion 24, NDK 27.0.12077973
• iOS: deployment target 14.0
• Dart SDK: >=3.3.0 <4.0.0
• Flutter SDK: >=3.19.0

0.1.0 — 2026-04-23

Added

• DepthLiftView — Main widget that renders any 2D image as a live 3D parallax scene.
• DepthLiftController — Programmatic control for playback, effect switching, and export.
• DepthLiftOptions — Immutable configuration with copyWith, toMap, equality, and lowPowerMode.
• 4 visual effects — Parallax, Bokeh (depth-of-field), Float (Lissajous breathing), Zoom (Ken Burns).
• Depth Anything v2 Small on-device inference:
  • Android: TFLite via tflite_flutter, input [1, 3, 518, 518].
  • iOS: Core ML via .mlpackage, same tensor layout.
• Remote depth API fallback — POST base64 image to configurable HTTPS endpoint.
• Depth post-processing — normalisation, 5×5 boundary median filter, bilinear upsampling.
• 3D mesh construction — configurable 16–256 grid with foreground 1.5× Z amplification.
• Real-time rendering:
  • Android: OpenGL ES 3.0 surface → Flutter ExternalTexture.
  • iOS: Metal → CVPixelBuffer registered as FlutterTexture.
• Gyroscope tilt via sensors_plus with pointer fallback.
• Bokeh shader — 9-tap separable Gaussian blur driven by depth distance from focal plane.
• Frame export — exportFrame() returns PNG bytes.
• Video export — exportVideo() placeholder (single-frame for now).
• Error handling — DepthLiftModelException, onError callback, flat-image fallback.
• Low-power mode — halves mesh resolution and disables bokeh.
• Unit tests — options, enums, controller state stream, mesh vertex math.
• Widget tests — loading widget visibility, default construction.
• Full documentation — dartdoc on all public APIs, comprehensive README.

Platform requirements

• Android: minSdkVersion 24
• iOS: deployment target 14.0
• Dart SDK: >=3.3.0 <4.0.0
• Flutter SDK: >=3.19.0