# Difference between revisions of "Canvas3D JS Library"

## Introduction

The Canvas 3D JS Libary (C3DL) is a javascript library that will make it easier to write 3D applications using canvas 3d. It will provide a set of math, scene, and 3d object classes to make the canvas more accessible for developers that want to develop 3D content in browser.

## People Working On This Project

• Catherine Leung
• Mark Paruzel (CodeBot)
• Andrew Smith

Andrew's patch - this change to the canvas 3D extension allows the "simple" examples from Vlad's page to work with ati cards. This is intended for Windows only. Model viewer examples do not work yet.

• INCOMPLETE

• IN PROGRESS

• IN PROGRESS

## Math Operations

### Vector Class

A Vector basically describes a direction in the form of X, Y, and Z coordinates of a 3D world. Basic 3D math cannot exist without the utilization of spatial coordinates which the Vector Class encapsulates. The Vector Class will have the following members within it:

• Getters
• getX() - Retrieves the X value
• getY() - Retrieves the Y value
• getZ() - Retrieves the Z value
• Setters
• set(newX, newY, newZ) - This sets new (x, y, z) values to the Vector
• setX(newX) - Takes a number value as the new value for X
• setY(newY) - Takes a number value as the new value for Y
• setZ(newZ) - Takes a number value as the new value for Z
• setFromVector(vec) - Takes a Vector object as the new value for this Vector
• Calculations
• normalize() - Unit Normalization
• dot() - Calculates the Dot Product. Returns a number
• length() - Returns the Length of Vector from (0, 0, 0)
• lengthSq() - Returns the Squared value of Length
• cross(vec) - Takes a Vector object and computes the Cross Product between the two values. Returns a Vector object that is the cross of the two
• add(vec) - Takes a Vector object and adds its values to its own
• subtract(vec) - Takes a Vector object and subtracts its values from its own
• multiply(scalar) - Takes a number value and multiplies (x, y, z) by it
• divide(scalar) - Takes a number value and divides (x, y, z) by it
• isEqual(vec) - Takes a Vector object and compares it to its (x, y, z) values. Returns true if they match
• multiplyByQuat(quat) - Takes a Quaternion and multiplies its orientation by (x, y, z). It returns a new Vector orientation

### Matrix Class

A Matrix Class is necessary to provide Matrix operations such as rotation, translation, and scaling to any point in the 3D world. It is composed of a 4x4 matrix of floating point values that can be applied to any Matrix operation. This matrix is stored in Row-Major format, meaning its first 4 values are in the first row. The Matrix Class has the following members:

• Getters
• getMatrix() - Returns an array of 16 numbers. Each value represents a location of the matrix starting at the top left corner (Row-Major)
• Setters
• setMatrix(newMatArray) - Takes an Array of 16 numbers that represent the matrix in Row-Major format
• Calculations
• identity() - Sets the matrix up to be an identity matrix
• transpose() - Transposes the matrix to be in Column-Major format, and vice versa
• inverse() - Calculates the Inverse of the matrix. Returns NULL if it fails, else it returns an inverse matrix
• determinant() - Returns a number that is the Matrices determinant
• multiplyByScalar(scalar) - Multiplies the values of the matrix by a number
• divideByScalar(scalar) - Divides the values of the matrix by a number
• multiplyByMatrix(mat) - Multiplies two matrices together. It returns a new matrix
• multiplyByVector(vec) - Mutiplies the orientation of the matrix by the vector. This function returns the newly oriented Vector
• addMatrix(mat) - Adds the values of two matrices together. It returns a new matrix
• subtractMatrix(mat) - Subtracts the values of the two matrices. It return a new matrix

### Quaternion Class

A Quaternion is a 4-Dimensional representation of an orientation. It consists of a unit-length axis and an angle around that axis. It can function much like an orientation matrix but without the disadvantage of Gimble Lock. The Quaternion is stored as an array of 4 numbers, represented in the order of (w, x, y, z). The Quaternion Class has the following members:

• Getters
• getW() - Returns the numerical W component of the Quaternion
• getX() - Returns the numerical X component of the Quaternion
• getY() - Returns the numerical Y component of the Quaternion
• getZ() - Returns the numerical Z component of the Quaternion
• getMatrix() - Returns a Matrix object that reflects the orientation of the quaternion
• getAxisAngle(axis, angle) - Takes in two values, a Vector object and a Number. Converts the orientation of the quaternion into an axis Vector and an angle around it
• Setters
• setFromQuat(quat) - Sets this Quaternion with the same value as the one being passed in
• setFromMatrix(mat) - Creates a Quaternion orientation from the orientation of the Matrix object that is passed in
• Calculations
• length() - Returns the length of the Quaternion
• lengthSq() - Returns a number that represents the square of this Quaternion's length
• addQuat(quat) - Takes a Quaternion object that will be added to this Quaternion's internal (w, x, y, z) values
• subtractQuat(quat) - Takes a Quaternion object where its values will be subtracted from this Quaternion's (w, x, y, z) values
• multiplQuat(scalar) - Takes a number and multiplies its values by the Quaternion's (w, x, y, z) values
• conjugate() - Returns a Quaternion that is this Quaternion's conjugate
• dot(quat) - Takes a Quaternion and returns the Dot Product of the two
• normalize() - Normalizes the quaternion
• inverse() - Returns the inverse of this Quaternion

## Camera

• INCOMPLETE

• INCOMPLETE

• INCOMPLETE

### Free Camera Class

The Free Camera Class is a camera that can be translated and oriented. It cannot be attached to an item, rather, it can be moved separately by the user. The camera also supports velocities (without friction) that are applied to the object based on time. The Free Camera Class has the following Members:

• Getters
• getPosition() - Returns a Vector Object that represents the position of the Camera
• getUp() - Returns a Vector Object that represents the orientation of Up
• getDir() - Returns a Vector Object that is the direction the camera is facing
• getLeft() - Returns a Vector Object that represents the orientation of Left
• getLinearVel() - Returns a Vector that is the velocity that the camera is traveling at
• getAngularVel() - Returns a Vector that contains the rotation velocity around the local (x, y, z) axis of the camera
• Setters
• setPosition(vec) - Takes a Vector that sets the camera's position
• setLookAtPoint(vec) - Takes a Vector that represents the point the camera will look at
• setUpVector(vec) - Takes a vector that orients the camera Up
• setLinearVel(vec) - Takes a vector that is the camera's linear velocity
• setAngularVec(vec) - Takes a vector that represents the camera's rotational velocity around local (x, y, z) axis
• Other Functions
• rotateOnAxis(axis, angle) - Takes a vector and a number that represents a relative rotation to the camera's orientation
• yaw(angle) - Takes a number that the camera will rotate around its Up vector
• roll(angle) - Takes a number that the camera will rotate around its direction vector
• pitch(angle) - Takes a number that the camera will rotate around its Left vector
• update(timeElapsed) - Takes a number that represents the amount of milliseconds that passed since the last call to update. This function updates the position and rotation based on the set velocities

## TO DO

• get a website (in progress)
• find out about exposing of open gl 1.1 calls
• Should the OpenGL 1.1 calls be exposed to the Canvas3D web2.0 architecture. Mainly, for those functions that make 3D math easy (ie. gluLookAt, glMatrixMode, etc).