feat: 3D and 2D CSS transform matrix integration (#8195)

## Summary

This PR finally adds the integration of 2D and 3D transform matrix in
transforms interpolation. The 2D matrix is used when possible to
optimize interpolation. If the user uses a transformation that requires
a 3D space (like x, y rotation or perspective), the 3D matrix is used
instead. 2D transform matrix is automatically converted to the 3D
transform matrix when needed.

## Test plan

<details>
<summary>Code snippet</summary>

```tsx
import { useState } from 'react';
import type { ViewStyle } from 'react-native';
import { StyleSheet, View } from 'react-native';
import Animated from 'react-native-reanimated';

import { Button, Screen } from '@/apps/css/components';

const transitionStyles: Array<ViewStyle> = [
  {
    transform: [{ rotate: '45deg' }, { skewX: '45deg' }],
  },
  {
    transform: [{ translateY: 200 }, { rotate: '45deg' }, { scale: 2 }],
  },
  {
    transform: [{ rotate: '45deg' }, { translateY: 150 }],
    width: 200,
  },
];

export default function Playground() {
  const [state, setState] = useState(0);
  const stateToStyle = (num: number) => {
    return transitionStyles[num % transitionStyles.length];
  };

  return (
    <Screen>
      <View style={styles.container}>
        <Button
          title="Change state"
          onPress={() => {
            setState(state + 1);
          }}
        />
        <Animated.View
          style={[
            {
              backgroundColor: 'red',
              height: 65,
              marginTop: 60,
              transitionDuration: '0.5s',
              width: 65,
            },
            stateToStyle(state),
          ]}
        />
      </View>
    </Screen>
  );
}

const styles = StyleSheet.create({
  container: {
    alignItems: 'center',
    flex: 1,
    justifyContent: 'center',
  },
});
```

</details>

Author: MatiPl01

apps/fabric-example/ios/Podfile.lock

@@ -3190,10 +3190,10 @@ SPEC CHECKSUMS:
   RNReanimated: 3b47c33660454c6f9700b463e92daa282030866a
   RNScreens: 6ced6ae8a526512a6eef6e28c2286e1fc2d378c3
   RNSVG: 287504b73fa0e90a605225aa9f852a86d5461e84
-  RNWorklets: 7119ae08263033c456c80d90794a312f2f88c956
+  RNWorklets: 991f94e4fa31fc20853e74d5d987426f8580cb0d
   SocketRocket: d4aabe649be1e368d1318fdf28a022d714d65748
   Yoga: e80c5fabbc3e26311152fa20404cdfa14f16a11f
 
-PODFILE CHECKSUM: 5d8c04f461eed0f22e86610877d94f2b8b838b8b
+PODFILE CHECKSUM: db099f48c6dadedd8fc0a430129b75e561867ab9
 
 COCOAPODS: 1.15.2

packages/react-native-reanimated/Common/cpp/reanimated/CSS/InterpolatorRegistry.cpp

@@ -10,7 +10,7 @@
 #include <reanimated/CSS/common/values/CSSNumber.h>
 #include <reanimated/CSS/common/values/CSSValue.h>
 
-#include <reanimated/CSS/common/transforms/TransformMatrix3D.h>
+#include <reanimated/CSS/common/transforms/TransformMatrix2D.h>
 #include <reanimated/CSS/common/values/complex/CSSBoxShadow.h>
 
 #include <reanimated/CSS/svg/values/SVGLength.h>
@@ -164,8 +164,7 @@ const InterpolatorFactoriesRecord TRANSFORMS_INTERPOLATORS = {
            transformOp<TranslateYOperation>(0, {RelativeTo::Self, "height"})},
           {"skewX", transformOp<SkewXOperation>("0deg")},
           {"skewY", transformOp<SkewYOperation>("0deg")},
-          {"matrix",
-           transformOp<MatrixOperation>(TransformMatrix3D::Identity())}})},
+          {"matrix", transformOp<MatrixOperation>(TransformMatrix2D())}})},
 };
 
 const InterpolatorFactoriesRecord VIEW_INTERPOLATORS = mergeInterpolators(

packages/react-native-reanimated/Common/cpp/reanimated/CSS/common/transforms/TransformMatrix.h

@@ -3,24 +3,33 @@
 #include <reanimated/CSS/common/definitions.h>
 
 #include <folly/dynamic.h>
+#include <memory>
 #include <string>
 #include <utility>
 
 namespace reanimated::css {
 
 class TransformMatrix {
  public:
-  virtual ~TransformMatrix() = default;
-
-  virtual double determinant() const = 0;
+  using Shared = std::shared_ptr<const TransformMatrix>;
 
-  virtual double &operator[](size_t index) = 0;
-  virtual const double &operator[](size_t index) const = 0;
+  TransformMatrix() = default;
+  virtual ~TransformMatrix() = default;
 
   virtual size_t getDimension() const = 0;
+  virtual size_t getSize() const = 0;
+
+  virtual bool isSingular() const = 0;
+  virtual bool normalize() = 0;
+  virtual void transpose() = 0;
+  virtual double determinant() const = 0;
 
   virtual std::string toString() const = 0;
   virtual folly::dynamic toDynamic() const = 0;
+
+  virtual double &operator[](size_t index) = 0;
+  virtual const double &operator[](size_t index) const = 0;
+  virtual bool operator==(const TransformMatrix &other) const = 0;
 };
 
 template <typename TDerived, size_t TDimension>
@@ -29,51 +38,72 @@ class TransformMatrixBase : public TransformMatrix {
   static constexpr size_t SIZE = TDimension * TDimension;
   using MatrixArray = std::array<double, SIZE>;
 
-  explicit TransformMatrixBase(MatrixArray matrix)
-      : matrix_(std::move(matrix)) {}
-
-  explicit TransformMatrixBase(jsi::Runtime &rt, const jsi::Value &value) {
-    const auto array = value.asObject(rt).asArray(rt);
-    if (array.size(rt) != SIZE) {
-      throw std::invalid_argument(
-          "[Reanimated] Matrix array should have " + std::to_string(SIZE) +
-          " elements");
-    }
-
-    for (size_t i = 0; i < SIZE; ++i) {
-      matrix_[i] = array.getValueAtIndex(rt, i).asNumber();
+  TransformMatrixBase() : TransformMatrix(), matrix_{} {
+    // Create an identity matrix
+    for (size_t i = 0; i < TDimension; ++i) {
+      matrix_[i * (TDimension + 1)] = 1;
     }
   }
 
-  explicit TransformMatrixBase(const folly::dynamic &array) {
-    if (!array.isArray() || array.size() != SIZE) {
-      throw std::invalid_argument(
-          "[Reanimated] Matrix array should have " + std::to_string(SIZE) +
-          " elements");
-    }
+  explicit TransformMatrixBase(MatrixArray matrix)
+      : TransformMatrix(), matrix_(std::move(matrix)) {}
 
-    for (size_t i = 0; i < SIZE; ++i) {
-      matrix_[i] = array[i].asDouble();
-    }
+  TransformMatrixBase(const TransformMatrixBase &other)
+      : TransformMatrix(), matrix_(other.matrix_) {}
+
+  TransformMatrixBase(TransformMatrixBase &&other) noexcept
+      : TransformMatrix(), matrix_(std::move(other.matrix_)) {}
+
+  inline bool operator==(const TDerived &other) const {
+    return matrix_ == other.matrix_;
   }
 
-  virtual bool operator==(const TDerived &other) const = 0;
+  inline bool operator==(const TransformMatrix &other) const override {
+    return TDimension == other.getDimension() &&
+        matrix_ == static_cast<const TDerived &>(other).matrix_;
+  }
 
-  double &operator[](size_t index) override {
+  inline double &operator[](size_t index) override {
     return matrix_[index];
   }
 
-  const double &operator[](size_t index) const override {
+  inline const double &operator[](size_t index) const override {
     return matrix_[index];
   }
 
-  TDerived operator*(const TDerived &rhs) const {
-    return TDerived(multiply(rhs));
+  size_t getDimension() const override {
+    return TDimension;
   }
 
-  TDerived &operator*=(const TDerived &rhs) {
-    matrix_ = multiply(rhs);
-    return static_cast<TDerived &>(*this);
+  size_t getSize() const override {
+    return SIZE;
+  }
+
+  bool isSingular() const override {
+    return determinant() == 0;
+  }
+
+  bool normalize() override {
+    const auto last = matrix_[SIZE - 1];
+    if (last == 0) {
+      return false;
+    }
+    if (last == 1) {
+      return true;
+    }
+
+    for (size_t i = 0; i < SIZE; ++i) {
+      matrix_[i] /= last;
+    }
+    return true;
+  }
+
+  void transpose() override {
+    for (size_t i = 0; i < TDimension; ++i) {
+      for (size_t j = i + 1; j < TDimension; ++j) {
+        std::swap(matrix_[i * TDimension + j], matrix_[j * TDimension + i]);
+      }
+    }
   }
 
   std::string toString() const override {
@@ -96,50 +126,46 @@ class TransformMatrixBase : public TransformMatrix {
     return result;
   }
 
-  size_t getDimension() const override {
-    return TDimension;
+  inline TDerived operator*(const TDerived &rhs) const {
+    return TDerived(multiply(rhs));
   }
 
-  bool isSingular() const {
-    return determinant() == 0;
+  inline TDerived &operator*=(const TDerived &rhs) {
+    matrix_ = multiply(rhs);
+    return static_cast<TDerived &>(*this);
   }
 
-  bool normalize() {
-    const auto last = matrix_[SIZE - 1];
-    if (last == 0) {
-      return false;
-    }
-    if (last == 1) {
-      return true;
-    }
-
-    for (size_t i = 0; i < SIZE; ++i) {
-      matrix_[i] /= last;
+  TransformMatrixBase &operator=(const TransformMatrixBase &other) {
+    if (this != &other) {
+      // Note: dimension_ is const, so we can't reassign it
+      // But since all instances have the same dimension, this is fine
+      matrix_ = other.matrix_;
     }
-    return true;
+    return *this;
   }
 
-  void transpose() {
-    for (size_t i = 0; i < TDimension; ++i) {
-      for (size_t j = i + 1; j < TDimension; ++j) {
-        std::swap(matrix_[i * TDimension + j], matrix_[j * TDimension + i]);
-      }
+  TransformMatrixBase &operator=(TransformMatrixBase &&other) noexcept {
+    if (this != &other) {
+      matrix_ = std::move(other.matrix_);
     }
+    return *this;
   }
 
  protected:
   std::array<double, SIZE> matrix_;
 
   MatrixArray multiply(const TDerived &rhs) const {
-    std::array<double, SIZE> result{};
+    MatrixArray result{};
+
     for (size_t i = 0; i < TDimension; ++i) {
-      for (size_t j = 0; j < TDimension; ++j) {
-        for (size_t k = 0; k < TDimension; ++k) {
-          result[i * TDimension + j] +=
-              matrix_[i * TDimension + k] * rhs[k * TDimension + j];
+      for (size_t k = 0; k < TDimension; ++k) {
+        double temp = matrix_[i * TDimension + k];
+        for (size_t j = 0; j < TDimension; ++j) {
+          result[i * TDimension + j] += temp * rhs[k * TDimension + j];
         }
       }
     }
+
     return result;
   }
 };