 (defn starting-point [] (map rand space))
 
 
-;; To start off with lets assume that the paint is falling and has 0
-;; velocity of its own when it starts from the brush
-
-
-;; we need to know the amount of time it is going to take the paint to
-;; fall, which we can work out based on the y dimension alone
-
-;; we know the initial position and velocity, final position and
-;; acceleration and we need to find the time. We cant use the equation
-;; r = r0 + v0 * t + at^2/2
-;; we need to use the quadratic equation to solve for t
-;;
-;; rearranged we get
-;;   at^2 + 2v0t + 2r0 - 2r = 0
-;; in quad equation:
-;;   a = a
-;;   b = 2v0
-;;   c = 2r0 - 2r
-;;     r (final position) is always going to be 0 so,
-;;   c = 2r0
+;; Now that we can generate a random point in space we want to project
+;; this to the canvas. We are going to use [Newtonian equations of
+;; motion](http://wiki), we know the position, velocity and acceleration of the
+;; point and we want to know what the position and velocity are when y
+;; is 0. In order to work out final positions we need to know the
+;; total time the point spent falling, we can do this using the y
+;; position as we know that the final position should be 0.
+
+;; To work out the time it takes for the point to reach the canvas we
+;; will solve the following equation for t:
+;;
+;;    - $r$  = final displacement,
+;;    - $r0$ = initial displacement,
+;;    - $v0$ = initial velocity,
+;;    - $a$  = acceleration,
+;;    - $t$  = time.
+;;
+;; $r = r0 + v0 * t + \frac{at^2}{2}$
+;;
+;; This rearranges to:
+;;
+;; $at^2 + 2v0t + 2r0 - 2r = 0$
+;;
+;; We can solve this using the Quadratic Equation, but this will yield
+;; us two results. In general we can say that we are interested in the
+;; result with the maxium value.
+;;
+;; In this function you can see an example of call out to Java.
+;; Clojure doesn't have an inbuilt sqrt function so we are calling out
+;; to the java version. A function named in the form `foo/bar` means
+;; it will call the function `bar` in the namespace `foo`. **WHAT IS A NAMESPACE?**
 
 (defn time-to-canvas [position velocity acceleration]
   (let [a acceleration

  (and (> (impact-force mass velocity) min-impact-force-for-splatter)
       (> (rand) 0.8)))

;; if an impact splatters then we will need to bounce its velocity
;; vector as this is the direction it will exit its current position

;; the equation to bounce a vector, V, off a plane with normal, N, is:
;; needs rewriting http://mathworld.wolfram.com/Reflection.html
;; 
;;  N is the normal vector of the plane
;;  R is the reflected vector
;; 
;;  R = V - (2 * (V.N) * N)

;; dot product is he sum of the multiples of the dimensions

(defn dot-product [vector1 vector2]
  (reduce + (map * vector1 vector2)))

  (map #(* % constant) vector))


;; Using the above functions we can now implement the vector bouncing
;; equation. I have pulled $(2 * (V.N) * N)$ out into a variable
;; called extreme for clarity. **I don't think extreme is a much
;; better name than blah**

(defn bounce-vector [vector normal]
  (let [vector-dot-normal (dot-product vector normal)
        extreme (vector-multiply-by-constant normal (* 2 vector-dot-normal))]
    (vector-subtraction vector extreme)))


;; When an impact splatters it will only take a fraction of the
;; velocity, otherwise know as being elastic rather than inelastic
;; **check these definitions**. We can define a constant that will be
;; used to reduce the total velocity of the bounced vector to reflect
;; this elasticity.

;; **should this splatter vector be randomised a little bit?**

(def splatter-dampening-constant 0.7)

