-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Three-dimensional vectors of doubles with basic operations
--   
--   Simple three-dimensional vectors of doubles with basic vector and
--   matrix operations, supporting <a>Data.Vector.Unboxed</a> and
--   <a>Data.Vector.Storable</a>.
@package simple-vec3
@version 0.6

module Data.Vec3.Class

-- | Three-dimensional vector, with an associated matrix type.
class Vec3 v where {
    
    -- | Associated type for 3×3 matrix.
    data family Matrix v;
}

-- | Origin point <tt>(0, 0, 0)</tt>.
origin :: Vec3 v => v

-- | Construct a new vector from components.
fromXYZ :: Vec3 v => (Double, Double, Double) -> v

-- | Deconstruct a vector into components.
toXYZ :: Vec3 v => v -> (Double, Double, Double)

-- | Zip two vectors elementwise.
zipWith :: Vec3 v => (Double -> Double -> Double) -> v -> v -> v

-- | Add two vectors.
(<+>) :: Vec3 v => v -> v -> v

-- | Subtract two vectors.
(<->) :: Vec3 v => v -> v -> v

-- | Cross product.
(><) :: Vec3 v => v -> v -> v

-- | Scale a vector.
(.^) :: Vec3 v => v -> Double -> v

-- | Dot product.
(.*) :: Vec3 v => v -> v -> Double

-- | Euclidean norm of a vector.
norm :: Vec3 v => v -> Double

-- | Produce unit vector with the same direction as the original one.
normalize :: Vec3 v => v -> v

-- | Distance between two points.
distance :: Vec3 v => v -> v -> Double

-- | Invert the direction of a vector.
invert :: Vec3 v => v -> v

-- | Construct a new matrix from rows.
fromRows :: Vec3 v => (v, v, v) -> Matrix v

-- | Deconstruct a matrix into rows.
toRows :: Vec3 v => Matrix v -> (v, v, v)

-- | Generic vector dot product.
--   
--   Multiply the transpose of the first vector by the given matrix, then
--   multiply the result by the second vector.
--   
--   <pre>
--                       [ a11  a12  a13 ]   [ v2x ]
--                       [               ]   [     ]
--   [ v1x  v1y  v1z ] . [ a21  a22  a23 ] . [ v2y ] = s
--                       [               ]   [     ]
--                       [ a31  a32  a33 ]   [ v2z ]
--   </pre>
dotM :: Vec3 v => v -> v -> Matrix v -> Double

-- | Multiply a matrix and a vector.
--   
--   <pre>
--   [ a11  a12  a13 ]   [ v2x ]   [ rx ]
--   [               ]   [     ]   [    ]
--   [ a21  a22  a23 ] . [ v2y ] = [ ry ]
--   [               ]   [     ]   [    ]
--   [ a31  a32  a33 ]   [ v2z ]   [ rz ]
--   </pre>
mxv :: Vec3 v => Matrix v -> v -> v

-- | Build a diagonal matrix from a number <tt>d</tt>.
--   
--   <pre>
--   [ d  0  0 ]
--   [         ]
--   [ 0  d  0 ]
--   [         ]
--   [ 0  0  d ]
--   </pre>
diag :: Vec3 v => Double -> Matrix v

-- | Transpose a vector and multiply it by another vector, producing a
--   matrix.
--   
--   <pre>
--   [ v1x ]                       [ r11  r12  r13 ]
--   [     ]                       [               ]
--   [ v1y ] . [ v2x  v2y  v2z ] = [ r21  r22  r23 ]
--   [     ]                       [               ]
--   [ v1z ]                       [ r31  r32  r33 ]
--   </pre>
vxv :: Vec3 v => v -> v -> Matrix v

-- | Add two matrices.
addM :: Vec3 v => Matrix v -> Matrix v -> Matrix v
infixl 8 ><
infixl 7 <+>
infixl 7 <->
infixl 9 .^
infixl 8 .*

-- | <a>Vec3</a> implementation with <a>Unbox</a> instance based on default
--   Unbox instance for tuples of arrays, which wraps a vector of tuples as
--   a tuple of vectors.
--   
--   <pre>
--   interface:  [v1 (x, y, z); v2 (x, y, z) ...], length = N
--                    |  |  |       |  |  |
--   storage(x): [v1x-+  |  | ; v2x-+  |  |  ...], length = N
--   storage(y): [v1y----+  | ; v2y----+  |  ...], length = N
--   storage(z): [v1z-------+ ; v2z-------+  ...], length = N
--   </pre>
--   
--   You almost definitely want to use <a>CVec3</a> instead as it has
--   better performance.
type TVec3 = (Double, Double, Double)
instance GHC.Show.Show (Data.Vec3.Class.Matrix Data.Vec3.Class.TVec3)
instance GHC.Classes.Eq (Data.Vec3.Class.Matrix Data.Vec3.Class.TVec3)
instance Test.QuickCheck.Arbitrary.Arbitrary (Data.Vec3.Class.Matrix Data.Vec3.Class.TVec3)
instance Data.Vec3.Class.Vec3 Data.Vec3.Class.TVec3


-- | <a>Vec3</a> class and implementations.
--   
--   The package provides two different implementations for <a>Vec3</a>
--   type class, which differ in storage scheme. Benchmarks are included
--   for both. You most likely want to use <a>CVec3</a> which is based on
--   contiguous storage scheme and offers the best performance.
module Data.Vec3

-- | Three-dimensional vector, with an associated matrix type.
class Vec3 v where {
    
    -- | Associated type for 3×3 matrix.
    data family Matrix v;
}

-- | Origin point <tt>(0, 0, 0)</tt>.
origin :: Vec3 v => v

-- | Construct a new vector from components.
fromXYZ :: Vec3 v => (Double, Double, Double) -> v

-- | Deconstruct a vector into components.
toXYZ :: Vec3 v => v -> (Double, Double, Double)

-- | Zip two vectors elementwise.
zipWith :: Vec3 v => (Double -> Double -> Double) -> v -> v -> v

-- | Add two vectors.
(<+>) :: Vec3 v => v -> v -> v

-- | Subtract two vectors.
(<->) :: Vec3 v => v -> v -> v

-- | Cross product.
(><) :: Vec3 v => v -> v -> v

-- | Scale a vector.
(.^) :: Vec3 v => v -> Double -> v

-- | Dot product.
(.*) :: Vec3 v => v -> v -> Double

-- | Euclidean norm of a vector.
norm :: Vec3 v => v -> Double

-- | Produce unit vector with the same direction as the original one.
normalize :: Vec3 v => v -> v

-- | Distance between two points.
distance :: Vec3 v => v -> v -> Double

-- | Invert the direction of a vector.
invert :: Vec3 v => v -> v

-- | Construct a new matrix from rows.
fromRows :: Vec3 v => (v, v, v) -> Matrix v

-- | Deconstruct a matrix into rows.
toRows :: Vec3 v => Matrix v -> (v, v, v)

-- | Generic vector dot product.
--   
--   Multiply the transpose of the first vector by the given matrix, then
--   multiply the result by the second vector.
--   
--   <pre>
--                       [ a11  a12  a13 ]   [ v2x ]
--                       [               ]   [     ]
--   [ v1x  v1y  v1z ] . [ a21  a22  a23 ] . [ v2y ] = s
--                       [               ]   [     ]
--                       [ a31  a32  a33 ]   [ v2z ]
--   </pre>
dotM :: Vec3 v => v -> v -> Matrix v -> Double

-- | Multiply a matrix and a vector.
--   
--   <pre>
--   [ a11  a12  a13 ]   [ v2x ]   [ rx ]
--   [               ]   [     ]   [    ]
--   [ a21  a22  a23 ] . [ v2y ] = [ ry ]
--   [               ]   [     ]   [    ]
--   [ a31  a32  a33 ]   [ v2z ]   [ rz ]
--   </pre>
mxv :: Vec3 v => Matrix v -> v -> v

-- | Build a diagonal matrix from a number <tt>d</tt>.
--   
--   <pre>
--   [ d  0  0 ]
--   [         ]
--   [ 0  d  0 ]
--   [         ]
--   [ 0  0  d ]
--   </pre>
diag :: Vec3 v => Double -> Matrix v

-- | Transpose a vector and multiply it by another vector, producing a
--   matrix.
--   
--   <pre>
--   [ v1x ]                       [ r11  r12  r13 ]
--   [     ]                       [               ]
--   [ v1y ] . [ v2x  v2y  v2z ] = [ r21  r22  r23 ]
--   [     ]                       [               ]
--   [ v1z ]                       [ r31  r32  r33 ]
--   </pre>
vxv :: Vec3 v => v -> v -> Matrix v

-- | Add two matrices.
addM :: Vec3 v => Matrix v -> Matrix v -> Matrix v
infixl 8 ><
infixl 7 <+>
infixl 7 <->
infixl 9 .^
infixl 8 .*

-- | <a>Vec3</a> implementation with <a>Unbox</a> and <a>Storable</a>
--   instances based on a single contiguous array storage scheme, suitable
--   for use with <a>Data.Vector.Unboxed</a> and
--   <a>Data.Vector.Storable</a>.
--   
--   <pre>
--   interface: [v1 x   y   z  ; v2 x   y   z  ...], length = N = M / 3
--                  |   |   |       |   |   |
--   storage:   [  v1x v2y v2z ;   v2x v2y v2z ...], length = M
--   </pre>
--   
--   This implementation has the best performance.
data CVec3
CVec3 :: !Double -> !Double -> !Double -> CVec3

-- | <a>Vec3</a> implementation with <a>Unbox</a> instance based on default
--   Unbox instance for tuples of arrays, which wraps a vector of tuples as
--   a tuple of vectors.
--   
--   <pre>
--   interface:  [v1 (x, y, z); v2 (x, y, z) ...], length = N
--                    |  |  |       |  |  |
--   storage(x): [v1x-+  |  | ; v2x-+  |  |  ...], length = N
--   storage(y): [v1y----+  | ; v2y----+  |  ...], length = N
--   storage(z): [v1z-------+ ; v2z-------+  ...], length = N
--   </pre>
--   
--   You almost definitely want to use <a>CVec3</a> instead as it has
--   better performance.
type TVec3 = (Double, Double, Double)
instance GHC.Show.Show Data.Vec3.CVec3
instance GHC.Classes.Eq Data.Vec3.CVec3
instance GHC.Show.Show (Data.Vec3.Class.Matrix Data.Vec3.CVec3)
instance GHC.Classes.Eq (Data.Vec3.Class.Matrix Data.Vec3.CVec3)
instance Data.Vec3.Class.Vec3 Data.Vec3.CVec3
instance Data.Vector.Generic.Mutable.Base.MVector Data.Vector.Unboxed.Base.MVector Data.Vec3.CVec3
instance Data.Vector.Generic.Base.Vector Data.Vector.Unboxed.Base.Vector Data.Vec3.CVec3
instance Data.Vector.Unboxed.Base.Unbox Data.Vec3.CVec3
instance Foreign.Storable.Storable Data.Vec3.CVec3
instance Test.QuickCheck.Arbitrary.Arbitrary Data.Vec3.CVec3
instance Test.QuickCheck.Arbitrary.Arbitrary (Data.Vec3.Class.Matrix Data.Vec3.CVec3)