star-3dut

commit a67c5de5e1129793942c5b577a0288e84f7d97aa
parent 15b9d9c742254f4a2c596f7b0b1a1e821a5f896c
Author: Vincent Forest <vincent.forest@meso-star.com>
Date:   Fri, 13 Oct 2017 11:10:32 +0200

Comment the super shape

Diffstat:
M
src/s3dut.h
 | 
14
+++++++++++++-
M
src/s3dut_super_shape.c
 | 
5
++++-

2 files changed, 17 insertions(+), 2 deletions(-)
diff --git a/src/s3dut.h b/src/s3dut.h
@@ -45,6 +45,8 @@ struct s3dut_mesh_data {
   size_t nprimitives; /* # primitives */
 };
 
+/* Defines the radius 'r' with respect the an angle 'a':
+ * r(a) = ( |cos(M*a/4)/A)|^N1 + |sin(M*a/4)/B|^N2 )^{-1/N0} */
 struct s3dut_super_formula {
   double A;
   double B;
@@ -202,7 +204,17 @@ s3dut_create_thick_truncated_sphere
    const int cap_mask, /* Combination of s3dut_cap_flag. Ignored if no clamp */
    struct s3dut_mesh** sphere);
 
-/* TODO comment */
+/* Create a triangulated super shape centered in 0 and discretized in `nslices'
+ * around the Z axis and `nstacks' along the Z axnis. Face vertices are CCW
+ * ordered with respect to the center of the super shape.
+ *
+ * Assuming a point with the spherical coordinates {r, theta, phi} - with r the
+ * radius of the sphere, theta in [-PI,2PI] and phi in [-PI/2, PI/2] - the
+ * corresponding 3D coordinates onto the super shape is obtained by evaluating
+ * the following relations:
+ *    x = r0(theta)*cos(theta) * r1(phi)*cos(phi)
+ *    y = r0(theta)*sin(theta) * r1(phi)*cos(phi)
+ *    z = r1(phi)*sin(phi) */
 S3DUT_API res_T
 s3dut_create_super_shape
   (struct mem_allocator* allocator, /* May be NULL <=> use default allocator */
diff --git a/src/s3dut_super_shape.c b/src/s3dut_super_shape.c
@@ -35,6 +35,9 @@ cartesian_to_spherical(const double* xyz, struct spherical* spherical)
   ASSERT(spherical && xyz);
   spherical->r = d3_len(xyz);
   spherical->phi = asin(xyz[2]/spherical->r);
+  /* Map the atan results in [-PI, PI] to ensure that theta lies in [-PI,2PI]
+   * rather than [-PI/2, 3PI/2] that would violate the super formula
+   * constraints */
   spherical->theta = xyz[0] == 0 ? PI/2 : atan(xyz[1]/xyz[0]) - PI/2;
   if(xyz[0] < 0) spherical->theta += PI;
 }
@@ -76,7 +79,7 @@ s3dut_create_super_shape
   res = s3dut_create_sphere(allocator, radius, nslices, nstacks, &sshape);
   if(res != RES_OK) goto error;
 
-  /* Positionned the sphere vertices wrt to the super formulas */
+  /* Positioned the sphere vertices wrt to the super formulas */
   nverts = darray_double_size_get(&sshape->coords) / 3u;
   FOR_EACH(ivert, 0, nverts) {
     double* pos = darray_double_data_get(&sshape->coords) + ivert*3;