Ensure GLSL symbols are prefixed to avoid user name collision

Author: jeremyong

docs/gpu.md

@@ -1,21 +1,21 @@
 GPU support is currently provided by a single
 [glsl file](https://github.com/jeremyong/klein/blob/master/glsl/klein.glsl).
 This file can be pasted at the start of a shader to provide limited functionality supported by the
-full C++ Klein library. The plane, line, point, rotor, translator, and motor entity structs defined
-in this shader header are byte-for-byte identical to the entities as declared in C++.
+full C++ Klein library. The `kln_plane`, `kln_line`, `kln_point`, `kln_rotor`, and `kln_motor` entity structs defined
+in this shader header are byte-for-byte identical to their C++ counterparts.
 
 Currently, the following functions are supported:
 
-| Function                                              | Description                                       |
-| ----------------------------------------------------- | ------------------------------------------------- |
-| `rotor rr_mul(in rotor a, in rotor b)`                | Multiplies two rotors and returns the result      |
-| `translator tt_mul(in translator a, in translator b)` | Multiplies two translators and returns the result |
-| `motor mm_mul(in motor a, in motor b)`                | Multiplies two motors and returns the result      |
-| `plane rotor_plane(in rotor r, in plane p)`           | Applies a rotor to a plane                        |
-| `plane motor_plane(in motor m, in plane p)`           | Applies a motor to a plane                        |
-| `point rotor_plane(in rotor r, in point p)`           | Applies a rotor to a point                        |
-| `point motor_plane(in motor m, in point p)`           | Applies a motor to a point                        |
-| `point motor_plane(in motor m)`                       | Applies a motor to the origin                     |
+| Function                                                           | Description                                       |
+| ------------------------------------------------------------------ | ------------------------------------------------- |
+| `kln_rotor kln_mul(in kln_rotor a, in kln_rotor b)`                | Multiplies two rotors and returns the result      |
+| `kln_translator kln_mul(in kln_translator a, in kln_translator b)` | Multiplies two translators and returns the result |
+| `kln_motor kln_mul(in kln_motor a, in kln_motor b)`                | Multiplies two motors and returns the result      |
+| `kln_plane kln_apply(in kln_rotor r, in kln_plane p)`              | Applies a rotor to a plane                        |
+| `kln_plane kln_apply(in kln_motor m, in kln_plane p)`              | Applies a motor to a plane                        |
+| `kln_point kln_apply(in kln_rotor r, in kln_point p)`              | Applies a rotor to a point                        |
+| `kln_point kln_apply(in kln_motor m, in kln_point p)`              | Applies a motor to a point                        |
+| `kln_point kln_apply(in kln_motor m)`                              | Applies a motor to the origin                     |
 
 GPU support is verified with a C++ test suite powered by a
 [shim](https://github.com/jeremyong/klein/blob/master/test/glsl_shim.hpp)

glsl/klein.glsl

@@ -6,41 +6,44 @@
 // p2 -> (e0123, e01, e02, e03)
 // p3 -> (e123, e032, e013, e021)
 
-struct plane
+struct kln_plane
 {
     vec4 p0;
 };
 
-struct line
+struct kln_line
 {
     vec4 p1;
     vec4 p2;
 };
 
-struct point
+// If integrating this library with other code, remember that the point layout
+// here has the homogeneous component in p3[0] and not p3[3]. The swizzle to
+// get the vec3 Cartesian representation is p3.yzw
+struct kln_point
 {
     vec4 p3;
 };
 
-struct rotor
+struct kln_rotor
 {
     vec4 p1;
 };
 
-struct translator
+struct kln_translator
 {
     vec4 p2;
 };
 
-struct motor
+struct kln_motor
 {
     vec4 p1;
     vec4 p2;
 };
 
-rotor rr_mul(in rotor a, in rotor b)
+kln_rotor kln_mul(in kln_rotor a, in kln_rotor b)
 {
-    rotor c;
+    kln_rotor c;
     c.p1 = a.p1.x * b.p1;
     c.p1 -= a.p1.yzwy * b.p1.ywyz;
 
@@ -52,17 +55,17 @@ rotor rr_mul(in rotor a, in rotor b)
     return c;
 }
 
-translator tt_mul(in translator a, in translator b)
+kln_translator kln_mul(in kln_translator a, in kln_translator b)
 {
     // (1 + a.p2) * (1 + b.p2) = 1 + a.p2 + b.p2
-    translator c;
+    kln_translator c;
     c.p2 = a.p2 + b.p2;
     return c;
 }
 
-motor mm_mul(in motor a, in motor b)
+kln_motor kln_mul(in kln_motor a, in kln_motor b)
 {
-    motor c;
+    kln_motor c;
     vec4 a_zyzw = a.p1.zyzw;
     vec4 a_ywyz = a.p1.ywyz;
     vec4 a_wzwy = a.p1.wzwy;
@@ -89,7 +92,7 @@ motor mm_mul(in motor a, in motor b)
     return c;
 }
 
-plane rotor_plane(in rotor r, in plane p)
+kln_plane kln_apply(in kln_rotor r, in kln_plane p)
 {
     vec4 dc_scale = vec4(1.0, 2.0, 2.0, 2.0);
     vec4 neg_low = vec4(-1.0, 1.0, 1.0, 1.0);
@@ -108,14 +111,14 @@ plane rotor_plane(in rotor r, in plane p)
     t3 -= r.p1.xzwy * r.p1.xzwy;
 
     // TODO: provide variadic rotor-plane application
-    plane q;
+    kln_plane q;
     q.p0 = t1 * p.p0.xzwy;
     q.p0 += t2 * p.p0.xwyz;
     q.p0 += t3 * p.p0;
     return q;
 }
 
-plane motor_plane(in motor m, in plane p)
+kln_plane kln_apply(in kln_motor m, in kln_plane p)
 {
     vec4 dc_scale = vec4(1.0, 2.0, 2.0, 2.0);
     vec4 neg_low = vec4(-1.0, 1.0, 1.0, 1.0);
@@ -140,15 +143,15 @@ plane motor_plane(in motor m, in plane p)
     t4 *= vec4(0.0, 2.0, 2.0, 2.0);
 
     // TODO: provide variadic motor-plane application
-    plane q;
+    kln_plane q;
     q.p0 = t1 * p.p0.xzwy;
     q.p0 += t2 * p.p0.xwyz;
     q.p0 += t3 * p.p0;
     q.p0 += vec4(dot(t4, p.p0), 0.0, 0.0, 0.0);
     return q;
 }
 
-point rotor_point(in rotor r, in point p)
+kln_point kln_apply(in kln_rotor r, in kln_point p)
 {
     vec4 scale = vec4(0, 2, 2, 2);
 
@@ -167,14 +170,14 @@ point rotor_point(in rotor r, in point p)
     t3 -= t4 * vec4(-1.0, 1.0, 1.0, 1.0);
 
     // TODO: provide variadic rotor-point application
-    point q;
+    kln_point q;
     q.p3 = t1 * p.p3.xwyz;
     q.p3 += t2 * p.p3.xzwy;
     q.p3 += t3 * p.p3;
     return  q;
 }
 
-point motor_point(in motor m, in point p)
+kln_point kln_apply(in kln_motor m, in kln_point p)
 {
     vec4 scale = vec4(0, 2, 2, 2);
 
@@ -199,17 +202,21 @@ point motor_point(in motor m, in point p)
     t4 *= scale;
 
     // TODO: provide variadic motor-point application
-    point q;
+    kln_point q;
     q.p3 = t1 * p.p3.xwyz;
     q.p3 += t2 * p.p3.xzwy;
     q.p3 += t3 * p.p3;
     q.p3 += t4 * p.p3.x;
     return  q;
 }
 
-point motor_origin(in motor m)
+// If no entity is provided as the second argument, the motor is
+// applied to the origin.
+// NOTE: The motor MUST be normalized for the result of this operation to be
+// well defined.
+kln_point kln_apply(in kln_motor m)
 {
-    point p;
+    kln_point p;
     p.p3 = m.p1 * m.p2.x;
     p.p3 += m.p1.x * m.p2;
     p.p3 += m.p1.xwyz * m.p2.xzwy;

test/test_glsl.cpp

@@ -8,13 +8,13 @@
 
 TEST_CASE("rr_mul")
 {
-    rotor r1;
+    kln_rotor r1;
     r1.p1 = vec4(2, 3, 4, 5);
 
-    rotor r2;
+    kln_rotor r2;
     r2.p1 = vec4(6, 7, 8, 9);
 
-    rotor r3 = rr_mul(r1, r2);
+    kln_rotor r3 = kln_mul(r1, r2);
     CHECK_EQ(r3.p1.x, -86.f);
     CHECK_EQ(r3.p1.y, 36.f);
     CHECK_EQ(r3.p1.z, 32.f);
@@ -23,15 +23,15 @@ TEST_CASE("rr_mul")
 
 TEST_CASE("mm_mul")
 {
-    motor m1;
+    kln_motor m1;
     m1.p1 = vec4(2, 3, 4, 5);
     m1.p2 = vec4(9, 6, 7, 8);
 
-    motor m2;
+    kln_motor m2;
     m2.p1 = vec4(6, 7, 8, 9);
     m2.p2 = vec4(13, 10, 11, 12);
 
-    motor m3 = mm_mul(m1, m2);
+    kln_motor m3 = kln_mul(m1, m2);
     CHECK_EQ(m3.p1.x, -86.f);
     CHECK_EQ(m3.p1.y, 36.f);
     CHECK_EQ(m3.p1.z, 32.f);
@@ -44,11 +44,11 @@ TEST_CASE("mm_mul")
 
 TEST_CASE("rotor_plane")
 {
-    rotor r;
+    kln_rotor r;
     r.p1 = vec4(1, 4, -3, 2);
-    plane p1;
-    p1.p0    = vec4(2, 3, 4, 5);
-    plane p2 = rotor_plane(r, p1);
+    kln_plane p1;
+    p1.p0        = vec4(2, 3, 4, 5);
+    kln_plane p2 = kln_apply(r, p1);
     CHECK_EQ(p2.p0.x, 60);
     CHECK_EQ(p2.p0.y, 42);
     CHECK_EQ(p2.p0.z, -144);
@@ -57,12 +57,12 @@ TEST_CASE("rotor_plane")
 
 TEST_CASE("motor_plane")
 {
-    motor m;
+    kln_motor m;
     m.p1 = vec4(1, 4, -3, 2);
     m.p2 = vec4(8, 5, 6, 7);
-    plane p1;
-    p1.p0    = vec4(2, 3, 4, 5);
-    plane p2 = motor_plane(m, p1);
+    kln_plane p1;
+    p1.p0        = vec4(2, 3, 4, 5);
+    kln_plane p2 = kln_apply(m, p1);
     CHECK_EQ(p2.p0.x, 416);
     CHECK_EQ(p2.p0.y, 42);
     CHECK_EQ(p2.p0.z, -144);
@@ -71,11 +71,11 @@ TEST_CASE("motor_plane")
 
 TEST_CASE("rotor_point")
 {
-    rotor r;
+    kln_rotor r;
     r.p1 = vec4(1, 4, -3, 2);
-    point p1;
-    p1.p3    = vec4(2, 3, 4, 5);
-    point p2 = rotor_point(r, p1);
+    kln_point p1;
+    p1.p3        = vec4(2, 3, 4, 5);
+    kln_point p2 = kln_apply(r, p1);
     CHECK_EQ(p2.p3.x, 60);
     CHECK_EQ(p2.p3.y, 42);
     CHECK_EQ(p2.p3.z, -144);
@@ -84,12 +84,12 @@ TEST_CASE("rotor_point")
 
 TEST_CASE("motor_point")
 {
-    motor m;
+    kln_motor m;
     m.p1 = vec4(1, 4, -3, 2);
     m.p2 = vec4(8, 5, 6, 7);
-    point p1;
-    p1.p3    = vec4(2, 3, 4, 5);
-    point p2 = motor_point(m, p1);
+    kln_point p1;
+    p1.p3        = vec4(2, 3, 4, 5);
+    kln_point p2 = kln_apply(m, p1);
     CHECK_EQ(p2.p3.x, 60);
     CHECK_EQ(p2.p3.y, -238);
     CHECK_EQ(p2.p3.z, -144);
@@ -98,10 +98,10 @@ TEST_CASE("motor_point")
 
 TEST_CASE("motor_origin")
 {
-    motor m;
-    m.p1    = vec4(1, 4, -3, 2);
-    m.p2    = vec4(8, 5, 6, 7);
-    point p = motor_origin(m);
+    kln_motor m;
+    m.p1        = vec4(1, 4, -3, 2);
+    m.p2        = vec4(8, 5, 6, 7);
+    kln_point p = kln_apply(m);
     CHECK_EQ(p.p3.x, 1);
     CHECK_EQ(p.p3.y, -140);
     CHECK_EQ(p.p3.z, 0);