gml 1.1.0

// Copyright 2015 Creekware Inc. See the COPYRIGHT
// file at the top-level directory of this distribution.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.

//! Defines functions that generate common transformation matricies.
//!
//! The matricies generated by this crate use standard OpenGL fixed-function conventions.
//! For example, the look_at() function generates a transform from world space into the
//! specified eye space that the projective matrix functions (perspective, ortho, etc)
//! are designed to excpect.  The OpenGL compatibility specifications defines the particular
//! layout of this eye space.

use num::traits::*;
use std::f32;
use vector::*;
use matrix::*;


/// Creates a 4x4 matrix for an orthographic parallel viewing volume with z bounds.
///
/// ```
/// use gml::*;
///
/// let r = ortho_z(0.0, 800.0, 0.0, 600.0, -100.0, 100.0);
///
/// let e = Matrix4x4::new( 0.0025,  1.0     ,  1.0 , 1.0,
///                         1.0   ,  0.003333,  1.0 , 1.0,
///                         1.0   ,  1.0     , -0.01, 1.0,
///                        -1.0   , -1.0     ,  0.0 , 1.0 );
///
/// assert!(r.eq_approx(e, 1e-5));
/// ```
pub fn ortho_z<T:Copy + Float>(left:T, right:T, bottom:T, top:T, z_near:T, z_far:T) -> Matrix4x4<T> {
    let mut result = Matrix4x4::one();
    let two = T::one() + T::one();
    result[0][0] = two / (right - left);
    result[1][1] = two / (top - bottom);
    result[2][2] = - two / (z_far - z_near);
    result[3][0] = - (right + left) / (right - left);
    result[3][1] = - (top + bottom) / (top - bottom);
    result[3][2] = - (z_far + z_near) / (z_far - z_near);
    return result;
}

/// Creates a 4x4 matrix for an orthographic parallel viewing volume.
///
/// ```
/// use gml::*;
///
/// let r = ortho(0.0, 800.0, 0.0, 600.0);
///
/// let e = Matrix4x4::new( 0.0025,  1.0     ,  1.0 , 1.0,
///                         1.0   ,  0.003333,  1.0 , 1.0,
///                         1.0   ,  1.0     , -1.0 , 1.0,
///                        -1.0   , -1.0     ,  1.0 , 1.0 );
///
/// assert!(r.eq_approx(e, 1e-5));
/// ```
pub fn ortho<T:Copy + Float>(left:T, right:T, bottom:T, top:T) -> Matrix4x4<T> {
    let mut result = Matrix4x4::one();
    let two = T::one() + T::one();
    result[0][0] = two / (right - left);
    result[1][1] = two / (top - bottom);
    result[2][2] = - T::one();
    result[3][0] = - (right + left) / (right - left);
    result[3][1] = - (top + bottom) / (top - bottom);
    return result;
}

/// Creates a frustum matrix.
///
/// ```
/// use gml::*;
///
/// let r = frustum(3.0, 600.0, -2.0, 540.0, -100.0, 100.0);
/// let e = Matrix4x4::new(-0.335008, 0.0      , 0.0  , 0.0,
///                         0.0     , -0.369004, 0.0  , 0.0,
///                         1.01005 , 0.99262  , 0.0  ,-1.0,
///                         0.0     , 0.0      , 100.0, 0.0 );
/// assert!(r.eq_approx(e, 1e-5));
/// ```
pub fn frustum<T:Copy + Float>(left:T, right:T, bottom:T, top:T, near:T, far:T) -> Matrix4x4<T> {
    let mut result = Matrix4x4::zero();
    let two = T::one() + T::one();
    result[0][0] = (two * near) / (right - left);
    result[1][1] = (two * near) / (top - bottom);
    result[2][0] = (right + left) / (right - left);
    result[2][1] = (top + bottom) / (top - bottom);
    result[2][2] = -(far + near) / (far - near);
    result[2][3] = - T::one();
    result[3][2] = -(two * far * near) / (far - near);
    return result;
}

/// Creates a matrix for a symetric perspective-view frustum.
///
/// _fovy_
/// :    Specifies the field of view angle in the y direction.  Expressed in radians.
///
/// _aspect_
/// :    Specifies the aspect ratio that determines the field of view in the x direction.
///      The aspect ratio is the ratio of the x (width) to y (height).
///
/// _near_
/// :    Specifies the distance from the viewer to the near clipping plane (always positive).
///
/// _far_
/// :    Specifies the distance from the viewer to the far clipping plane (always positive).
///
/// ```
/// use gml::*;
///
/// let r = perspective(3.14/7.0, 16.0/9.0, 80.0, 10.0);
/// let e = Matrix4x4::new( 2.465767, 0.0    , 0.0  , 0.0,
///                         0.0    , 4.383585, 0.0  , 0.0,
///                         0.0    , 0.0    , 1.285714, -1.0,
///                         0.0    , 0.0    , 22.857143, 0.0 );
/// assert!(r.eq_approx(e, 1e-5));
/// ```
pub fn perspective<T:Copy + Float>(fovy:T, aspect:T, z_near:T, z_far:T) -> Matrix4x4<T> {
    assert!(aspect.abs() > T::zero());

    let mut result = Matrix4x4::zero();
    let two = T::one() + T::one();

    let tan_half_fovy = (fovy / two).tan();

    result[0][0] = T::one() / (aspect * tan_half_fovy);
    result[1][1] = T::one() / (tan_half_fovy);
    result[2][2] = - (z_far + z_near) / (z_far - z_near);
    result[2][3] = - T::one();
    result[3][2] = - (two * z_far * z_near) / (z_far - z_near);
    
    return result;
}

/// Creates a perspective projection matrix based on a field of view.
///
/// _fovy_
/// :   Specifies the field of view angle in the y direction.  Expressed in radians.
///
/// _width_
/// :  Width of the view.
///
/// _height_
/// : Height of the view.
///
/// _near_
/// :   Specifies the distance from the viewer to the near clipping plane (always positive).
///
/// _far_
/// :    Specifies the distance from the viewer to the far clipping plane (always positive).
///
/// ```
/// use gml::*;
///
/// let r = perspective_fov(3.14/7.0, 160.0, 90.0, 80.0, 10.0);
/// let e = Matrix4x4::new( 2.465767, 0.0    , 0.0  , 0.0,
///                         0.0    , 4.383585, 0.0  , 0.0,
///                         0.0    , 0.0     , 1.285714, -1.0,
///                         0.0    , 0.0     , 22.857143, 0.0 );
/// assert!(r.eq_approx(e, 1e-5));
/// ```
pub fn perspective_fov<T:Copy + Float>(fov:T, width:T, height:T, z_near:T, z_far:T) -> Matrix4x4<T> {
    assert!(width > T::zero());
    assert!(height > T::zero());
    assert!(fov > T::zero());
    
    let mut result = Matrix4x4::zero();
    let two = T::one() + T::one();
    let half = T::one() / two;

    let rad = fov;
    let h = (half * rad).cos() / (half * rad).sin();
    let w = h * height / width;

    result[0][0] = w;
    result[1][1] = h;
    result[2][2] = - (z_far + z_near) / (z_far - z_near);
    result[2][3] = - T::one();
    result[3][2] = - (two * z_far * z_near) / (z_far - z_near);
    return result;
}

/// Creates a matrix for a symmetric perspective-view frustum with far plane at infinite.
///
/// _fovy_
/// :    Specifies the field of view angle in the y direction.  Expressed in radians.
///
/// _aspect_
/// :    Specifies the aspect ratio that determines the field of view in the x direction.
///      The aspect ratio is the ratio of the x (width) to y (height).
///
/// _near_
/// :    Specifies the distance from the viewer to the near clipping plane (always positive).
///
/// ```
/// use gml::*;
///
/// let r = infinite_perspective(3.14/7.0, 16.0/9.0, 80.0);
/// let e = Matrix4x4::new( 2.465767, 0.0    , 0.0  , 0.0,
///                         0.0    , 4.383585, 0.0  , 0.0,
///                         0.0    , 0.0     , -1.0  , -1.0,
///                         0.0    , 0.0     , -160.0  , 0.0 );
/// assert!(r.eq_approx(e, 1e-5));
/// ```
pub fn infinite_perspective<T:Copy + Float>(fovy:T, aspect:T, z_near:T) -> Matrix4x4<T> {
    
    let mut result = Matrix4x4::zero();
    let two = T::one() + T::one();

    let range = (fovy / two).tan() * z_near;
    let left = -range * aspect;
    let right = range * aspect;
    let bottom = -range;
    let top = range;

    result[0][0] = (two * z_near) / (right - left);
    result[1][1] = (two * z_near) / (top - bottom);
    result[2][2] = - T::one();
    result[2][3] = - T::one();
    result[3][2] = - two * z_near;
    return result;
}

/// Creates a matrix for a symmetric perspective-view frustum with far plane at infinite
/// for graphics hardware that doesn't support depth clamping, with espilon.
///
/// _fovy_
/// :    Specifies the field of view angle in the y direction.  Expressed in radians.
///
/// _aspect_
/// :    Specifies the aspect ratio that determines the field of view in the x direction.
///      The aspect ratio is the ratio of x (width) to y (height).
///
/// _near_
/// :    Specifies the distance from the viewer to the near clipping plane (always positive).
///
/// _ep_
/// :    Epsilon value
///
/// Infinite projection matrix: http://www.terathon.com/gdc07_lengyel.pdf
///
/// ```
/// use gml::*;
///
/// let r = tweaked_infinite_perspective_ep(3.14/1.75, 16.0/9.0, 100.0, 1e-5);
///
/// let e = Matrix4x4::new(0.448998, 0.0, 0.0, 0.0,
///                        0.0, 0.798218, 0.0, 0.0,
///                        0.0, 0.0, -0.99999, -1.0,
///                        0.0, 0.0, -199.999, 0.0 );
/// assert!(r.eq_approx(e, 1e-3));
/// ```
pub fn tweaked_infinite_perspective_ep<T:Copy + Float>(fovy:T, aspect:T, z_near:T, ep:T) -> Matrix4x4<T> {
    let mut result = Matrix4x4::zero();
    let two = T::one() + T::one();

    let range = (fovy / two).tan() * z_near;        
    let left = -range * aspect;
    let right = range * aspect;
    let bottom = -range;
    let top = range;

    result[0][0] = (two * z_near) / (right - left);
    result[1][1] = (two * z_near) / (top - bottom);
    result[2][2] = ep - T::one();
    result[2][3] = - T::one();
    result[3][2] = (ep - two) * z_near;
    return result;
}

/// Creates a matrix for a symmetric perspective-view frustum with far plane at infinite
/// for graphics hardware that doesn't support depth clamping.
///
/// _fovy_
/// :    Specifies the field of view angle in the y direction.  Expressed in radians.
///
/// _aspect_
/// :    Specifies the aspect ratio that determines the field of view in the x direction.
///      The aspect ratio is the ratio of x (width) to y (height).
///
/// _near_
/// :    Specifies the distance from the viewer to the near clipping plane (always positive).
///
/// ```
/// use gml::*;
///
/// let r = tweaked_infinite_perspective(3.14/1.75, 16.0/9.0, 100.0);
///
/// let e = Matrix4x4::new(0.448998, 0.0, 0.0, 0.0,
///                        0.0, 0.798218, 0.0, 0.0,
///                        0.0, 0.0, -0.99999, -1.0,
///                        0.0, 0.0, -199.999, 0.0 );
/// assert!(r.eq_approx(e, 1e-3));
/// ```
pub fn tweaked_infinite_perspective<T:Copy + Float>(fovy:T, aspect:T, z_near:T) -> Matrix4x4<T> {
    tweaked_infinite_perspective_ep(fovy, aspect, z_near, T::from(f32::EPSILON).unwrap())
}

/// Map the specified object coordinates (obj.x, obj.y, obj.z) into window coordinates
///
/// _obj_
/// :    Specify the object coordinates.
///
/// _model_
/// :    Specifies the current modelview matrix.
///
/// _proj_
/// :    Specifies the current projection matrix.
///
/// _viewport_
/// :    Specifies the current viewport.
///
/// ```
/// use gml::*;
///
/// let obj = Vector3::new(10.0, 20.0, 30.0);
///
/// let model    = Matrix4::new(-3.0,-1.0,-5.0, 2.0,
///                              4.0, 4.0, 1.0, 9.0,
///                              9.0, 2.0, 5.0, 4.0,
///                              3.0, 2.0, 0.5, 1.5 );
///
/// let proj     = Matrix4::new( 3.0, 2.0, 5.0, 7.0,
///                              0.5, 1.5, 2.5, 3.5,
///                              4.5, 5.5, 6.0, 4.0,
///                              0.5, 9.5, 8.5, 2.5 );
///
/// let viewport = Vector4::new( 5.5, 1.5, 0.5, 4.5 );
///
/// let r = project(obj, model, proj, viewport);
///
/// let e = Vector3::new( 5.858388, 6.309963, 1.17362 );
///
/// assert!(r.eq_approx(e, 1e-5));
/// ```
pub fn project<T:Copy + Float>(obj:Vector3<T>, model:Matrix4<T>, proj:Matrix4<T>, viewport:Vector4<T>) ->Vector3<T> {
    let half = T::one() / (T::one() + T::one());
    
    let mut tmp = Vector4::new( obj[0], obj[1], obj[2], T::one() );
    tmp = model * tmp;
    tmp = proj * tmp;

    tmp = tmp / tmp.w;
    tmp = tmp * half + half;
    tmp[0] = tmp[0] * viewport[2] + viewport[0];
    tmp[1] = tmp[1] * viewport[3] + viewport[1];

    return Vector3{x:tmp[0], y:tmp[1], z:tmp[2]};
}

/// Map the specified window coordinates (obj.x, obj.y, obj.z) into object coordinates
///
/// _obj_
/// :    Specify the object coordinates.
///
/// _model_
/// :    Specifies the current modelview matrix.
///
/// _proj_
/// :    Specifies the current projection matrix.
///
/// _viewport_
/// :    Specifies the current viewport.
///
/// ```
/// use gml::*;
///
/// let obj = Vector3::new( 5.858388, 6.309963, 1.17362 );
///
/// let model    = Matrix4::new(-3.0,-1.0,-5.0, 2.0,
///                              4.0, 4.0, 1.0, 9.0,
///                              9.0, 2.0, 5.0, 4.0,
///                              3.0, 2.0, 0.5, 1.5 );
///
/// let proj     = Matrix4::new( 3.0, 2.0, 5.0, 7.0,
///                              0.5, 1.5, 2.5, 3.5,
///                              4.5, 5.5, 6.0, 4.0,
///                              0.5, 9.5, 8.5, 2.5 );
///
/// let viewport = Vector4::new( 5.5, 1.5, 0.5, 4.5 );
///
/// let r = unproject(obj, model, proj, viewport);
///
/// let e = Vector3::new(9.983053, 19.971006, 29.953223 );
///
/// assert!(r.eq_approx(e, 1e-5));
/// ```
pub fn unproject<T:Copy + Float>(win:Vector3<T>, model:Matrix4<T>, proj:Matrix4<T>, viewport:Vector4<T>) -> Vector3<T> {
    let two = T::one() + T::one();
    let inverse = (proj * model).inverse();

    let mut tmp = Vector4::new( win[0], win[1], win[2], T::one() );
    tmp[0] = (tmp[0] - viewport[0]) / viewport[2];
    tmp[1] = (tmp[1] - viewport[1]) / viewport[3];
    tmp = tmp * two - T::one();

    let mut obj = inverse * tmp;
    obj = obj / obj.w;

    return Vector3::new( obj[0], obj[1], obj[2] );
}

/// Define a picking region
///
/// ```
/// use gml::*;
///
/// let center = Vector2::new(10.0, 20.0);
/// let delta  = Vector2::new( 3.0,  7.0);
/// let viewport = Vector4::new(5.0, 11.0, 23.0, 6.0);
///
/// let r = pick_matrix(center, delta, viewport);
///
/// let e = Matrix4::new( 7.666667, 7.666667, 7.666667, 7.666667,
///                       0.857143, 0.857143, 0.857143, 0.857143,
///                       1.0     , 1.0     , 1.0     , 1.0     ,
///                       3.619048, 3.619048, 3.619048, 3.619048 );
///
/// assert!(r.eq_approx(e, 1e-5));
/// ```
pub fn pick_matrix<T:Copy + Float>(center:Vector2<T>, delta:Vector2<T>, viewport:Vector4<T>) -> Matrix4x4<T> {
    assert!(delta.x > T::zero() && delta.y > T::zero());

    let mut result = Matrix4x4::one();
    let two = T::one() + T::one();

    if !(delta.x > T::zero() && delta.y > T::zero()) {
        return result; // Error
    }

    let temp = Vector3{x: (viewport[2] - two * (center.x - viewport[0])) / delta.x,
                       y: (viewport[3] - two * (center.y - viewport[1])) / delta.y,
                       z:  T::zero() };

    // Translate and scale the picked region to the entire window
    result = result.translate(temp);
    return result.scale(Vector3::new(viewport[2] / delta.x, viewport[3] / delta.y, T::one()));
}

/// Build a look at view matrix.
///
/// _eye_
/// :    Position of the camera.
///
/// _center_
/// :    Position where the camera is looking at
///
/// _up_
/// :    Normalized up vector, how the camera is orientated.  Typically (0, 0, 1).
///
/// ```
/// use gml::*;
///
/// let eye    = Vector3::new(10.0, 20.0, 30.0);
/// let center = Vector3::new( 5.0, 15.0, 22.0);
/// let up     = Vector3::new( 0.0, 0.6, 0.8);
///
/// let r = look_at(eye, center, up);
///
/// let e = Matrix4::new( 0.157991, -0.869334, 0.468293, 1.0,
///                       0.789953,  0.395824, 0.468293, 1.0,
///                      -0.592464,  0.295943, 0.749269, 1.0,
///                       0.394976, -8.101448,-36.526847,1.0 );
/// assert!(r.eq_approx(e, 1e-5));
/// ```
pub fn look_at<T:Copy + Float>(eye:Vector3<T>, center:Vector3<T>, up:Vector3<T>) -> Matrix4x4<T> {
    let f = (center - eye).normalize();
    let s = f.cross(up).normalize();
    let u = s.cross(f);

    let mut result = Matrix4x4::one();
    result[0][0] = s.x;
    result[1][0] = s.y;
    result[2][0] = s.z;
    result[0][1] = u.x;
    result[1][1] = u.y;
    result[2][1] = u.z;
    result[0][2] =-f.x;
    result[1][2] =-f.y;
    result[2][2] =-f.z;
    result[3][0] =-s.dot(eye);
    result[3][1] =-u.dot(eye);
    result[3][2] = f.dot(eye);
    return result;
}