@rafaelaugusto/jolt 0.1.0-beta.6 → 0.1.0-beta.8

package/platforms/android/java/org/rafaelaugusto/jolt/PhotoZoom.java

@@ -0,0 +1,250 @@
+package org.rafaelaugusto.jolt;
+
+import android.animation.ValueAnimator;
+import android.graphics.RectF;
+import android.view.*;
+import android.widget.ImageView;
+
+/** Focal zoom, bounds, pan and dismissal; no pointer/frame callback crosses to JS. */
+public final class PhotoZoom implements View.OnTouchListener, View.OnLayoutChangeListener {
+    public interface Listener {
+        void onDismiss(float x,float y,float scale,float velocity,float progress);
+        void onSettled(float x,float y,float scale);
+    }
+    private final ImageView image;
+    private final View viewport,backdrop,chrome;
+    private final Listener listener;
+    private final View.OnTouchListener previousTouch,previousImageTouch;
+    private final ScaleGestureDetector pinch;
+    private final GestureDetector taps;
+    private final float minimum,maximum,doubleTap,density,slop;
+    private final float bitmapWidth,bitmapHeight;
+    private final boolean dismiss,originalClickable,originalImageClickable,originalClip,originalClipPadding;
+    private final float originalScaleX,originalScaleY,originalX,originalY,backdropAlpha,chromeAlpha;
+    private final RectF content=new RectF();
+    private float anchorX,anchorY,width,height,x,y,scale,progress;
+    private float lastX,lastY,downX,downY,lastFocusX,lastFocusY,vx,vy;
+    private float rawPanX,rawPanY,pinchFloor;
+    private int pointer=-1,mode; // 0 undecided, 1 pan, 2 dismiss, 3 handed to parent
+    private boolean disposed,pending,reduced,active=true;
+    private VelocityTracker velocity;
+    private ValueAnimator animation;
+
+    public PhotoZoom(ImageView image,View viewport,float bitmapWidth,float bitmapHeight,float minimum,float maximum,float doubleTap,
+                     boolean dismiss,boolean reduced,View backdrop,View chrome,
+                     View.OnTouchListener previousTouch,View.OnTouchListener previousImageTouch,Listener listener) {
+        this.image=image;this.viewport=viewport;this.minimum=minimum;this.maximum=maximum;
+        this.bitmapWidth=bitmapWidth;this.bitmapHeight=bitmapHeight;
+        this.doubleTap=doubleTap;this.dismiss=dismiss;this.reduced=reduced;
+        this.backdrop=backdrop;this.chrome=chrome;this.previousTouch=previousTouch;this.listener=listener;
+        this.previousImageTouch=previousImageTouch;
+        density=image.getResources().getDisplayMetrics().density;
+        slop=ViewConfiguration.get(image.getContext()).getScaledTouchSlop();
+        originalScaleX=image.getScaleX();originalScaleY=image.getScaleY();
+        originalX=image.getTranslationX();originalY=image.getTranslationY();
+        originalClickable=viewport.isClickable();
+        originalImageClickable=image.isClickable();
+        originalClip=!(viewport instanceof ViewGroup)||((ViewGroup)viewport).getClipChildren();
+        originalClipPadding=!(viewport instanceof ViewGroup)||((ViewGroup)viewport).getClipToPadding();
+        backdropAlpha=backdrop==null?1:backdrop.getAlpha();chromeAlpha=chrome==null?1:chrome.getAlpha();
+        scale=minimum;
+        pinch=new ScaleGestureDetector(image.getContext(),new ScaleGestureDetector.SimpleOnScaleGestureListener(){
+            @Override public boolean onScaleBegin(ScaleGestureDetector detector){
+                if(pending || disposed) return false;
+                cancelAnimation();mode=1;pinchFloor=Math.min(minimum,scale);
+                lastFocusX=detector.getFocusX();lastFocusY=detector.getFocusY();
+                disallow(true);return true;
+            }
+            @Override public boolean onScale(ScaleGestureDetector detector){
+                float next=clamp(scale*detector.getScaleFactor(),pinchFloor,maximum);
+                float fx=detector.getFocusX(),fy=detector.getFocusY();
+                x=fx-anchorX-(lastFocusX-anchorX-x)*next/scale;
+                y=fy-anchorY-(lastFocusY-anchorY-y)*next/scale;
+                scale=next;lastFocusX=fx;lastFocusY=fy;
+                progress=clamp((minimum-scale)/(minimum*.15f),0,1);
+                rebasePan();
+                apply();return true;
+            }
+        });
+        taps=new GestureDetector(image.getContext(),new GestureDetector.SimpleOnGestureListener(){
+            @Override public boolean onDown(MotionEvent e){return true;}
+            @Override public boolean onDoubleTap(MotionEvent e){
+                if(!pending) zoom(scale>minimum+.01f?minimum:Math.min(maximum,doubleTap),e.getX(),e.getY(),true);
+                return true;
+            }
+            @Override public boolean onSingleTapConfirmed(MotionEvent e){viewport.performClick();return true;}
+        });
+        viewport.setClickable(true);viewport.setOnTouchListener(this);
+        image.setClickable(true);image.setOnTouchListener((v,event)->{
+            MotionEvent local=MotionEvent.obtain(event);
+            local.transform(image.getMatrix());
+            local.offsetLocation(image.getLeft()-viewport.getScrollX(),image.getTop()-viewport.getScrollY());
+            boolean consumed=onTouch(viewport,local);local.recycle();return consumed;
+        });
+        if(viewport instanceof ViewGroup){((ViewGroup)viewport).setClipChildren(true);((ViewGroup)viewport).setClipToPadding(true);}
+        viewport.addOnLayoutChangeListener(this);image.addOnLayoutChangeListener(this);
+        measure();apply();
+    }
+    public float getX(){return x/density;}
+    public float getY(){return y/density;}
+    public float getScale(){return scale;}
+    public float getDismissProgress(){return progress;}
+    public boolean isDismissPending(){return pending;}
+    public void setReduced(boolean value){reduced=value;if(value){if(pending)reset(false);else settle(false);}}
+    public void setActive(boolean value){active=value;if(!value){cancelAnimation();endTouch();pending=false;settle(false);}}
+    public void zoom(float value,float focusX,float focusY,boolean animated){
+        if(disposed || pending) return;
+        cancelAnimation();
+        float next=clamp(value,minimum,maximum);
+        float tx=focusX-anchorX-(focusX-anchorX-x)*next/scale;
+        float ty=focusY-anchorY-(focusY-anchorY-y)*next/scale;
+        float[] bounds=bounds(next);
+        spring(clamp(tx,bounds[0],bounds[1]),clamp(ty,bounds[2],bounds[3]),next,0,0,animated,false);
+    }
+    public void reset(boolean animated){
+        if(disposed)return;
+        pending=false;mode=0;float[] b=bounds(minimum);
+        spring(clamp(0,b[0],b[1]),clamp(0,b[2],b[3]),minimum,0,0,animated,false);
+    }
+    public void requestDismiss(){
+        if(disposed || pending || !dismiss)return;
+        // Programmatic close normalizes zoom before emitting one route intent.
+        float[] b=bounds(minimum);
+        spring(clamp(0,b[0],b[1]),clamp(0,b[2],b[3]),minimum,0,0,true,true);
+    }
+    public void stop(){
+        if(disposed)return;
+        disposed=true;cancelAnimation();endTouch();
+        viewport.setOnTouchListener(previousTouch);viewport.setClickable(originalClickable);
+        image.setOnTouchListener(previousImageTouch);image.setClickable(originalImageClickable);
+        if(viewport instanceof ViewGroup){((ViewGroup)viewport).setClipChildren(originalClip);((ViewGroup)viewport).setClipToPadding(originalClipPadding);}
+        viewport.removeOnLayoutChangeListener(this);image.removeOnLayoutChangeListener(this);
+        image.setScaleX(originalScaleX);image.setScaleY(originalScaleY);
+        image.setTranslationX(originalX);image.setTranslationY(originalY);
+        if(backdrop!=null)backdrop.setAlpha(backdropAlpha);if(chrome!=null)chrome.setAlpha(chromeAlpha);
+    }
+    private void measure(){
+        width=viewport.getWidth();height=viewport.getHeight();
+        float iw=image.getWidth(),ih=image.getHeight();
+        float left=image.getPaddingLeft(),top=image.getPaddingTop();
+        float cw=iw-left-image.getPaddingRight(),ch=ih-top-image.getPaddingBottom();
+        float dw=Math.max(1,bitmapWidth),dh=Math.max(1,bitmapHeight);
+        ImageView.ScaleType fit=image.getScaleType();
+        float factor=fit==ImageView.ScaleType.CENTER_CROP?Math.max(cw/dw,ch/dh):Math.min(cw/dw,ch/dh);
+        if(fit==ImageView.ScaleType.FIT_XY){dw=cw;dh=ch;}
+        else if(fit!=ImageView.ScaleType.CENTER && fit!=ImageView.ScaleType.MATRIX){dw*=factor;dh*=factor;}
+        anchorX=image.getLeft()+image.getPivotX()+originalX;
+        anchorY=image.getTop()+image.getPivotY()+originalY;
+        // ImageView clips the raster before its outer transform is applied.
+        float ox=left+(fit==ImageView.ScaleType.MATRIX?0:(cw-dw)/2),oy=top+(fit==ImageView.ScaleType.MATRIX?0:(ch-dh)/2);
+        content.set((Math.max(left,ox)-image.getPivotX())*originalScaleX,
+                    (Math.max(top,oy)-image.getPivotY())*originalScaleY,
+                    (Math.min(left+cw,ox+dw)-image.getPivotX())*originalScaleX,
+                    (Math.min(top+ch,oy+dh)-image.getPivotY())*originalScaleY);
+    }
+    private float[] bounds(float s){
+        float loX=width-anchorX-content.right*s,hiX=-anchorX-content.left*s;
+        float loY=height-anchorY-content.bottom*s,hiY=-anchorY-content.top*s;
+        if(loX>hiX)loX=hiX=(loX+hiX)/2;
+        if(loY>hiY)loY=hiY=(loY+hiY)/2;
+        return new float[]{loX,hiX,loY,hiY};
+    }
+    private void apply(){
+        image.setScaleX(originalScaleX*scale);image.setScaleY(originalScaleY*scale);
+        image.setTranslationX(originalX+x);image.setTranslationY(originalY+y);
+        if(backdrop!=null)backdrop.setAlpha(backdropAlpha*(1-progress));
+        if(chrome!=null)chrome.setAlpha(chromeAlpha*(1-progress));
+    }
+    private void settle(boolean animated){
+        if(disposed)return;
+        float s=clamp(scale,minimum,maximum),b[]=bounds(s);
+        float tx=clamp(x,b[0],b[1]),ty=clamp(y,b[2],b[3]);
+        if(mode==2){s=minimum;b=bounds(s);tx=clamp(0,b[0],b[1]);ty=clamp(0,b[2],b[3]);}
+        else {tx=clamp(tx+vx*.12f,b[0],b[1]);ty=clamp(ty+vy*.12f,b[2],b[3]);}
+        spring(tx,ty,s,vx,vy,animated,false);
+    }
+    private void cancelAnimation(){if(animation!=null){animation.cancel();animation=null;}}
+    private void spring(float tx,float ty,float targetScale,float velocityX,float velocityY,boolean animated,boolean close){
+        cancelAnimation();
+        final float sx=x,sy=y,ss=scale,sp=progress;
+        if(!animated || reduced){x=tx;y=ty;scale=targetScale;progress=0;apply();if(close)emitDismiss(0);else listener.onSettled(x/density,y/density,scale);return;}
+        animation=ValueAnimator.ofFloat(0,1);animation.setDuration(550);
+        animation.setInterpolator(new android.view.animation.LinearInterpolator());
+        animation.addUpdateListener(a->{
+            float fraction=(float)a.getAnimatedValue(),t=fraction*.55f;
+            float decay=(float)Math.exp(-16*t);
+            x=tx+((sx-tx)+(velocityX+16*(sx-tx))*t)*decay;
+            y=ty+((sy-ty)+(velocityY+16*(sy-ty))*t)*decay;
+            scale=targetScale+(ss-targetScale)*(1+16*t)*decay;
+            progress=sp*(1+16*t)*decay;
+            if(fraction>=1){x=tx;y=ty;scale=targetScale;progress=0;}
+            apply();
+            if(fraction>=1){animation=null;if(close)emitDismiss(0);else listener.onSettled(x/density,y/density,scale);}
+        });animation.start();
+    }
+    private void emitDismiss(float velocityY){
+        if(pending || disposed)return;
+        pending=true;listener.onDismiss(x/density,y/density,scale,velocityY/density,progress);
+    }
+    private void disallow(boolean value){if(viewport.getParent()!=null)viewport.getParent().requestDisallowInterceptTouchEvent(value);}
+    private void endTouch(){pointer=-1;if(velocity!=null){velocity.recycle();velocity=null;}disallow(false);}
+    @Override public boolean onTouch(View view,MotionEvent event){
+        if(disposed || !active || pending)return false;
+        int action=event.getActionMasked();
+        if(action==MotionEvent.ACTION_DOWN){
+            cancelAnimation();mode=0;vx=vy=0;
+            pointer=event.getPointerId(0);lastX=downX=event.getX();lastY=downY=event.getY();
+            rebasePan();
+            if(velocity!=null)velocity.recycle();velocity=VelocityTracker.obtain();disallow(true);
+        }
+        if(velocity!=null)velocity.addMovement(event);
+        pinch.onTouchEvent(event);taps.onTouchEvent(event);
+        int index=event.findPointerIndex(pointer);
+        if(action==MotionEvent.ACTION_MOVE && !pinch.isInProgress() && event.getPointerCount()==1 && index>=0){
+            float px=event.getX(index),py=event.getY(index),totalX=px-downX,totalY=py-downY;
+            if(mode==0 && Math.hypot(totalX,totalY)>slop){
+                if(scale<=minimum+.001f){
+                    if(dismiss && Math.abs(totalY)>Math.abs(totalX)*1.2f)mode=2;
+                    else {mode=3;disallow(false);return false;}
+                }else mode=1;
+            }
+            if(mode==1){
+                float[] b=bounds(scale);
+                rawPanX+=px-lastX;rawPanY+=py-lastY;
+                x=rubber(rawPanX,b[0],b[1],width);y=rubber(rawPanY,b[2],b[3],height);
+            }else if(mode==2){
+                x+= (px-lastX)*.4f;y+=py-lastY;
+                progress=clamp(Math.abs(y)/Math.max(height*.5f,1),0,1);
+                scale=minimum*(1-progress*.15f);
+            }
+            lastX=px;lastY=py;apply();
+        }
+        if(action==MotionEvent.ACTION_POINTER_UP){
+            int next=event.getActionIndex()==0?1:0;
+            if(next<event.getPointerCount()){pointer=event.getPointerId(next);lastX=downX=event.getX(next);lastY=downY=event.getY(next);rebasePan();}
+        }
+        if(action==MotionEvent.ACTION_UP || action==MotionEvent.ACTION_CANCEL){
+            if(velocity!=null){velocity.computeCurrentVelocity(1000);vx=velocity.getXVelocity(pointer);vy=velocity.getYVelocity(pointer);}
+            boolean commit=action==MotionEvent.ACTION_UP && mode==2 && (progress>.35f || (Math.abs(vy)>1000*density && y*vy>0));
+            boolean wasAnimation=animation!=null;
+            endTouch();
+            if(commit)emitDismiss(vy);
+            else if(mode!=3 && !wasAnimation)settle(true);
+        }
+        return mode!=3;
+    }
+    @Override public void onLayoutChange(View v,int l,int t,int r,int b,int ol,int ot,int or,int ob){
+        if(disposed || (l==ol&&t==ot&&r==or&&b==ob))return;
+        cancelAnimation();pending=false;measure();vx=vy=0;mode=0;settle(false);
+    }
+    private static float clamp(float v,float lo,float hi){return Math.max(lo,Math.min(hi,v));}
+    private void rebasePan(){float[] b=bounds(scale);rawPanX=unrubber(x,b[0],b[1],width);rawPanY=unrubber(y,b[2],b[3],height);}
+    private static float unrubber(float v,float lo,float hi,float dimension){
+        float edge=clamp(v,lo,hi),d=v-edge,size=Math.max(1,dimension);
+        return edge+d/(.55f*Math.max(.001f,1-Math.abs(d)/size));
+    }
+    private static float rubber(float value,float lo,float hi,float dimension){
+        float edge=clamp(value,lo,hi),d=value-edge;
+        return edge+Math.signum(d)*dimension*(1-1/(Math.abs(d)*.55f/Math.max(1,dimension)+1));
+    }
+}

package/platforms/android/proguard-rules.pro

@@ -11,3 +11,7 @@
 -keep class org.rafaelaugusto.jolt.TextReveal$* { *; }
 -keep class org.rafaelaugusto.jolt.NumberRoll { *; }
 -keep class org.rafaelaugusto.jolt.NumberRoll$* { *; }
+-keep class org.rafaelaugusto.jolt.ImageEffect { *; }
+-keep class org.rafaelaugusto.jolt.ImageEffect$* { *; }
+-keep class org.rafaelaugusto.jolt.PhotoZoom { *; }
+-keep class org.rafaelaugusto.jolt.PhotoZoom$* { *; }

package/platforms/ios/build.xcconfig

@@ -0,0 +1 @@
+OTHER_LDFLAGS = $(inherited) -framework Metal -framework MetalKit

package/platforms/ios/src/JoltImageEffect.h

@@ -0,0 +1,25 @@
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+@interface JoltImageEffect : NSObject
++ (nullable instancetype)createWithView:(UIImageView *)view
+                          destination:(nullable UIImage *)destination
+                                 mode:(NSInteger)mode
+                              originX:(double)x originY:(double)y
+                            amplitude:(double)amplitude radius:(double)radius
+                             duration:(double)duration seed:(double)seed
+                             listener:(void (^)(BOOL, double))listener;
+@property(nonatomic, readonly) double progress;
+@property(nonatomic, readonly) BOOL paused;
+@property(nonatomic, readonly) NSUInteger frames;
+@property(nonatomic, readonly) double longestFrame;
+@property(nonatomic, readonly) NSUInteger textureBytes;
+- (void)play:(double)endpoint;
+- (void)pause;
+- (void)resume;
+- (void)seek:(double)progress;
+- (void)finish:(double)endpoint;
+- (void)stop;
+- (void)stopPreservingImage;
+@end
+NS_ASSUME_NONNULL_END

package/platforms/ios/src/JoltImageEffect.mm

@@ -0,0 +1,242 @@
+#import "JoltImageEffect.h"
+#import <MetalKit/MetalKit.h>
+#import <simd/simd.h>
+
+static const char *JoltImageShader = R"METAL(
+#include <metal_stdlib>
+using namespace metal;
+struct Vertex {float4 position [[position]]; float2 uv;};
+struct Params {float2 size; float2 origin; float2 displacement; float progress; float amplitude; float radius; float seed; float mode;};
+vertex Vertex joltVertex(uint id [[vertex_id]]) {
+    float2 p[4]={float2(-1,-1),float2(1,-1),float2(-1,1),float2(1,1)};
+    float2 uv[4]={float2(0,1),float2(1,1),float2(0,0),float2(1,0)};
+    return {float4(p[id],0,1),uv[id]};
+}
+fragment float4 joltImage(Vertex in [[stage_in]], constant Params &u [[buffer(0)]],
+                         texture2d<float> source [[texture(0)]], texture2d<float> destination [[texture(1)]]) {
+    constexpr sampler s(coord::normalized,address::clamp_to_edge,filter::linear);
+    float2 p=in.uv*u.size,q=p;
+    if(u.mode<1.5) {
+        float2 v=p-u.origin; float d=length(v);
+        float edge=clamp(min(min(p.x,u.size.x-p.x),min(p.y,u.size.y-p.y))/max(u.amplitude*2.,1.),0.,1.);
+        if(u.mode<.5) {
+            float wave=d-u.progress*length(u.size);
+            float a=sin(wave/max(u.radius*.12,1.))*exp(-pow(wave/max(u.radius,1.),2.))*u.amplitude*sin(u.progress*3.14159265);
+            q-=v/max(d,1.)*a*edge;
+        } else q-=u.displacement*exp(-d*d/max(u.radius*u.radius,1.))*edge;
+        return source.sample(s,q/u.size);
+    }
+    if(u.progress<=0.) return source.sample(s,in.uv);
+    if(u.progress>=1.) return destination.sample(s,in.uv);
+    float n=fract(sin(dot(floor(p/3.),float2(12.9898,78.233))+u.seed)*43758.5453);
+    float a=smoothstep(n-.08,n+.08,u.progress*1.16-.08);
+    return mix(source.sample(s,in.uv),destination.sample(s,in.uv),a);
+}
+)METAL";
+
+typedef struct {
+    vector_float2 size, origin, displacement;
+    float progress, amplitude, radius, seed, mode;
+} JoltImageParams;
+
+@interface JoltImageEffect () <MTKViewDelegate, UIGestureRecognizerDelegate>
+@property(nonatomic, weak) UIImageView *image;
+@property(nonatomic, strong) UIImage *original;
+@property(nonatomic, strong) MTKView *surface;
+@property(nonatomic, strong) id<MTLCommandQueue> queue;
+@property(nonatomic, strong) id<MTLRenderPipelineState> pipeline;
+@property(nonatomic, strong) id<MTLTexture> sourceTexture, destinationTexture;
+@property(nonatomic, strong) UIPanGestureRecognizer *pan;
+@property(nonatomic, copy) void (^listener)(BOOL,double);
+@property(nonatomic) BOOL originalInteraction, disposed, playing, settling;
+@property(nonatomic, readwrite) BOOL paused;
+@property(nonatomic, readwrite) double progress;
+@property(nonatomic, readwrite) NSUInteger frames;
+@property(nonatomic, readwrite) double longestFrame;
+@property(nonatomic, readwrite) NSUInteger textureBytes;
+@property(nonatomic) double duration, goal, anchor, startProgress, remaining, previousFrame;
+@property(nonatomic) vector_float2 settleStart;
+@property(nonatomic) JoltImageParams params;
+@end
+
+@implementation JoltImageEffect
++ (instancetype)createWithView:(UIImageView *)view destination:(UIImage *)destination mode:(NSInteger)mode
+                       originX:(double)x originY:(double)y amplitude:(double)amplitude radius:(double)radius
+                      duration:(double)duration seed:(double)seed listener:(void (^)(BOOL,double))listener {
+    if(!view.image.CGImage || view.image.images.count || view.image.renderingMode==UIImageRenderingModeAlwaysTemplate || !view.window) return nil;
+    CGFloat scale=view.window.screen.scale;
+    NSUInteger w=(NSUInteger)ceil(view.bounds.size.width*scale),h=(NSUInteger)ceil(view.bounds.size.height*scale);
+    if(!w || !h || w*h>4194304 || (mode==2 && !destination.CGImage)) return nil;
+    id<MTLDevice> device=MTLCreateSystemDefaultDevice();
+    if(!device) return nil;
+    static id<MTLRenderPipelineState> cached;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+        NSError *error=nil;
+        id<MTLLibrary> library=[device newLibraryWithSource:[NSString stringWithUTF8String:JoltImageShader] options:nil error:&error];
+        MTLRenderPipelineDescriptor *descriptor=[MTLRenderPipelineDescriptor new];
+        descriptor.vertexFunction=[library newFunctionWithName:@"joltVertex"];
+        descriptor.fragmentFunction=[library newFunctionWithName:@"joltImage"];
+        descriptor.colorAttachments[0].pixelFormat=MTLPixelFormatBGRA8Unorm;
+        if(library) cached=[device newRenderPipelineStateWithDescriptor:descriptor error:&error];
+        if(error) NSLog(@"Jolt image shader unavailable: %@",error.localizedDescription);
+    });
+    if(!cached) return nil;
+    JoltImageEffect *effect=[JoltImageEffect new];
+    effect.image=view; effect.original=view.image; effect.originalInteraction=view.userInteractionEnabled;
+    effect.listener=listener; effect.pipeline=cached; effect.queue=[device newCommandQueue];
+    effect.duration=duration/1000.; effect.goal=1; effect.paused=YES;
+    effect.params=(JoltImageParams){ {(float)w,(float)h}, {(float)(x*scale),(float)(y*scale)}, {0,0}, 0,
+        (float)(amplitude*scale),(float)(radius*scale),(float)seed,(float)mode };
+    effect.sourceTexture=[effect texture:view.image device:device width:w height:h];
+    effect.destinationTexture=mode==2?[effect texture:destination device:device width:w height:h]:effect.sourceTexture;
+    if(!effect.sourceTexture || !effect.destinationTexture) return nil;
+    effect.textureBytes=w*h*4*(mode==2?2:1);
+    MTKView *surface=[[MTKView alloc] initWithFrame:view.bounds device:device];
+    surface.opaque=NO; surface.backgroundColor=UIColor.clearColor;
+    surface.clearColor=MTLClearColorMake(0,0,0,0);
+    surface.userInteractionEnabled=NO; surface.accessibilityElementsHidden=YES;
+    surface.colorPixelFormat=MTLPixelFormatBGRA8Unorm;
+    surface.autoResizeDrawable=NO; surface.drawableSize=CGSizeMake(w,h);
+    surface.preferredFramesPerSecond=MIN(120,view.window.screen.maximumFramesPerSecond);
+    surface.paused=YES; surface.enableSetNeedsDisplay=YES;
+    surface.delegate=effect; effect.surface=surface;
+    [view addSubview:surface];
+    // Draw the identity frame before suppressing the original raster.
+    [surface draw]; view.image=nil;
+    if(mode==1) {
+        effect.pan=[[UIPanGestureRecognizer alloc] initWithTarget:effect action:@selector(drag:)];
+        effect.pan.delegate=effect; effect.pan.cancelsTouchesInView=NO;
+        view.userInteractionEnabled=YES; [view addGestureRecognizer:effect.pan];
+    }
+    return effect;
+}
+- (id<MTLTexture>)texture:(UIImage *)image device:(id<MTLDevice>)device width:(NSUInteger)w height:(NSUInteger)h {
+    if(!image.CGImage) return nil;
+    NSMutableData *data=[NSMutableData dataWithLength:w*h*4];
+    CGColorSpaceRef space=CGColorSpaceCreateDeviceRGB();
+    CGContextRef context=CGBitmapContextCreate(data.mutableBytes,w,h,8,w*4,space,kCGImageAlphaPremultipliedLast|kCGBitmapByteOrder32Big);
+    CGColorSpaceRelease(space);
+    if(!context) return nil;
+    CGContextTranslateCTM(context,0,h); CGContextScaleCTM(context,1,-1);
+    CGFloat iw=image.size.width,ih=image.size.height;
+    UIViewContentMode mode=self.image.contentMode;
+    CGFloat factor=mode==UIViewContentModeScaleAspectFill?MAX(w/iw,h/ih):MIN(w/iw,h/ih);
+    BOOL unscaled=mode==UIViewContentModeCenter || mode==UIViewContentModeTopLeft;
+    CGFloat dw=mode==UIViewContentModeScaleToFill?w:unscaled?iw*self.image.window.screen.scale:iw*factor;
+    CGFloat dh=mode==UIViewContentModeScaleToFill?h:unscaled?ih*self.image.window.screen.scale:ih*factor;
+    CGFloat left=mode==UIViewContentModeTopLeft?0:(w-dw)/2,top=mode==UIViewContentModeTopLeft?0:(h-dh)/2;
+    UIGraphicsPushContext(context); [image drawInRect:CGRectMake(left,top,dw,dh)]; UIGraphicsPopContext();
+    CGContextRelease(context);
+    MTLTextureDescriptor *descriptor=[MTLTextureDescriptor texture2DDescriptorWithPixelFormat:MTLPixelFormatRGBA8Unorm width:w height:h mipmapped:NO];
+    descriptor.usage=MTLTextureUsageShaderRead;
+    id<MTLTexture> texture=[device newTextureWithDescriptor:descriptor];
+    [texture replaceRegion:MTLRegionMake2D(0,0,w,h) mipmapLevel:0 withBytes:data.bytes bytesPerRow:w*4];
+    return texture;
+}
+- (void)play:(double)endpoint {
+    if(self.disposed || self.params.mode==1) return;
+    self.goal=endpoint; self.startProgress=self.progress; self.remaining=MAX(.001,self.duration*fabs(endpoint-self.progress));
+    self.anchor=CACurrentMediaTime(); self.playing=YES; self.settling=NO; self.paused=NO;
+    self.previousFrame=0; self.surface.enableSetNeedsDisplay=NO; self.surface.paused=NO;
+}
+- (void)pause {
+    if(self.disposed) return;
+    [self advance:CACurrentMediaTime()]; self.paused=YES;
+    self.surface.paused=YES; self.surface.enableSetNeedsDisplay=YES;
+}
+- (void)resume {
+    if(self.disposed || !self.paused) return;
+    if(self.params.mode==1) {
+        self.paused=NO;
+        if(self.settling && self.playing) {
+            self.settleStart=self.params.displacement;self.anchor=CACurrentMediaTime();
+            self.remaining=MIN(.6,self.duration);self.previousFrame=0;
+            self.surface.enableSetNeedsDisplay=NO;self.surface.paused=NO;
+        }
+        return;
+    }
+    [self play:self.goal];
+}
+- (void)seek:(double)value {
+    if(self.disposed || self.params.mode==1) return;
+    BOOL hold=self.paused; self.progress=value;
+    JoltImageParams p=self.params;p.progress=value;self.params=p;
+    [self.surface draw];
+    if(!hold) [self play:self.goal];
+}
+- (void)finish:(double)endpoint {
+    if(self.disposed || self.params.mode==1) return;
+    self.progress=endpoint; self.playing=NO;
+    self.surface.paused=YES;
+    if(self.listener) self.listener(YES,endpoint);
+}
+- (void)stop {
+    [self detach:YES];
+}
+- (void)stopPreservingImage {
+    [self detach:NO];
+}
+- (void)detach:(BOOL)restoreImage {
+    if(self.disposed) return;
+    self.disposed=YES; self.surface.paused=YES; self.surface.delegate=nil;
+    [self.surface removeFromSuperview]; self.surface=nil;
+    if(self.pan) { [self.image removeGestureRecognizer:self.pan];self.image.userInteractionEnabled=self.originalInteraction;self.pan=nil; }
+    if(restoreImage && !self.image.image) self.image.image=self.original;
+    self.sourceTexture=nil;self.destinationTexture=nil;self.original=nil;self.queue=nil;
+    self.textureBytes=0; self.listener=nil;
+}
+- (void)advance:(double)now {
+    if(!self.playing || self.paused || self.disposed) return;
+    double t=MIN(1,MAX(0,(now-self.anchor)/self.remaining));
+    JoltImageParams p=self.params;
+    if(self.settling) p.displacement=self.settleStart*(float)(exp(-8*t)*(1-t));
+    else {self.progress=self.startProgress+(self.goal-self.startProgress)*t;p.progress=self.progress;}
+    self.params=p;
+    if(t>=1) {
+        self.playing=NO;self.surface.paused=YES;self.surface.enableSetNeedsDisplay=YES;
+        if(!self.settling && self.listener) self.listener(YES,self.progress);
+    }
+}
+- (void)drawInMTKView:(MTKView *)view {
+    if(self.disposed) return;
+    double now=CACurrentMediaTime();
+    if(self.previousFrame>0 && self.playing) self.longestFrame=MAX(self.longestFrame,now-self.previousFrame);
+    self.previousFrame=now;self.frames++;
+    [self advance:now];
+    if(self.disposed) return;
+    MTLRenderPassDescriptor *pass=view.currentRenderPassDescriptor;
+    id<CAMetalDrawable> drawable=view.currentDrawable;
+    if(!pass || !drawable) return;
+    id<MTLCommandBuffer> command=[self.queue commandBuffer];
+    id<MTLRenderCommandEncoder> encoder=[command renderCommandEncoderWithDescriptor:pass];
+    [encoder setRenderPipelineState:self.pipeline];
+    JoltImageParams params=self.params;
+    [encoder setFragmentBytes:&params length:sizeof(params) atIndex:0];
+    [encoder setFragmentTexture:self.sourceTexture atIndex:0];
+    [encoder setFragmentTexture:self.destinationTexture atIndex:1];
+    [encoder drawPrimitives:MTLPrimitiveTypeTriangleStrip vertexStart:0 vertexCount:4];
+    [encoder endEncoding]; [command presentDrawable:drawable]; [command commit];
+}
+- (void)mtkView:(MTKView *)view drawableSizeWillChange:(CGSize)size {}
+- (void)drag:(UIPanGestureRecognizer *)gesture {
+    if(self.disposed || self.paused) return;
+    CGFloat scale=self.image.window.screen.scale;
+    JoltImageParams p=self.params;
+    if(gesture.state==UIGestureRecognizerStateBegan) {
+        self.playing=NO;self.surface.paused=YES;self.surface.enableSetNeedsDisplay=YES;
+        CGPoint position=[gesture locationInView:self.image],translation=[gesture translationInView:self.image];
+        p.origin=(vector_float2){(float)((position.x-translation.x)*scale),(float)((position.y-translation.y)*scale)};
+    }
+    if(gesture.state==UIGestureRecognizerStateBegan || gesture.state==UIGestureRecognizerStateChanged) {
+        CGPoint delta=[gesture translationInView:self.image];
+        double length=hypot(delta.x,delta.y)*scale;
+        double factor=length==0?0:p.amplitude*tanh(length/MAX(p.amplitude,1))/length;
+        p.displacement=(vector_float2){(float)(delta.x*scale*factor),(float)(delta.y*scale*factor)};
+        self.params=p;[self.surface draw];
+    } else if(gesture.state==UIGestureRecognizerStateEnded || gesture.state==UIGestureRecognizerStateCancelled || gesture.state==UIGestureRecognizerStateFailed) {
+        self.settleStart=p.displacement;self.anchor=CACurrentMediaTime();self.remaining=MIN(.6,self.duration);
+        self.playing=YES;self.settling=YES;self.surface.enableSetNeedsDisplay=NO;self.surface.paused=NO;
+    }
+}
+@end

package/platforms/ios/src/JoltInteractiveAnimation.h

@@ -0,0 +1,18 @@
+#import <UIKit/UIKit.h>
+NS_ASSUME_NONNULL_BEGIN
+
+/** Native sampled playback for opt-in interactive views. No UIKit method replacement. */
+@interface JoltInteractiveAnimation : NSObject
++ (instancetype)startView:(UIView *)view layers:(NSArray<CALayer *> *)layers keyPath:(NSString *)keyPath
+                  values:(NSArray<NSNumber *> *)values times:(NSArray<NSNumber *> *)times
+                duration:(double)duration delay:(double)delay repeat:(double)repeat
+                 reverse:(BOOL)reverse finalValue:(double)finalValue
+               startedAt:(double)startedAt completion:(void (^)(BOOL))completion;
++ (void)syncView:(UIView *)view excluding:(nullable NSString *)keyPath;
++ (nullable NSNumber *)valueForView:(UIView *)view keyPath:(NSString *)keyPath;
++ (NSUInteger)activeCount;
+@property(nonatomic, readonly) double elapsed;
+- (void)control:(double)elapsed paused:(BOOL)paused;
+- (void)cancel;
+@end
+NS_ASSUME_NONNULL_END