@vib3code/sdk 2.0.1 → 2.0.3-canary.0a63e71

package/cpp/geometry/WarpFunctions.cpp

@@ -0,0 +1,238 @@
+/**
+ * WarpFunctions.cpp - Core Type Warp Functions
+ *
+ * Provides warp transformations that modify base geometries to create
+ * the three core type variants (Base, Hypersphere, Hypertetrahedron).
+ *
+ * Core type 0 (Base, index 0-7):   No warp, pure base geometry.
+ * Core type 1 (Hypersphere, 8-15): Project onto 3-sphere surface.
+ * Core type 2 (Hypertetra, 16-23): Warp toward pentatope vertices.
+ */
+
+#include "math/Vec4.hpp"
+#include <vector>
+#include <cmath>
+#include <numbers>
+#include <algorithm>
+
+namespace vib3 {
+
+/**
+ * Project a 4D point onto the 3-sphere of given radius.
+ *
+ * Normalizes the point to lie on S3, then scales by `radius`.
+ * If the point is at the origin, returns a default point on the sphere.
+ *
+ * @param point  Input 4D point
+ * @param radius Radius of the target 3-sphere
+ * @return Point projected onto S3 * radius
+ */
+Vec4 warpHypersphere(Vec4 point, float radius) noexcept {
+    float len = point.length();
+
+    if (len < 1e-8f) {
+        // Degenerate case: return a default point on the sphere
+        return Vec4(radius, 0.0f, 0.0f, 0.0f);
+    }
+
+    return point * (radius / len);
+}
+
+/**
+ * Inverse stereographic projection from R3 to S3.
+ *
+ * Maps a 3D point (interpreted as x,y,z with w=0) onto the 3-sphere
+ * using inverse stereographic projection from the north pole (0,0,0,1).
+ *
+ * @param point Input 4D point (only x,y,z used)
+ * @return Point on unit S3
+ */
+Vec4 inverseStereographicToHypersphere(Vec4 point) noexcept {
+    float r2 = point.x * point.x + point.y * point.y + point.z * point.z;
+    float denom = 1.0f + r2;
+
+    return Vec4(
+        2.0f * point.x / denom,
+        2.0f * point.y / denom,
+        2.0f * point.z / denom,
+        (r2 - 1.0f) / denom
+    );
+}
+
+/**
+ * Apply Hopf fibration mapping.
+ *
+ * Given a point on S3, returns its base point on S2 (the Hopf projection)
+ * and the fiber angle. This is used to visualize toroidal structures
+ * inherent in the 3-sphere.
+ *
+ * @param point Point on S3
+ * @return Projected point (x,y,z = S2 base point, w = fiber angle)
+ */
+Vec4 hopfProject(Vec4 point) noexcept {
+    // Normalize to ensure on S3
+    Vec4 p = point.normalized();
+
+    // Hopf map S3 -> S2:
+    //   n1 = 2(x*z + y*w)
+    //   n2 = 2(y*z - x*w)
+    //   n3 = x^2 + y^2 - z^2 - w^2
+    float n1 = 2.0f * (p.x * p.z + p.y * p.w);
+    float n2 = 2.0f * (p.y * p.z - p.x * p.w);
+    float n3 = p.x * p.x + p.y * p.y - p.z * p.z - p.w * p.w;
+
+    // Fiber angle
+    float fiberAngle = std::atan2(p.y, p.x) - std::atan2(p.w, p.z);
+
+    return Vec4(n1, n2, n3, fiberAngle);
+}
+
+/**
+ * Batch warp: project all points in a geometry onto S3.
+ *
+ * @param points Input geometry vertices
+ * @param radius Radius of the target 3-sphere
+ * @return Warped vertices on the 3-sphere
+ */
+std::vector<Vec4> warpHypersphereBatch(const std::vector<Vec4>& points,
+                                        float radius) noexcept {
+    std::vector<Vec4> result;
+    result.reserve(points.size());
+
+    for (const auto& p : points) {
+        result.push_back(warpHypersphere(p, radius));
+    }
+
+    return result;
+}
+
+// ---- Hypertetrahedron (Pentatope) Warp ----
+
+namespace {
+
+/**
+ * The 5 vertices of a regular 5-cell (pentatope) in R4.
+ *
+ * These are the vertices of the simplest regular 4D polytope,
+ * the analogue of the tetrahedron in 4D.
+ */
+constexpr int kPentatopeVertexCount = 5;
+
+Vec4 getPentatopeVertex(int index) noexcept {
+    // Standard regular 5-cell vertices
+    // Constructed so that all pairwise distances are equal.
+    const float s = std::sqrt(2.0f / 5.0f);
+    const float t = std::sqrt(2.0f / 3.0f);
+    const float u = 1.0f / std::sqrt(3.0f);
+    const float v = 1.0f / std::sqrt(15.0f);
+
+    switch (index) {
+        case 0: return Vec4( t,         0.0f,     0.0f,     -v);
+        case 1: return Vec4(-u,         u,        0.0f,     -v);
+        case 2: return Vec4(-u,        -u,        0.0f,     -v);
+        case 3: return Vec4( 0.0f,      0.0f,     t,        -v);
+        case 4: return Vec4( 0.0f,      0.0f,     0.0f,  4.0f * v);
+        default: return Vec4::zero();
+    }
+}
+
+} // anonymous namespace
+
+/**
+ * Warp a 4D point toward the nearest pentatope vertex.
+ *
+ * Finds the closest vertex of the regular 5-cell and interpolates
+ * the point toward it, creating a tetrahedral clustering effect.
+ * The interpolation factor is based on the inverse distance to
+ * the nearest vertex, producing a gravitational pull effect.
+ *
+ * @param point Input 4D point
+ * @return Warped point attracted toward nearest pentatope vertex
+ */
+Vec4 warpHypertetra(Vec4 point) noexcept {
+    // Find nearest pentatope vertex
+    int nearestIdx = 0;
+    float nearestDist = point.distanceSquaredTo(getPentatopeVertex(0));
+
+    for (int i = 1; i < kPentatopeVertexCount; ++i) {
+        float dist = point.distanceSquaredTo(getPentatopeVertex(i));
+        if (dist < nearestDist) {
+            nearestDist = dist;
+            nearestIdx = i;
+        }
+    }
+
+    Vec4 nearest = getPentatopeVertex(nearestIdx);
+
+    // Warp factor based on distance (closer = stronger pull)
+    float dist = std::sqrt(nearestDist);
+    float warpStrength = 1.0f / (1.0f + dist * 2.0f);
+
+    // Interpolate toward the nearest pentatope vertex
+    return point.lerp(nearest, warpStrength);
+}
+
+/**
+ * Warp a 4D point onto the edges of the pentatope.
+ *
+ * Projects the point to the nearest edge of the 5-cell,
+ * producing a skeletal wireframe appearance.
+ *
+ * @param point Input 4D point
+ * @return Point projected onto nearest pentatope edge
+ */
+Vec4 warpToEdges(Vec4 point) noexcept {
+    // 10 edges of the pentatope (all pairs of 5 vertices)
+    constexpr int edgePairs[10][2] = {
+        {0, 1}, {0, 2}, {0, 3}, {0, 4},
+        {1, 2}, {1, 3}, {1, 4},
+        {2, 3}, {2, 4},
+        {3, 4}
+    };
+
+    Vec4 bestProjection = point;
+    float bestDist = 1e10f;
+
+    for (const auto& pair : edgePairs) {
+        Vec4 a = getPentatopeVertex(pair[0]);
+        Vec4 b = getPentatopeVertex(pair[1]);
+        Vec4 edge = b - a;
+        Vec4 toPoint = point - a;
+
+        // Project onto edge (clamped to [0,1])
+        float edgeLenSq = edge.dot(edge);
+        if (edgeLenSq < 1e-10f) continue;
+
+        float t = toPoint.dot(edge) / edgeLenSq;
+        t = std::max(0.0f, std::min(1.0f, t));
+
+        Vec4 projected = a.lerp(b, t);
+        float dist = point.distanceSquaredTo(projected);
+
+        if (dist < bestDist) {
+            bestDist = dist;
+            bestProjection = projected;
+        }
+    }
+
+    return bestProjection;
+}
+
+/**
+ * Batch warp: apply hypertetra warp to all points.
+ *
+ * @param points Input geometry vertices
+ * @return Warped vertices attracted toward pentatope vertices
+ */
+std::vector<Vec4> warpHypertetraBatch(const std::vector<Vec4>& points) noexcept {
+    std::vector<Vec4> result;
+    result.reserve(points.size());
+
+    for (const auto& p : points) {
+        result.push_back(warpHypertetra(p));
+    }
+
+    return result;
+}
+
+} // namespace vib3

package/cpp/geometry/Wave.cpp

@@ -0,0 +1,85 @@
+/**
+ * Wave.cpp - Sinusoidal Interference Pattern in 4D
+ *
+ * Generates a grid of 4D points with sinusoidal wave displacement.
+ * The base grid lies in the XZ plane, with Y and W components driven
+ * by interference of multiple wave sources.
+ */
+
+#include "math/Vec4.hpp"
+#include <vector>
+#include <cmath>
+#include <numbers>
+
+namespace vib3 {
+
+/**
+ * Generate a 4D sinusoidal interference pattern.
+ *
+ * Creates a resolution x resolution grid in the XZ plane, centered at
+ * the origin. The Y component is displaced by the sum of three wave
+ * sources with different frequencies, and the W component uses a
+ * cross-wave pattern, producing a rich 4D interference field.
+ *
+ * @param resolution Number of grid points along each axis (total = resolution^2)
+ * @return Vector of 4D points with wave displacement
+ */
+std::vector<Vec4> generateWave(int resolution) noexcept {
+    if (resolution < 4) resolution = 4;
+
+    constexpr float pi = std::numbers::pi_v<float>;
+
+    // Grid extends from -gridExtent to +gridExtent
+    constexpr float gridExtent = 2.0f;
+
+    // Wave parameters: {frequency, amplitude, phase offset X, phase offset Z}
+    struct WaveSource {
+        float freq;
+        float ampY;
+        float ampW;
+        float phaseX;
+        float phaseZ;
+    };
+
+    constexpr WaveSource waves[] = {
+        { 1.0f,  0.5f, 0.3f, 0.0f,        0.0f        },  // Primary wave
+        { 2.3f,  0.25f, 0.15f, pi * 0.5f,  pi * 0.25f  },  // Secondary wave
+        { 3.7f,  0.125f, 0.1f, pi * 0.75f, pi * 0.6f   },  // Tertiary wave
+    };
+    constexpr int numWaves = 3;
+
+    std::vector<Vec4> vertices;
+    vertices.reserve(static_cast<size_t>(resolution) * static_cast<size_t>(resolution));
+
+    float step = (2.0f * gridExtent) / static_cast<float>(resolution - 1);
+
+    for (int ix = 0; ix < resolution; ++ix) {
+        float x = -gridExtent + static_cast<float>(ix) * step;
+
+        for (int iz = 0; iz < resolution; ++iz) {
+            float z = -gridExtent + static_cast<float>(iz) * step;
+
+            float y = 0.0f;
+            float w = 0.0f;
+
+            // Sum contributions from all wave sources
+            for (int wi = 0; wi < numWaves; ++wi) {
+                const auto& ws = waves[wi];
+                float phX = ws.freq * x * pi + ws.phaseX;
+                float phZ = ws.freq * z * pi + ws.phaseZ;
+
+                // Y displacement: circular wave pattern
+                y += ws.ampY * std::sin(phX) * std::cos(phZ);
+
+                // W displacement: cross-interference pattern
+                w += ws.ampW * std::cos(phX + phZ);
+            }
+
+            vertices.emplace_back(x, y, z, w);
+        }
+    }
+
+    return vertices;
+}
+
+} // namespace vib3

package/cpp/include/vib3_ffi.h

@@ -0,0 +1,238 @@
+/**
+ * VIB3+ FFI Header
+ *
+ * C interface for cross-platform FFI bindings.
+ * Used by Flutter, React Native, and other FFI-capable frameworks.
+ */
+
+#ifndef VIB3_FFI_H
+#define VIB3_FFI_H
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Platform export macros
+#if defined(_WIN32) || defined(_WIN64)
+    #define VIB3_EXPORT __declspec(dllexport)
+#else
+    #define VIB3_EXPORT __attribute__((visibility("default")))
+#endif
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * 4D Vector (16-byte aligned)
+ */
+typedef struct VIB3_EXPORT Vib3Vec4 {
+    float x, y, z, w;
+} Vib3Vec4;
+
+/**
+ * 4D Rotor (8 components for proper 4D rotation)
+ */
+typedef struct VIB3_EXPORT Vib3Rotor4D {
+    float s;      // Scalar
+    float xy;     // Bivector XY
+    float xz;     // Bivector XZ
+    float yz;     // Bivector YZ
+    float xw;     // Bivector XW
+    float yw;     // Bivector YW
+    float zw;     // Bivector ZW
+    float xyzw;   // Pseudoscalar
+} Vib3Rotor4D;
+
+/**
+ * 4x4 Matrix (column-major)
+ */
+typedef struct VIB3_EXPORT Vib3Mat4x4 {
+    float data[16];
+} Vib3Mat4x4;
+
+/**
+ * Rotation plane enumeration
+ */
+typedef enum VIB3_EXPORT Vib3RotationPlane {
+    VIB3_PLANE_XY = 0,
+    VIB3_PLANE_XZ = 1,
+    VIB3_PLANE_YZ = 2,
+    VIB3_PLANE_XW = 3,
+    VIB3_PLANE_YW = 4,
+    VIB3_PLANE_ZW = 5
+} Vib3RotationPlane;
+
+/**
+ * Projection type enumeration
+ */
+typedef enum VIB3_EXPORT Vib3ProjectionType {
+    VIB3_PROJ_PERSPECTIVE = 0,
+    VIB3_PROJ_STEREOGRAPHIC = 1,
+    VIB3_PROJ_ORTHOGRAPHIC = 2,
+    VIB3_PROJ_OBLIQUE = 3
+} Vib3ProjectionType;
+
+/**
+ * Command batch result
+ */
+typedef struct VIB3_EXPORT Vib3BatchResult {
+    int32_t success_count;
+    int32_t error_count;
+    int32_t result_size;
+} Vib3BatchResult;
+
+/**
+ * Engine handle (opaque)
+ */
+typedef struct Vib3Engine* Vib3EngineHandle;
+
+/**
+ * Texture handle for rendering
+ */
+typedef struct {
+    void* native_handle;  // Platform-specific texture handle
+    int32_t width;
+    int32_t height;
+    int32_t format;
+} Vib3TextureHandle;
+
+// ============================================================================
+// Vec4 Functions
+// ============================================================================
+
+VIB3_EXPORT Vib3Vec4* vib3_vec4_create(float x, float y, float z, float w);
+VIB3_EXPORT void vib3_vec4_free(Vib3Vec4* v);
+VIB3_EXPORT float vib3_vec4_dot(const Vib3Vec4* a, const Vib3Vec4* b);
+VIB3_EXPORT float vib3_vec4_length(const Vib3Vec4* v);
+VIB3_EXPORT void vib3_vec4_normalize(Vib3Vec4* v);
+VIB3_EXPORT Vib3Vec4* vib3_vec4_add(const Vib3Vec4* a, const Vib3Vec4* b);
+VIB3_EXPORT Vib3Vec4* vib3_vec4_sub(const Vib3Vec4* a, const Vib3Vec4* b);
+VIB3_EXPORT Vib3Vec4* vib3_vec4_scale(const Vib3Vec4* v, float s);
+VIB3_EXPORT Vib3Vec4* vib3_vec4_lerp(const Vib3Vec4* a, const Vib3Vec4* b, float t);
+
+// ============================================================================
+// Rotor4D Functions
+// ============================================================================
+
+VIB3_EXPORT Vib3Rotor4D* vib3_rotor4d_identity(void);
+VIB3_EXPORT Vib3Rotor4D* vib3_rotor4d_from_plane_angle(Vib3RotationPlane plane, float angle);
+VIB3_EXPORT Vib3Rotor4D* vib3_rotor4d_from_euler6(
+    float xy, float xz, float yz,
+    float xw, float yw, float zw
+);
+VIB3_EXPORT void vib3_rotor4d_free(Vib3Rotor4D* r);
+VIB3_EXPORT Vib3Rotor4D* vib3_rotor4d_multiply(const Vib3Rotor4D* a, const Vib3Rotor4D* b);
+VIB3_EXPORT Vib3Vec4* vib3_rotor4d_rotate(const Vib3Rotor4D* r, const Vib3Vec4* v);
+VIB3_EXPORT Vib3Rotor4D* vib3_rotor4d_slerp(const Vib3Rotor4D* a, const Vib3Rotor4D* b, float t);
+VIB3_EXPORT void vib3_rotor4d_normalize(Vib3Rotor4D* r);
+VIB3_EXPORT Vib3Mat4x4* vib3_rotor4d_to_matrix(const Vib3Rotor4D* r);
+
+// ============================================================================
+// Mat4x4 Functions
+// ============================================================================
+
+VIB3_EXPORT Vib3Mat4x4* vib3_mat4x4_identity(void);
+VIB3_EXPORT Vib3Mat4x4* vib3_mat4x4_rotation_xy(float angle);
+VIB3_EXPORT Vib3Mat4x4* vib3_mat4x4_rotation_xz(float angle);
+VIB3_EXPORT Vib3Mat4x4* vib3_mat4x4_rotation_yz(float angle);
+VIB3_EXPORT Vib3Mat4x4* vib3_mat4x4_rotation_xw(float angle);
+VIB3_EXPORT Vib3Mat4x4* vib3_mat4x4_rotation_yw(float angle);
+VIB3_EXPORT Vib3Mat4x4* vib3_mat4x4_rotation_zw(float angle);
+VIB3_EXPORT Vib3Mat4x4* vib3_mat4x4_rotation_from_angles(
+    float xy, float xz, float yz,
+    float xw, float yw, float zw
+);
+VIB3_EXPORT void vib3_mat4x4_free(Vib3Mat4x4* m);
+VIB3_EXPORT Vib3Mat4x4* vib3_mat4x4_multiply(const Vib3Mat4x4* a, const Vib3Mat4x4* b);
+VIB3_EXPORT Vib3Vec4* vib3_mat4x4_multiply_vec4(const Vib3Mat4x4* m, const Vib3Vec4* v);
+VIB3_EXPORT void vib3_mat4x4_get_data(const Vib3Mat4x4* m, float* out);
+
+// ============================================================================
+// Projection Functions
+// ============================================================================
+
+VIB3_EXPORT Vib3Vec4* vib3_project_perspective(const Vib3Vec4* v, float distance);
+VIB3_EXPORT Vib3Vec4* vib3_project_stereographic(const Vib3Vec4* v);
+VIB3_EXPORT Vib3Vec4* vib3_project_orthographic(const Vib3Vec4* v);
+VIB3_EXPORT Vib3Vec4* vib3_project_oblique(const Vib3Vec4* v, float shear_x, float shear_y);
+
+// Batch projection (for geometry arrays)
+VIB3_EXPORT int32_t vib3_project_batch(
+    const float* positions,   // Input: [x,y,z,w, x,y,z,w, ...]
+    int32_t count,            // Number of Vec4s
+    Vib3ProjectionType type,
+    float param,              // Distance for perspective, unused for others
+    float* out                // Output: [x,y,z, x,y,z, ...]
+);
+
+// ============================================================================
+// Command Batching
+// ============================================================================
+
+/**
+ * Process a batch of commands
+ *
+ * @param commands Binary command buffer
+ * @param size Size of command buffer in bytes
+ * @param results Output buffer for results
+ * @return Number of bytes written to results
+ */
+VIB3_EXPORT int32_t vib3_process_command_batch(
+    const uint8_t* commands,
+    uint32_t size,
+    uint8_t* results
+);
+
+// ============================================================================
+// Engine Functions
+// ============================================================================
+
+VIB3_EXPORT Vib3EngineHandle vib3_engine_create(void);
+VIB3_EXPORT void vib3_engine_destroy(Vib3EngineHandle engine);
+
+VIB3_EXPORT bool vib3_engine_initialize(
+    Vib3EngineHandle engine,
+    int32_t width,
+    int32_t height
+);
+
+VIB3_EXPORT void vib3_engine_set_system(Vib3EngineHandle engine, const char* system);
+VIB3_EXPORT void vib3_engine_set_geometry(Vib3EngineHandle engine, int32_t index);
+VIB3_EXPORT void vib3_engine_set_rotation(
+    Vib3EngineHandle engine,
+    Vib3RotationPlane plane,
+    float angle
+);
+VIB3_EXPORT void vib3_engine_set_all_rotations(
+    Vib3EngineHandle engine,
+    float xy, float xz, float yz,
+    float xw, float yw, float zw
+);
+VIB3_EXPORT void vib3_engine_reset_rotation(Vib3EngineHandle engine);
+
+VIB3_EXPORT void vib3_engine_set_visual_param(
+    Vib3EngineHandle engine,
+    const char* param,
+    float value
+);
+
+VIB3_EXPORT void vib3_engine_render(Vib3EngineHandle engine);
+VIB3_EXPORT Vib3TextureHandle vib3_engine_get_texture(Vib3EngineHandle engine);
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+VIB3_EXPORT const char* vib3_version(void);
+VIB3_EXPORT const char* vib3_geometry_name(int32_t index);
+VIB3_EXPORT bool vib3_has_simd(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // VIB3_FFI_H