feat(scripting): 3D Vector ops, Mat4 lookAt/ortho, Vector buffer writes, GPUBuffer write source range (#13003) ef0e100413

* feat(scripting): 3D Vector ops, Mat4 lookAt/ortho, Vector buffer writes, GPUBuffer write source range

* test(scripting): pin Vector fastcall and C binding paths bit-identical, align lerp endpoint

Co-authored-by: Luigi Rosso <luigi-rosso@users.noreply.github.com>

Author: luigi-rosso

.rive_head

@@ -1 +1 @@
-eeb280d7f906f2e47bb77c02600a301dda7e600d
+ef0e10041348832ffb0d398b9bb20df97a1d00b8

include/rive/lua/rive_lua_libs.hpp

@@ -347,6 +347,9 @@ enum class LuaAtoms : int16_t
     writeToBuffer,
     invertAffine,
 
+    // Vector
+    writeVec4,
+
     // Gamepad
     axes,
     gamepadMapping,

include/rive/math/mat4.hpp

@@ -178,6 +178,73 @@ class Mat4
         return m;
     }
 
+    // Right-handed view matrix looking from `eye` toward `center` (GLM
+    // convention). `up` need not be normalized.
+    static Mat4 lookAt(const float eye[3],
+                       const float center[3],
+                       const float up[3])
+    {
+        float f[3] = {center[0] - eye[0],
+                      center[1] - eye[1],
+                      center[2] - eye[2]};
+        float fInv = 1.f / std::sqrt(f[0] * f[0] + f[1] * f[1] + f[2] * f[2]);
+        f[0] *= fInv;
+        f[1] *= fInv;
+        f[2] *= fInv;
+        float s[3] = {f[1] * up[2] - f[2] * up[1],
+                      f[2] * up[0] - f[0] * up[2],
+                      f[0] * up[1] - f[1] * up[0]};
+        float sInv = 1.f / std::sqrt(s[0] * s[0] + s[1] * s[1] + s[2] * s[2]);
+        s[0] *= sInv;
+        s[1] *= sInv;
+        s[2] *= sInv;
+        float u[3] = {s[1] * f[2] - s[2] * f[1],
+                      s[2] * f[0] - s[0] * f[2],
+                      s[0] * f[1] - s[1] * f[0]};
+        Mat4 m;
+        m.m_buffer[0] = s[0];
+        m.m_buffer[1] = u[0];
+        m.m_buffer[2] = -f[0];
+        m.m_buffer[4] = s[1];
+        m.m_buffer[5] = u[1];
+        m.m_buffer[6] = -f[1];
+        m.m_buffer[8] = s[2];
+        m.m_buffer[9] = u[2];
+        m.m_buffer[10] = -f[2];
+        m.m_buffer[12] = -(s[0] * eye[0] + s[1] * eye[1] + s[2] * eye[2]);
+        m.m_buffer[13] = -(u[0] * eye[0] + u[1] * eye[1] + u[2] * eye[2]);
+        m.m_buffer[14] = f[0] * eye[0] + f[1] * eye[1] + f[2] * eye[2];
+        return m;
+    }
+
+    // Right-handed orthographic projection. Maps view-space z=[-near, -far]
+    // to NDC z in either [0, 1] (default, depthZeroToOne=true) or [-1, 1].
+    static Mat4 ortho(float left,
+                      float right,
+                      float bottom,
+                      float top,
+                      float near_,
+                      float far_,
+                      bool depthZeroToOne = true)
+    {
+        Mat4 m;
+        m.m_buffer[0] = 2.f / (right - left);
+        m.m_buffer[5] = 2.f / (top - bottom);
+        m.m_buffer[12] = -(right + left) / (right - left);
+        m.m_buffer[13] = -(top + bottom) / (top - bottom);
+        if (depthZeroToOne)
+        {
+            m.m_buffer[10] = -1.f / (far_ - near_);
+            m.m_buffer[14] = -near_ / (far_ - near_);
+        }
+        else
+        {
+            m.m_buffer[10] = -2.f / (far_ - near_);
+            m.m_buffer[14] = -(far_ + near_) / (far_ - near_);
+        }
+        return m;
+    }
+
     // SIMD: out = lhs * rhs. Both column-major.
     static Mat4 multiply(const Mat4& lhs, const Mat4& rhs)
     {

scripting/premake5.lua

@@ -1,5 +1,5 @@
 local dependency = require('dependency')
-local luau = dependency.github('luigi-rosso/luau', 'rive_0_728')
+local luau = dependency.github('luigi-rosso/luau', 'rive_0_728_vec3')
 local libhydrogen = dependency.github('luigi-rosso/libhydrogen', 'rive_0_2')
 
 dofile('rive_build_config.lua')

src/lua/math/lua_mat4.cpp

@@ -90,6 +90,27 @@ static int mat4_perspectiveReverseZ(lua_State* L)
     return 1;
 }
 
+static int mat4_lookAt(lua_State* L)
+{
+    const float* eye = luaL_checkvector(L, 1);
+    const float* center = luaL_checkvector(L, 2);
+    const float* up = luaL_checkvector(L, 3);
+    lua_pushmat4(L, Mat4::lookAt(eye, center, up));
+    return 1;
+}
+
+static int mat4_ortho(lua_State* L)
+{
+    float l = float(luaL_checknumber(L, 1));
+    float r = float(luaL_checknumber(L, 2));
+    float b = float(luaL_checknumber(L, 3));
+    float t = float(luaL_checknumber(L, 4));
+    float n = float(luaL_checknumber(L, 5));
+    float f = float(luaL_checknumber(L, 6));
+    lua_pushmat4(L, Mat4::ortho(l, r, b, t, n, f, /*zeroToOne=*/true));
+    return 1;
+}
+
 // In-place: Mat4.multiply(out, a, b)  ->  out = a * b. Returns out.
 // Avoids per-call userdata allocation in tight loops.
 static int mat4_static_multiply(lua_State* L)
@@ -379,6 +400,8 @@ static const luaL_Reg mat4StaticMethods[] = {
     {"fromRotationZ", mat4_fromRotationZ},
     {"perspective", mat4_perspective},
     {"perspectiveReverseZ", mat4_perspectiveReverseZ},
+    {"lookAt", mat4_lookAt},
+    {"ortho", mat4_ortho},
     {"multiply", mat4_static_multiply},
     {"multiplyAffine", mat4_static_multiplyAffine},
     {"invert", mat4_static_invert},

src/lua/math/lua_vec2d.cpp

@@ -2,6 +2,8 @@
 #ifdef WITH_RIVE_SCRIPTING
 #include "rive/lua/rive_lua_libs.hpp"
 #include "lualib.h"
+#include <cmath>
+#include <cstring>
 
 using namespace rive;
 
@@ -40,49 +42,59 @@ static int vector_index(lua_State* L)
     return 0;
 }
 
+// All magnitude and interpolation ops read all 3 components. For genuine 2D
+// vectors z is 0, so results are identical to the old 2D math.
+static inline float dot3(const float* a, const float* b)
+{
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+
 static int vector_length(lua_State* L)
 {
-    auto vec = lua_checkvec2d(L, 1);
-    lua_pushnumber(L, vec->length());
+    const float* vec = luaL_checkvector(L, 1);
+    lua_pushnumber(L, std::sqrt(dot3(vec, vec)));
     return 1;
 }
 
 static int vector_normalized(lua_State* L)
 {
-    auto vec = lua_checkvec2d(L, 1);
-    lua_pushvec2d(L, vec->normalized());
+    const float* vec = luaL_checkvector(L, 1);
+    float len2 = dot3(vec, vec);
+    float scale = len2 > 0 ? 1.f / std::sqrt(len2) : 1.f;
+    lua_pushvector(L, vec[0] * scale, vec[1] * scale, vec[2] * scale);
     return 1;
 }
 
 static int vector_lengthSquared(lua_State* L)
 {
-    auto vec = lua_checkvec2d(L, 1);
-    lua_pushnumber(L, vec->lengthSquared());
+    const float* vec = luaL_checkvector(L, 1);
+    lua_pushnumber(L, dot3(vec, vec));
     return 1;
 }
 
-static int vector_distance(lua_State* L)
+static int vector_distanceSquared(lua_State* L)
 {
-    auto lhs = lua_checkvec2d(L, 1);
-    auto rhs = lua_checkvec2d(L, 2);
-    lua_pushnumber(L, Vec2D::distance(*lhs, *rhs));
+    const float* lhs = luaL_checkvector(L, 1);
+    const float* rhs = luaL_checkvector(L, 2);
+    float d[3] = {rhs[0] - lhs[0], rhs[1] - lhs[1], rhs[2] - lhs[2]};
+    lua_pushnumber(L, dot3(d, d));
     return 1;
 }
 
-static int vector_distanceSquared(lua_State* L)
+static int vector_distance(lua_State* L)
 {
-    auto lhs = lua_checkvec2d(L, 1);
-    auto rhs = lua_checkvec2d(L, 2);
-    lua_pushnumber(L, Vec2D::distanceSquared(*lhs, *rhs));
+    const float* lhs = luaL_checkvector(L, 1);
+    const float* rhs = luaL_checkvector(L, 2);
+    float d[3] = {rhs[0] - lhs[0], rhs[1] - lhs[1], rhs[2] - lhs[2]};
+    lua_pushnumber(L, std::sqrt(dot3(d, d)));
     return 1;
 }
 
 static int vector_dot(lua_State* L)
 {
-    auto lhs = lua_checkvec2d(L, 1);
-    auto rhs = lua_checkvec2d(L, 2);
-
-    lua_pushnumber(L, Vec2D::dot(*lhs, *rhs));
+    const float* lhs = luaL_checkvector(L, 1);
+    const float* rhs = luaL_checkvector(L, 2);
+    lua_pushnumber(L, dot3(lhs, rhs));
     return 1;
 }
 
@@ -94,33 +106,98 @@ static int vector_cross(lua_State* L)
     return 1;
 }
 
+// 3D cross product. Distinct from `cross`, which returns the scalar 2D
+// perp-dot.
+static int vector_cross3(lua_State* L)
+{
+    const float* a = luaL_checkvector(L, 1);
+    const float* b = luaL_checkvector(L, 2);
+    lua_pushvector(L,
+                   a[1] * b[2] - a[2] * b[1],
+                   a[2] * b[0] - a[0] * b[2],
+                   a[0] * b[1] - a[1] * b[0]);
+    return 1;
+}
+
 static int vector_scaleAndAdd(lua_State* L)
 {
-    auto a = lua_checkvec2d(L, 1);
-    auto b = lua_checkvec2d(L, 2);
+    const float* a = luaL_checkvector(L, 1);
+    const float* b = luaL_checkvector(L, 2);
     float scale = float(luaL_checknumber(L, 3));
-    lua_pushvec2d(L, Vec2D::scaleAndAdd(*a, *b, scale));
+    lua_pushvector(L,
+                   a[0] + b[0] * scale,
+                   a[1] + b[1] * scale,
+                   a[2] + b[2] * scale);
     return 1;
 }
 
 static int vector_scaleAndSub(lua_State* L)
 {
-    auto a = lua_checkvec2d(L, 1);
-    auto b = lua_checkvec2d(L, 2);
+    const float* a = luaL_checkvector(L, 1);
+    const float* b = luaL_checkvector(L, 2);
     float scale = float(luaL_checknumber(L, 3));
-    lua_pushvec2d(L, *a - *b * scale);
+    lua_pushvector(L,
+                   a[0] - b[0] * scale,
+                   a[1] - b[1] * scale,
+                   a[2] - b[2] * scale);
     return 1;
 }
 
+// Exact at t=1, mirroring the VM fastcall's luai_lerpf so both dispatch
+// paths return bit-identical results.
+static inline float lerpf(float a, float b, float t)
+{
+    return t == 1.f ? b : a + (b - a) * t;
+}
+
 static int vector_lerp(lua_State* L)
 {
-    auto lhs = lua_checkvec2d(L, 1);
-    auto rhs = lua_checkvec2d(L, 2);
-    float factor = float(luaL_checknumber(L, 3));
-    lua_pushvec2d(L, Vec2D::lerp(*lhs, *rhs, factor));
+    const float* a = luaL_checkvector(L, 1);
+    const float* b = luaL_checkvector(L, 2);
+    float t = float(luaL_checknumber(L, 3));
+    lua_pushvector(L,
+                   lerpf(a[0], b[0], t),
+                   lerpf(a[1], b[1], t),
+                   lerpf(a[2], b[2], t));
     return 1;
 }
 
+// vec:writeToBuffer(buf, byteOffset) — 12 bytes (x, y, z as float32).
+static int vector_writeToBuffer(lua_State* L)
+{
+    const float* vec = luaL_checkvector(L, 1);
+    size_t bufLen = 0;
+    void* buf = luaL_checkbuffer(L, 2, &bufLen);
+    int off = int(luaL_checkinteger(L, 3));
+    if (off < 0 || size_t(off) + 12 > bufLen)
+    {
+        luaL_error(L, "Vector:writeToBuffer offset out of range");
+        return 0;
+    }
+    std::memcpy(static_cast<uint8_t*>(buf) + off, vec, 12);
+    return 0;
+}
+
+// vec:writeVec4(buf, byteOffset, w) — 16 bytes (x, y, z, w as float32),
+// matching a vec4 uniform-buffer slot.
+static int vector_writeVec4(lua_State* L)
+{
+    const float* vec = luaL_checkvector(L, 1);
+    size_t bufLen = 0;
+    void* buf = luaL_checkbuffer(L, 2, &bufLen);
+    int off = int(luaL_checkinteger(L, 3));
+    float w = float(luaL_checknumber(L, 4));
+    if (off < 0 || size_t(off) + 16 > bufLen)
+    {
+        luaL_error(L, "Vector:writeVec4 offset out of range");
+        return 0;
+    }
+    uint8_t* dst = static_cast<uint8_t*>(buf) + off;
+    std::memcpy(dst, vec, 12);
+    std::memcpy(dst + 12, &w, 4);
+    return 0;
+}
+
 static int vector_xy(lua_State* L)
 {
     float x = (float)lua_tonumber(L, 1);
@@ -130,6 +207,16 @@ static int vector_xy(lua_State* L)
     return 1;
 }
 
+static int vector_xyz(lua_State* L)
+{
+    float x = (float)lua_tonumber(L, 1);
+    float y = (float)lua_tonumber(L, 2);
+    float z = (float)lua_tonumber(L, 3);
+
+    lua_pushvector(L, x, y, z);
+    return 1;
+}
+
 static int vector_origin(lua_State* L)
 {
     lua_pushvector2(L, 0.0f, 0.0f);
@@ -158,6 +245,10 @@ static int vector_namecall(lua_State* L)
                 return vector_dot(L);
             case (int)LuaAtoms::lerp:
                 return vector_lerp(L);
+            case (int)LuaAtoms::writeToBuffer:
+                return vector_writeToBuffer(L);
+            case (int)LuaAtoms::writeVec4:
+                return vector_writeVec4(L);
         }
     }
 
@@ -170,10 +261,12 @@ static const luaL_Reg vectorStaticMethods[] = {
     {"distanceSquared", vector_distanceSquared},
     {"dot", vector_dot},
     {"cross", vector_cross},
+    {"cross3", vector_cross3},
     {"scaleAndAdd", vector_scaleAndAdd},
     {"scaleAndSub", vector_scaleAndSub},
     {"lerp", vector_lerp},
     {"xy", vector_xy},
+    {"xyz", vector_xyz},
     {"origin", vector_origin},
     {"length", vector_length},
     {"lengthSquared", vector_lengthSquared},