README.md

   1 # cl-tuples - A set of macros for auto-generating optimised vector math routines
   2
   3 ## A tuple type declaration auto-generates a number of useful functions, macros, and types.
   4
   5 It is best to give an example.
   6
   7         (def-tuple-type vector2d
   8                 :tuple-element-type short-float
   9                 :initial-element 0.0f0
  10                 :elements (x y))
  11
  12 Will declare a tuple of short-floats, arrays of which are initialised
  13 with the element 0.0f0 and which has two elements, named x and y.
  14
  15 There will be a struct to represent this type, declared as follows:
  16
  17         (defstruct vector2d
  18                 :type vector
  19                 :constructor nil
  20                 (x 0.0f0 :type short-float)
  21                 (y 0.0f0 :type short-float))
  22
  23 i.e. a struct, stored as a vector with elements representing the
  24 elements of the tuple, initialised to the initial-element value of the
  25 tuple.
  26
  27 Literals can be written via the modified read syntax
  28
  29                 #[ vector2d 0.2 1.2 ] => #( 0.2 1.2 )
  30                 #[ vector2d* 0.2 1.2 ] => (values 0.2 1.2)
  31
  32 It is reccomended literals are written with the above syntax as their
  33 expansion will also incorportate type definitions that will be
  34 compatible with the following routines that will be generated to be
  35 able to manipulate them.
  36
  37         (vector2d-values* x y) => (values x y)          ;; convert from args to values
  38         (vector2d* v) => (values (aref v 0) (aref v 1)) ;; covert from array to values
  39         (new-vector2d)                                  ;; returns an empty tuple vector- i.e. #( 0 0 )
  40         (make-vector2d x y)                             ;; returns a vector (struct) as #( x y )
  41         (make-vector2d* (values x y))                   ;; same as the above only with multiple value arguments
  42         (setf (vector2d* v) (values x y) )              ;; generalised set that takes multiple values
  43         (with-vector2d v (i j) ...)                     ;; binds x and y of tuple vector v to i and j in the body
  44         (with-vector2d* (values x y) (i j) ..)          ;; same as the above, only it expects a values form
  45
  46         ;; arrays -- this can create an array  of n vector2ds (eg 4 vector2ds == 8 element array)
  47         (make-vector2d-array dimensons &key adjustable fill-pointer)
  48
  49         (vector2d-aref v  n)                                                ;; treats v as an array of n vector2d's and
  50                                                                                                     ;; returns the nth vector2d as a vector (ie
  51                                                                                                     ;; struct)
  52         (vector2d-aref* v n)                                                    ;; treats v as an array of n vector2d's and returns the
  53                                                                                                     ;; nth vector2 as multiple values
  54
  55         (setf (vector2d-aref v n) #( x y ))             ;; sets the n'tn vector2d in the array v
  56
  57         (setf (vector2d-aref v n) (values x y ))        ;; sets the n'tn vector2d in the array v, expects multiple
  58                                                                                                         ;; value argument
  59
  60      (vector2d-push #( x y ) v)                     ;; push an vector2d into an array of vector2d
  61          (vector2d-push*  (values x y) v)               ;; same as above but with multiple values
  62          (vector2d-push-extend #( x y ) v)              ;; as vector2d-push but admits the possiblity of extension
  63          (vector2d-push-extend* (values x y) v)         ;; same as above but takes multiple value arguments
  64
  65         (vector2d-fill-pointer v)                       ;; returns fill pointer
  66         (setf (vector2d-fill-pointer v) x)              ;; sets fill pointer
  67         (vector2d-array-dimensions v)                   ;; returns number of vector2d's array can hold
  68
  69 In addition a small convienince reader syntax is implemented - #{ x y
  70 z } is equivalent to (values x y z) as client code of this library is
  71 likely to manipulate many multiple values.
  72
  73 Note that the code cl-tuples generates is implementation agnostic: it
  74 is heavily predicated on the assumption that your implementation does
  75 a good job of optimising multiple value calls. If this is not the
  76 case, then the convienence of the array - related functions are
  77 probably the only good reason to use this library.
  78
  79 ## HOWTO
  80
  81 A two-dimensional vector value is created by `MAKE-VECTOR2D`:
  82
  83     > (make-vector2d 1f0 1f0)
  84     #(1.0 1.0)
  85
  86 The type `FAST-FLOAT`, which is used for all float values, is actually a
  87 subtype of `SINGLE-FLOAT`, so make sure to only use values that fit into
  88 that type.
  89
  90 To calculate the length of this vector `VECTOR2D-LENGTH*` can now be
  91 used like this:
  92
  93     > (let ((v (make-vector2d 1f0 1f0)))
  94         (vector2d-length* (vector2d* v)))
  95     1.4142135
  96
  97 By converting the object into a bunch of variables, the macro pipeline
  98 keeps transient objects and function calls away.  The above form thus
  99 expands to something like the following (type declarations and some
 100 other code omitted for clarity):
 101
 102     (LET ((V (MAKE-VECTOR2D 1.0 1.0)))
 103       (MULTIPLE-VALUE-BIND (#:G1764 #:G1765)
 104           (VALUES (AREF V 0) (AREF V 1))
 105         (SYMBOL-MACROLET ((X #:G1764) (Y #:G1765))
 106           (SQRT (+ (* X X) (* Y Y))))))
 107
 108 The coordinates of the vector are bound and made available to the length
 109 calculation code.  If we skip the object creation and go straight the
 110 `VALUES` route, the following is approximately the same as above,
 111 without ever creating a vector object.
 112
 113     > (vector2d-length* (vector2d-values 1.0 1.0))
 114     1.4142135
 115
 116 The reader syntax may be used to the same effect:
 117
 118     > #{1.0 1.0}
 119     1.0
 120     1.0
 121     > (vector2d-length* #{1.0 1.0})
 122     1.4142135
 123
 124 Based on this design more operations are implemented.  See the API and
 125 the tests for details on vectors, vertexes, matrixes and quaternions.
 126
 127 Defining new operators is done via `DEF-TUPLE-OP`, e.g.:
 128
 129     (def-tuple-op scaling-matrix44*
 130         ((sx cl-tuples::fast-float)
 131          (sy cl-tuples::fast-float)
 132          (sz cl-tuples::fast-float))
 133       (:return matrix44
 134                (matrix44-values*
 135                 sx    0.0f0 0.0f0 0.0f0
 136                 0.0f0 sy    0.0f0 0.0f0
 137                 0.0f0 0.0f0 sz    0.0f0
 138                 0.0f0 0.0f0 0.0f0 1.0f0)))
 139
 140 This operator accepts three arguments and creates the obvious matrix
 141 from them.  So lets say, a function has as a conventional argument a
 142 vector of three elements.  Binding each element to a name and applying
 143 the above operator to them gives us the following:
 144
 145     > (let ((v (make-vector3d* #{1f0 1f0 1f0))))
 146         (with-vector3d v (sx sy sz)
 147           (make-matrix44* (scaling-matrix44* sx sy sz)))
 148     #(1.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 0.0 1.0)
 149
 150 The calculated matrix is converted to an actual object to be returned.
 151
 152 ## ASSORTED EXAMPLES
 153
 154     > (let ((v (make-vector2d 1f0 1f0))
 155             (s 2f0))
 156         (vector2d-length* (vector2d-scale* (vector2d* v) s)))
 157     2.828427
 158
 159 # QUATERNIONS
 160
 161 (Adapted from the documentation of cl-quaternion to this API.)
 162
 163 Creating a quaternion from real and imaginary components.  The first
 164 argument is the real part, and the rest are the imaginary components.
 165
 166     > (make-quaternion* (quaternion-values* 10f0 3f0 0f0 0f0))
 167     #(10.0 3.0 0.0 0.0)
 168
 169 Quaternions can be normalized and magnitudes may be computed.
 170
 171     > (make-quaternion* (quaternion-normalize* (quaternion* *)))
 172     #(0.9578263 0.28734788 0.0 0.0)
 173     > (quaternion-mag* (quaternion* *))
 174     1.0
 175
 176 Quaternion addition and multiplication are supported.
 177
 178     > (make-quaternion*
 179        (quaternion-sum* (quaternion-values* 3f0 0f0 0f0 0f0)
 180                         (quaternion-values* 1f0 1f0 0f0 1f0)))
 181     #(4.0 1.0 0.0 1.0)
 182     > (make-quaternion*
 183        (quaternion-dot* (quaternion-values* 3f0 0f0 0f0 0f0)
 184                         (quaternion-values* 1f0 1f0 0f0 1f0)))
 185     #(3.0 0.0 3.0 -3.0)
 186
 187 Unit quaternions may be used to represent rotations.  Functions are
 188 provided for working with quaternions for this purpose.
 189
 190     > (make-quaternion*
 191        (angle-axis-quaternion*
 192         (angle-axis-values* 0f0 0f0 1f0 (coerce (/ pi 2f0) 'single-float))))
 193     #(0.0 0.0 0.70710677 0.70710677)
 194
 195 (`ROTATE-VECTOR-WITH-QUATERNION` and `ROTATE-VECTOR-BY-AXIS-ANGLE`
 196 missing though.)