SharedValue, DerivedValue의 동작 원리

이번 글에서 살펴볼 내용

• SharedValue가 C++ 레벨에서 실제로 어떤 형태로 존재하며, 왜 두 런타임에서 값을 동기적으로 읽을 수 있는지

• useDerivedValue가 React를 거치지 않고 값을 어떻게 조합하는지

• withTiming, withSpring, withDecay가 사용하는 Animation Driver 모델

• 매 프레임마다 실제로 이루어지는 Spring Physics 계산

• Reanimated가 애니메이션을 언제 종료해야 하는지 어떻게 판단하는지

SharedValue: React State도, Signal도 아니다

// SharedValue — simplified internal structure
class SharedValue {
  std::mutex mutex;
  AnimationState currentAnimation; // null if not animating
  JSValue storedValue;             // the raw value (number, object, array)
  std::vector<WorkletHandle> listeners; // registered useAnimatedStyle callbacks
};

          Main JS Thread                  UI Thread 런타임
                │                               │
                │── write sv.value = 1 ──►      │
                │   (JSI → C++ mutex lock)      │
                │                               │
                │           ◄── read sv.value ──│
                │       (JSI → C++ mutex lock)  │
                │                               │
                │      C++ SharedValue Store    │
                │         (sv.storedValue)      │
                └─────────────────┬─────────────┘
                                  │
                          Owned by C++ layer,
                     accessible from both sides via JSI

useDerivedValue: React 없이 동작하는 Reactive Computation

const progress = useSharedValue(0);

const opacity = useDerivedValue(() => {
  'worklet';

  return interpolate(progress.value, [0, 1], [0.2, 1]);
});

// DerivedValue dependency tracking

Derivation Worklet이 실행되면:

1. Reanimated는 모든 `sharedValue.value` 읽기를 감지한다.
2. 각각의 읽기는 해당 SharedValue의 "subscriber"로 DerivedValue를 등록한다.
3. 구독 중인 SharedValue가 변경되면 DerivedValue를 dirty 상태로 표시한다.
4. 다음 프레임에서 Worklet을 다시 실행하고 DerivedValue를 업데이트한다.

// This is reactive computation, fully on the UI thread

const scrollY = useSharedValue(0);

// Derived values — all computed on UI thread, zero React renders
const headerOpacity = useDerivedValue(() =>
  interpolate(scrollY.value, [0, 100], [1, 0], Extrapolate.CLAMP)
);

const headerTranslateY = useDerivedValue(() =>
  interpolate(scrollY.value, [0, 100], [0, -60], Extrapolate.CLAMP)
);

const contentPaddingTop = useDerivedValue(() =>
  interpolate(scrollY.value, [0, 100], [120, 60], Extrapolate.CLAMP)
);

// 하나의 scrollY 변화만으로 세 값이 매 프레임마다 업데이트됩니다.
// 이 과정에서 React는 아무것도 알지 못합니다.

Animation Driver: withTiming, withSpring, withDecay

sharedValue.value = withSpring(1);

// Animation driver model

withSpring(target)는 다음과 같은 AnimationObject를 반환한다고 생각할 수 있다.

{
  type: 'spring',
  current: 0,        // 현재 값
  target: 1,         // 목표 값
  velocity: 0,       // 현재 속도
  config: { ... }    // stiffness, damping, mass
}

1. C++ Frame Callback 실행

2. 활성화된 Animation을 가지고 있는 각각의 SharedValue에 대해:
   a. animation.nextValue(frameTime, animation.current, animation.velocity) 호출
   b. 반환된 값을 SharedValue에 저장
   c. Animation 상태 업데이트 (velocity, elapsed time 등)
   d. Animation이 종료되었다면 SharedValue에서 Driver 제거

3. Subscriber들에게 값이 변경되었음을 알림

withTiming: Easing Function으로 값을 변화시키기

// withTiming driver (simplified)

function timingStep(elapsed, duration, from, to, easingFn) {
  'worklet';

  const progress = Math.min(elapsed / duration, 1);
  const easedProgress = easingFn(progress);

  const currentValue =
    from + (to - from) * easedProgress;

  const finished = progress >= 1;

  return {
    value: currentValue,
    finished
  };
}

// ✅ Custom easing — must be a worklet

const customEasing = (t) => {
  'worklet';

  return t < 0.5
    ? 2 * t * t
    : -1 + (4 - 2 * t) * t;
};

sharedValue.value = withTiming(1, {
  duration: 400,
  easing: customEasing,
});

Animation Composition: withSequence, withRepeat, withDelay

• withDelay(ms, animation) — 지정된 시간 동안 현재 값을 유지한 뒤 내부 Animation Driver에 실행을 위임합니다.

• withSequence(...animations) — 여러 Animation을 순서대로 실행하고, 현재 Animation이 끝나면 다음 Animation으로 넘어갑니다.

• withRepeat(animation, n) — Animation이 끝날 때마다 다시 시작하며, 지정된 횟수만큼 반복합니다. 1을 전달하면 무한 반복합니다.

// Animation driver composition

withRepeat(
  withSequence(
    withTiming(1, { duration: 300 }),
    withTiming(0, { duration: 300 })
  ),
  -1
)

Frame N: withRepeat.nextValue(dt)
  → withSequence.nextValue(dt)에 위임
    → withTiming(1).nextValue(dt)에 위임
    → { value: 0.3, finished: false } 반환

Frame N+20:
  withSequence가 withTiming(1)의 종료를 감지
  → withTiming(0)으로 전환

Frame N+40:
  withSequence가 withTiming(0)의 종료를 감지
  → withRepeat에 finished 전달

withRepeat:
  반복 횟수가 남아 있다면 다시 시작
  → withSequence 상태 초기화

SharedValue Listener: Main JS Thread로 돌아가는 방법

useAnimatedReaction(
  () => progress.value,      // selector — UI thread에서 실행
  (current, previous) => {    // handler — 기본적으로 UI thread에서 실행
    if (current >= 1 && previous < 1) {
      runOnJS(onAnimationComplete)(); // Main JS Thread로 알림
    }
  }
);

정리: 이번 글에서 살펴본 내용

• SharedValue는 React State가 아니라 JSI Binding을 가진 C++ 객체입니다. 두 런타임에서 동기적으로 읽고 쓸 수 있으며 Mutex를 통해 접근이 보호됩니다.

• useDerivedValue는 React의 개입 없이 UI Thread에서 동작하는 Reactive Computation을 만들며, SharedValue와 DerivedValue 사이의 의존 관계는 DAG 형태로 관리됩니다.

• Animation Driver(withSpring, withTiming, withDecay)는 경과 시간과 현재 상태를 기반으로 매 프레임마다 다음 값을 계산하는 Worklet입니다.

• Spring Physics는 감쇠 조화 진동자 모델을 사용하며, Semi-implicit Euler 방식으로 위치와 속도를 계산합니다. 변위와 속도가 설정된 Rest Threshold 아래로 내려가면 애니메이션이 종료됩니다.

• withSequence, withRepeat, withDelay는 동일한 Animation Driver Interface를 기반으로 여러 Animation을 조합할 수 있도록 해줍니다.

• useAnimatedReaction은 UI Thread에서 Selector를 실행하고 그 결과가 변경되었을 때 Handler를 실행합니다. 불필요한 매 프레임 실행을 피하기 위해 Selector는 최대한 간단하게 유지하는 것이 좋습니다.

다음 글에서는

원문

React Native Reanimated Internals, Part 3: SharedValue, DerivedValue, and How Animation Drivers…

Here’s a question that stumped me for a while: when you call withSpring(1), where does the spring calculation happen? How does Reanimated…

https://medium.com/@debdut.saha.1/react-native-reanimated-internals-part-3-sharedvalue-derivedvalue-and-how-animation-drivers-1dfae8538b32