## Libraries.Game.Graphics.PerspectiveCamera Documentation

*Inherits from: *Libraries.Language.Object, Libraries.Game.Graphics.Camera

## Summary

### Actions Summary Table

Actions | Description |
---|---|

Compare(Libraries.Language.Object object) | This action compares two object hash codes and returns an integer. |

Equals(Libraries.Language.Object object) | This action determines if two objects are equal based on their hash code values. |

GetCombinedMatrix() | This action returns a matrix containing the combined values of the camera's projection and view matrices. |

GetDirection() | This action will return the current direction of the Camera. |

GetFar() | This action will return the distance to the far clipping plane of the camera. |

GetFieldOfView() | This action will return the field of view of the camera to the given angle. |

GetFrustum() | This action returns a frustum containing the area visible to the camera. |

GetHashCode() | This action gets the hash code for an object. |

GetHeight() | This action will return the effective height of the camera lens. |

GetInverseCombinedMatrix() | This action returns a matrix containing the inversed combined projection and view matrices. |

GetNear() | This action will return the distance to the near clipping plane of the camera. |

GetPickRay(number screenX, number screenY) | GetPickRay will return a ray that begins at the given screen coordinates and points in the direction that the camera is viewing. |

GetPickRay(number screenX, number screenY, number viewportX, number viewportY, number viewportWidth, number viewportHeight) | GetPickRay will return a ray that begins at the given screen coordinates and points in the direction that the camera is viewing. |

GetPosition() | This action will return the current position of the Camera. |

GetProjectionMatrix() | This action returns the calculated projection matrix of the Camera. |

GetUp() | This action will return the direction that the camera considers to be up. |

GetViewMatrix() | This action returns the calculated view matrix of the camera. |

GetWidth() | This action will return the effective width of the camera lens. |

GetZoom() | The GetZoom action returns the current level of zoom used by the camera. |

Initialize(number field, number viewportWidth, number viewportHeight) | Initializes the camera by giving an angle in degrees to represent the field of view, as well as the width and height for the camera to show in virtual space. |

LookAt(Libraries.Compute.Vector3 target) | This action will angle the camera to look at the given point in 3D space. |

LookAt(number x, number y, number z) | This action will angle the camera to look at the given point in 3D space. |

Move(Libraries.Compute.Vector3 vector) | This action moves the camera on the x, y, and z planes by the amounts stored in the given Vector3. |

Move(number x, number y, number z) | This action moves the camera by the given amounts on the x, y, and z planes, respectively. |

Rotate(Libraries.Compute.Quaternion quaternion) | This action rotates the camera the given number of degrees around the axis given as a 3D vector. |

Rotate(Libraries.Compute.Vector3 axis, number degrees) | This action rotates the camera the given number of degrees around the axis given as a 3D vector. |

Rotate(number axisX, number axisY, number axisZ, number degrees) | This action rotates the camera the given number of degrees clockwise around an axis. |

Rotate(Libraries.Compute.Matrix4 transform) | This action rotates the camera using the rotational information stored in a Matrix4 object. |

RotateAround(Libraries.Compute.Vector3 point, Libraries.Compute.Vector3 axis, number degrees) | This action will rotate the camera clockwise around the given point, with the camera's rotation being about the given axis. |

ScreenToWorldCoordinates(Libraries.Compute.Vector3 coords) | This action will translate a point given in screen coordinates to the world space. |

ScreenToWorldCoordinates(Libraries.Compute.Vector3 coords, number viewportX, number viewportY, number viewportWidth, number viewportHeight) | This action will translate a point given in screen coordinates to the world space. |

ScreenToWorldCoordinates(number x, number y) | This action will translate a point given in screen coordinates to the world space. |

ScreenToWorldCoordinates(number x, number y, boolean useNearPlane) | This action will translate a point given in screen coordinates to the world space. |

SetDirection(number x, number y, number z) | This action will set the direction of the Camera. |

SetDirection(Libraries.Compute.Vector3 newDirection) | This action will set the direction of the Camera. |

SetFar(number value) | This action will set the distance to the far clipping plane of the camera. |

SetFieldOfView(number angle) | This action will set the field of view of the camera to the given angle. |

SetHeight(number height) | This action will set the effective height of the camera lens. |

SetNear(number value) | This action will set the distance to the near clipping plane of the camera. |

SetPosition(Libraries.Compute.Vector3 newPosition) | This action will set the position of the Camera. |

SetPosition(number x, number y, number z) | This action will set the position of the Camera. |

SetSize(number width, number height) | This action will set the effective width and height of the camera lens. |

SetUp(number x, number y, number z) | This action will set the direction that the camera considers to be up. |

SetUp(Libraries.Compute.Vector3 newUp) | This action will set the direction that the camera considers to be up. |

SetWidth(number width) | This action will set the effective width of the camera lens. |

SetYawPitchRoll(number yaw, number pitch, number roll) | The SetYawPitchRoll action sets the direction and orientation of the Camera using yaw, pitch, and roll angles. |

SetZoom(number zoom) | The SetZoom action will set the zoom level of the camera. |

Transform(Libraries.Compute.Matrix4 transform) | This action will transform the position, direction, and up vector of this camera by the given matrix. |

Update() | This action recalculates the camera's position and data. |

WorldToScreenCoordinates(number x, number y, number z) | This action will return the screen coordinates of a point in the world space. |

WorldToScreenCoordinates(Libraries.Compute.Vector3 coords) | This action will return the screen coordinates of a point in the world space. |

WorldToScreenCoordinates(Libraries.Compute.Vector3 coords, number viewportX, number viewportY, number viewportWidth, number viewportHeight) | This action will return the screen coordinates of a point in the world space. |

## Actions Documentation

### Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns an integer. The result is larger if this hash code is larger than the object passed as a parameter, smaller, or equal. In this case, -1 means smaller, 0 means equal, and 1 means larger. This action was changed in Quorum 7 to return an integer, instead of a CompareResult object, because the previous implementation was causing efficiency issues.

**Example Code**

```
Object o
Object t
integer result = o:Compare(t) //1 (larger), 0 (equal), or -1 (smaller)
```

#### Parameters

- Libraries.Language.Object: The object to compare to.

#### Return

integer: The Compare result, Smaller, Equal, or Larger.

### Equals(Libraries.Language.Object object)

This action determines if two objects are equal based on their hash code values.

**Example Code**

```
use Libraries.Language.Object
use Libraries.Language.Types.Text
Object o
Text t
boolean result = o:Equals(t)
```

#### Parameters

- Libraries.Language.Object: The to be compared.

#### Return

boolean: True if the hash codes are equal and false if they are not equal.

### GetCombinedMatrix()

This action returns a matrix containing the combined values of the camera's projection and view matrices. This is primarily used internally by the engine for calculations.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Matrix4
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
Matrix4 combined = cam:GetCombinedMatrix()
end
action Update(number seconds)
end
end
```

#### Return

Libraries.Compute.Matrix4: The combined projection and view Matrix of the Camera.

### GetDirection()

This action will return the current direction of the Camera. The direction is returned as a Vector3 object. This is a reference to the actual Vector3 used by the Camera, so changes to the vector will effect the Camera.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
Vector3 direction = cam:GetDirection()
output "The default 3D camera direction is " + direction:GetX()
+ ", " + direction:GetY() + ", " + direction:GetZ()
end
action Update(number seconds)
end
end
```

#### Return

Libraries.Compute.Vector3: The Vector3 used by this Camera to store its direction.

### GetFar()

This action will return the distance to the far clipping plane of the camera. Objects that are farther than the distance to the far clipping plane will not be seen by the camera.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
output "The default distance to the far clipping plane of the 3D camera is " + cam:GetFar()
end
action Update(number seconds)
end
end
```

#### Return

number: The distance to the far clipping plane of the Camera.

### GetFieldOfView()

This action will return the field of view of the camera to the given angle. The field of view is measured in degrees.

#### Return

number:

### GetFrustum()

This action returns a frustum containing the area visible to the camera.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Frustum
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
Frustum frustum = cam:GetFrustum()
end
action Update(number seconds)
end
end
```

#### Return

Libraries.Compute.Frustum: The frustum that contains the Camera's visible area.

### GetHashCode()

This action gets the hash code for an object.

**Example Code**

```
Object o
integer hash = o:GetHashCode()
```

#### Return

integer: The integer hash code of the object.

### GetHeight()

This action will return the effective height of the camera lens.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
output "The default height of the 3D camera is " + cam:GetHeight()
end
action Update(number seconds)
end
end
```

#### Return

number: The height of the Camera lens.

### GetInverseCombinedMatrix()

This action returns a matrix containing the inversed combined projection and view matrices. This is primarily used internally by the engine for calculations.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Matrix4
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
Matrix4 inverse = cam:GetInverseCombinedMatrix()
end
action Update(number seconds)
end
end
```

#### Return

Libraries.Compute.Matrix4: The inverse of the combined projection and view Matrices of the Camera.

### GetNear()

This action will return the distance to the near clipping plane of the camera. Objects that are closer than the distance to the near clipping plane will not be seen by the camera.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
output "The default distance to the near clipping plane of the 3D camera is " + cam:GetNear()
end
action Update(number seconds)
end
end
```

#### Return

number: The distance to the near clipping plane of the Camera.

### GetPickRay(number screenX, number screenY)

GetPickRay will return a ray that begins at the given screen coordinates and points in the direction that the camera is viewing. The Ray's position will be in world coordinates.

#### Parameters

#### Return

### GetPickRay(number screenX, number screenY, number viewportX, number viewportY, number viewportWidth, number viewportHeight)

GetPickRay will return a ray that begins at the given screen coordinates and points in the direction that the camera is viewing. The Ray's position will be in world coordinates. This action will calculate the point using the given position and dimensions of the viewport.

#### Parameters

#### Return

### GetPosition()

This action will return the current position of the Camera. The position is returned as a Vector3 object containing the current x, y, and z coordinates. This is a reference to the actual Vector3 used by the Camera, so changes to the vector will effect the Camera.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
Vector3 position = cam:GetPosition()
output "The default 3D camera position is " + position:GetX()
+ ", " + position:GetY() + ", " + position:GetZ()
end
action Update(number seconds)
end
end
```

#### Return

Libraries.Compute.Vector3: The Vector3 used by the Camera to store its position.

### GetProjectionMatrix()

This action returns the calculated projection matrix of the Camera. This is primarily used internally by the engine for calculations.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Matrix4
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
Matrix4 projection = cam:GetProjectionMatrix()
end
action Update(number seconds)
end
end
```

#### Return

Libraries.Compute.Matrix4: The projection Matrix of the Camera.

### GetUp()

This action will return the direction that the camera considers to be up. The returned Vector3 indicates the direction that the top of the camera faces out towards. This is a reference to the actual Vector3 used by the Camera, so changes to the vector will effect the Camera.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
Vector3 up = cam:GetUp()
output "The default 3D camera up direction is " + up:GetX()
+ ", " + up:GetY() + ", " + up:GetZ()
end
action Update(number seconds)
end
end
```

#### Return

Libraries.Compute.Vector3: The Vector3 used by the Camera to store the "up" direction.

### GetViewMatrix()

This action returns the calculated view matrix of the camera. This is primarily used internally by the engine for calculations.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Matrix4
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
Matrix4 view = cam:GetViewMatrix()
end
action Update(number seconds)
end
end
```

#### Return

Libraries.Compute.Matrix4: The view Matrix of the Camera.

### GetWidth()

This action will return the effective width of the camera lens.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
output "The default width of the 3D camera is " + cam:GetWidth()
end
action Update(number seconds)
end
end
```

#### Return

number: The width of the Camera lens.

### GetZoom()

The GetZoom action returns the current level of zoom used by the camera. The default value is 1.

#### Return

number:

### Initialize(number field, number viewportWidth, number viewportHeight)

Initializes the camera by giving an angle in degrees to represent the field of view, as well as the width and height for the camera to show in virtual space.

#### Parameters

### LookAt(Libraries.Compute.Vector3 target)

This action will angle the camera to look at the given point in 3D space.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Layer2D
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.Camera
use Libraries.Game.Graphics.AmbientLight
use Libraries.Game.Graphics.DirectionalLight
use Libraries.Compute.Vector3
class Main is Game
Vector3 target
action Main
StartGame()
end
action CreateGame
Color color
Model box
box:LoadBox(2, 2, 2, color:Purple())
box:SetPosition(10, 0, 0)
Add(box)
Camera cam = GetCamera3D()
cam:SetPosition(0, 2, -7)
AmbientLight ambient
ambient:SetColor(0.4, 0.4, 0.4, 1)
SetAmbientLight(ambient)
DirectionalLight light
light:SetColor(0.8, 0.8, 0.8, 1)
light:SetDirection(-1, -1, 2)
Add(light)
end
action Update(number seconds)
Camera cam = GetCamera3D()
if target:GetX() < 10
target:SetX(target:GetX() + seconds)
cam:LookAt(target)
end
end
end
```

#### Parameters

- Libraries.Compute.Vector3: A Vector3 containing the point to look at.

### LookAt(number x, number y, number z)

This action will angle the camera to look at the given point in 3D space.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Layer2D
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.Camera
use Libraries.Game.Graphics.AmbientLight
use Libraries.Game.Graphics.DirectionalLight
class Main is Game
number targetX = 0
action Main
StartGame()
end
action CreateGame
Color color
Model box
box:LoadBox(2, 2, 2, color:Purple())
box:SetPosition(10, 0, 0)
Add(box)
Camera cam = GetCamera3D()
cam:SetPosition(0, 2, -7)
AmbientLight ambient
ambient:SetColor(0.4, 0.4, 0.4, 1)
SetAmbientLight(ambient)
DirectionalLight light
light:SetColor(0.8, 0.8, 0.8, 1)
light:SetDirection(-1, -1, 2)
Add(light)
end
action Update(number seconds)
Camera cam = GetCamera3D()
if targetX < 10
targetX = targetX + seconds
cam:LookAt(targetX, 0, 0)
end
end
end
```

#### Parameters

- number x: The x-coordinate of the point to look at.
- number y: The y-coordinate of the point to look at.
- number z: The z-coordinate of the point to look at.

### Move(Libraries.Compute.Vector3 vector)

This action moves the camera on the x, y, and z planes by the amounts stored in the given Vector3.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.Camera
use Libraries.Game.Graphics.AmbientLight
use Libraries.Game.Graphics.DirectionalLight
use Libraries.Compute.Vector3
class Main is Game
Vector3 moveVector
action Main
StartGame()
end
action CreateGame
Color color
Model cube
cube:LoadBox(2, 2, 2, color:Orange())
Add(cube)
AmbientLight ambient
ambient:SetColor(0.4, 0.4, 0.4, 1)
SetAmbientLight(ambient)
DirectionalLight light
light:SetColor(0.8, 0.8, 0.8, 1)
light:SetDirection(-0.5, -1.5, 1)
Add(light)
Camera cam = GetCamera3D()
cam:SetPosition(-8, 2, 0)
end
action Update(number seconds)
Camera cam = GetCamera3D()
Vector3 position = cam:GetPosition()
if position:GetX() < 0
moveVector:Set(2 * seconds, 0, -1 * seconds)
cam:Move(moveVector)
end
end
end
```

#### Parameters

- Libraries.Compute.Vector3: A Vector3 describing how far to move on each coordinate plane.

### Move(number x, number y, number z)

This action moves the camera by the given amounts on the x, y, and z planes, respectively.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.Camera
use Libraries.Game.Graphics.AmbientLight
use Libraries.Game.Graphics.DirectionalLight
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Color color
Model cube
cube:LoadBox(2, 2, 2, color:Orange())
Add(cube)
AmbientLight ambient
ambient:SetColor(0.4, 0.4, 0.4, 1)
SetAmbientLight(ambient)
DirectionalLight light
light:SetColor(0.8, 0.8, 0.8, 1)
light:SetDirection(-0.5, -1.5, 1)
Add(light)
Camera cam = GetCamera3D()
cam:SetPosition(-8, 2, 0)
end
action Update(number seconds)
Camera cam = GetCamera3D()
Vector3 position = cam:GetPosition()
if position:GetX() < 0
cam:Move(2 * seconds, 0, -1 * seconds)
end
end
end
```

#### Parameters

- number x: How far to move the camera on the x-axis.
- number y: How far to move the camera on the y-axis.
- number z: How far to move the camera on the z-axis.

### Rotate(Libraries.Compute.Quaternion quaternion)

This action rotates the camera the given number of degrees around the axis given as a 3D vector.

#### Parameters

### Rotate(Libraries.Compute.Vector3 axis, number degrees)

This action rotates the camera the given number of degrees around the axis given as a 3D vector. The axis is essentially a ray that starts at the center of the camera and points outward. The camera will then rotate clockwise around that ray.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Drawable
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
Vector3 axis
action Main
StartGame()
end
action CreateGame
Color color
Drawable box1
box1:LoadFilledRectangle(200, 200, color:Pink())
box1:SetPosition(300, 0)
Add(box1)
Drawable box2
box2:LoadFilledRectangle(200, 200, color:Maroon())
box2:SetPosition(300, 400)
Add(box2)
axis:Set(0, 0, 1)
end
action Update(number seconds)
Camera cam = GetCamera2D()
cam:Rotate(axis, 20 * seconds)
end
end
```

#### Parameters

- Libraries.Compute.Vector3: The ray to rotate around.
- number degrees: The number of degrees to rotate.

### Rotate(number axisX, number axisY, number axisZ, number degrees)

This action rotates the camera the given number of degrees clockwise around an axis. The axis is essentially a ray that starts at the center of the camera and points outward. The camera will then rotate clockwise around that ray. The ray is defined using three numbers, representing which way it points on the x, y, and z planes, respectively.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Drawable
use Libraries.Game.Graphics.Camera
class Main is Game
action Main
StartGame()
end
action CreateGame
Color color
Drawable box1
box1:LoadFilledRectangle(200, 200, color:Pink())
box1:SetPosition(300, 0)
Add(box1)
Drawable box2
box2:LoadFilledRectangle(200, 200, color:Maroon())
box2:SetPosition(300, 400)
Add(box2)
end
action Update(number seconds)
Camera cam = GetCamera2D()
cam:Rotate(20 * seconds, 0, 0, 1)
end
end
```

#### Parameters

- number axisX: The x-component of the ray to rotate around.
- number axisY: The y-component of the ray to rotate around.
- number axisZ: The z-component of the ray to rotate around.
- number degrees: How many degrees to rotate about the axis.

### Rotate(Libraries.Compute.Matrix4 transform)

This action rotates the camera using the rotational information stored in a Matrix4 object. Typically the Matrix4 is primed using actions such as "SetToRotation" to store the rotational information before calling this action.

**Example Code**

```
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Matrix4
use Libraries.Game.Graphics.AmbientLight
use Libraries.Game.Graphics.DirectionalLight
class Main is Game
action Main
StartGame()
end
action CreateGame
Color color
Model cube
cube:LoadBox(2, 2, 2, color:Orange())
Add(cube)
AmbientLight ambient
ambient:SetColor(0.4, 0.4, 0.4, 1)
SetAmbientLight(ambient)
DirectionalLight light
light:SetColor(0.8, 0.8, 0.8, 1)
light:SetDirection(-0.5, -1.5, 1)
Add(light)
Matrix4 matrix
matrix:SetToRotation(0, 1, 0, 45)
Camera camera = GetCamera3D()
camera:SetPosition(-3, 3, -3)
camera:Rotate(matrix)
end
action Update(number seconds)
end
end
```

#### Parameters

### RotateAround(Libraries.Compute.Vector3 point, Libraries.Compute.Vector3 axis, number degrees)

This action will rotate the camera clockwise around the given point, with the camera's rotation being about the given axis. The camera is rotated by the given number of degrees.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
use Libraries.Game.Graphics.AmbientLight
use Libraries.Game.Graphics.DirectionalLight
class Main is Game
Vector3 point
Vector3 axis
action Main
StartGame()
end
action CreateGame
Color color
Model cube
cube:LoadBox(2, 2, 2, color:Orange())
Add(cube)
point:Set(0, 0, 0)
axis:Set(0, 1, 0)
AmbientLight ambient
ambient:SetColor(0.4, 0.4, 0.4, 1)
SetAmbientLight(ambient)
DirectionalLight light
light:SetColor(0.8, 0.8, 0.8, 1)
light:SetDirection(-0.5, -1.5, 1)
Add(light)
end
action Update(number seconds)
Camera cam = GetCamera3D()
cam:RotateAround(point, axis, 30 * seconds)
end
end
```

#### Parameters

- Libraries.Compute.Vector3: The point to rotate around.
- Libraries.Compute.Vector3: The axis that determines which direction the camera rotates in.
- number degrees: How many degrees to rotate about the axis.

### ScreenToWorldCoordinates(Libraries.Compute.Vector3 coords)

This action will translate a point given in screen coordinates to the world space. The z-coordinate of the given coordinates will be used to determine if the world coordinate returned should be on the near or far plane of the camera. A z-coordinate of 0 will get a point on the near plane, and a z-coordinate of 1 will get a point on the far plane. The calculated point will be contained in the Vector3 object that was passed as a parameter.

#### Parameters

#### Return

### ScreenToWorldCoordinates(Libraries.Compute.Vector3 coords, number viewportX, number viewportY, number viewportWidth, number viewportHeight)

This action will translate a point given in screen coordinates to the world space. The z-coordinate of the given coordinates will be used to determine if the world coordinate returned should be on the near or far plane of the camera. A z-coordinate of 0 will get a point on the near plane, and a z-coordinate of 1 will get a point on the far plane. The calculated point will be contained in the Vector3 object that was passed as a parameter. This action also takes the position of the viewport's origin as x and y coordinates, and the width and height of the viewport.

#### Parameters

#### Return

### ScreenToWorldCoordinates(number x, number y)

This action will translate a point given in screen coordinates to the world space. The calculated point will be on the near plane of the camera.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera2D()
cam:Move(150, -200, 0)
Vector3 coordinates = ScreenToWorldCoordinates(100, 100)
end
action Update(number seconds)
end
end
```

#### Parameters

#### Return

Libraries.Compute.Vector3: A Vector3 containing the world coordinates of the given point.

### ScreenToWorldCoordinates(number x, number y, boolean useNearPlane)

This action will translate a point given in screen coordinates to the world space. If the action is passed a true boolean value, the calculated point will be on the near clipping plane of the camera. Otherwise, it will be on the far plane.

#### Parameters

#### Return

### SetDirection(number x, number y, number z)

This action will set the direction of the Camera. It takes three number values which represent the new directional vector to use for the camera.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
cam:SetDirection(2, -2, 1)
end
action Update(number seconds)
end
end
```

#### Parameters

- number x: The new x-coordinate of the Camera.
- number y: The new y-coordinate of the Camera.
- number z: The new z-coordinate of the Camera.

### SetDirection(Libraries.Compute.Vector3 newDirection)

This action will set the direction of the Camera. It takes a Vector3 object which contains the new directional vector to use for the camera.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Vector3 direction
direction:Set(2, -2, 1)
Camera cam = GetCamera3D()
cam:SetDirection(direction)
end
action Update(number seconds)
end
end
```

#### Parameters

- Libraries.Compute.Vector3: The new direction of the Camera.

### SetFar(number value)

This action will set the distance to the far clipping plane of the camera. Objects that are farther than the distance to the far clipping plane will not be seen by the camera.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
cam:SetFar(2000)
end
action Update(number seconds)
end
end
```

#### Parameters

### SetFieldOfView(number angle)

This action will set the field of view of the camera to the given angle. The provided angle is assumed to be in degrees.

#### Parameters

### SetHeight(number height)

This action will set the effective height of the camera lens.

#### Parameters

### SetNear(number value)

This action will set the distance to the near clipping plane of the camera. Objects that are closer than the distance to the near clipping plane will not be seen by the camera.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Camera cam = GetCamera3D()
cam:SetNear(0.5)
end
action Update(number seconds)
end
end
```

#### Parameters

- number value: The distance to the near clipping plane of the Camera.

### SetPosition(Libraries.Compute.Vector3 newPosition)

This action will set the position of the Camera. It takes a Vector3 object containing the new x, y, and z coordinates to use for the camera's position.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.Camera
use Libraries.Game.Graphics.AmbientLight
use Libraries.Game.Graphics.DirectionalLight
use Libraries.Compute.Vector3
class Main is Game
action Main
StartGame()
end
action CreateGame
Color color
Model cube
cube:LoadBox(2, 2, 2, color:Orange())
Add(cube)
AmbientLight ambient
ambient:SetColor(0.4, 0.4, 0.4, 1)
SetAmbientLight(ambient)
DirectionalLight light
light:SetColor(0.8, 0.8, 0.8, 1)
light:SetDirection(-0.5, -1.5, 1)
Add(light)
Vector3 position
position:Set(0, 4, -10)
Camera cam = GetCamera3D()
cam:SetPosition(position)
end
action Update(number seconds)
end
end
```

#### Parameters

- Libraries.Compute.Vector3: The new position of the Camera.

### SetPosition(number x, number y, number z)

This action will set the position of the Camera. It takes three numbers representing the new x, y, and z coordinates to use for the camera's position.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.Camera
use Libraries.Game.Graphics.AmbientLight
use Libraries.Game.Graphics.DirectionalLight
class Main is Game
action Main
StartGame()
end
action CreateGame
Color color
Model cube
cube:LoadBox(2, 2, 2, color:Orange())
Add(cube)
AmbientLight ambient
ambient:SetColor(0.4, 0.4, 0.4, 1)
SetAmbientLight(ambient)
DirectionalLight light
light:SetColor(0.8, 0.8, 0.8, 1)
light:SetDirection(-0.5, -1.5, 1)
Add(light)
Camera cam = GetCamera3D()
cam:SetPosition(0, 4, -10)
end
action Update(number seconds)
end
end
```

#### Parameters

- number x: The new x-coordinate of the Camera.
- number y: The new y-coordinate of the Camera.
- number z: The new z-coordinate of the Camera.

### SetSize(number width, number height)

This action will set the effective width and height of the camera lens.

#### Parameters

### SetUp(number x, number y, number z)

This action will set the direction that the camera considers to be up. The top of the camera will face the direction indicated by the three given number values.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.DirectionalLight
use Libraries.Game.Graphics.AmbientLight
use Libraries.Game.Graphics.Color
class Main is Game
action Main
StartGame()
end
action CreateGame
Color color
Model cube
cube:LoadBox(2, 2, 2, color:Orange())
Add(cube)
AmbientLight ambient
ambient:SetColor(0.4, 0.4, 0.4, 1)
SetAmbientLight(ambient)
DirectionalLight light
light:SetColor(0.8, 0.8, 0.8, 1)
light:SetDirection(-0.5, -1.5, 1)
Add(light)
Camera cam = GetCamera3D()
Vector3 up
up:Set(cam:GetUp())
// By scaling all values by -1, we are effectively flipping this upside down.
number x = up:GetX() * -1
number y = up:GetY() * -1
number z = up:GetZ() * -1
cam:SetUp(x, y, z)
end
action Update(number seconds)
end
end
```

#### Parameters

- number x: The direction of the up vector along the x coordinate plane.
- number y: The direction of the up vector along the y coordinate plane.
- number z: The direction of the up vector along the z coordinate plane.

### SetUp(Libraries.Compute.Vector3 newUp)

This action will set the direction that the camera considers to be up. The top of the camera will face the direction of the given Vector3 object.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Vector3
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.DirectionalLight
use Libraries.Game.Graphics.AmbientLight
use Libraries.Game.Graphics.Color
class Main is Game
action Main
StartGame()
end
action CreateGame
Color color
Model cube
cube:LoadBox(2, 2, 2, color:Orange())
Add(cube)
AmbientLight ambient
ambient:SetColor(0.4, 0.4, 0.4, 1)
SetAmbientLight(ambient)
DirectionalLight light
light:SetColor(0.8, 0.8, 0.8, 1)
light:SetDirection(-0.5, -1.5, 1)
Add(light)
Camera cam = GetCamera3D()
Vector3 up
up:Set(cam:GetUp())
// By scaling all values by -1, we are effectively flipping this upside down.
up:Scale(-1, -1, -1)
cam:SetUp(up)
end
action Update(number seconds)
end
end
```

#### Parameters

- Libraries.Compute.Vector3: The direction the top of the Camera will face.

### SetWidth(number width)

This action will set the effective width of the camera lens.

#### Parameters

### SetYawPitchRoll(number yaw, number pitch, number roll)

The SetYawPitchRoll action sets the direction and orientation of the Camera using yaw, pitch, and roll angles. All angles are in degrees. The starting direction of the Camera (when the provided yaw, pitch, and roll are 0) is a camera pointing directly along the positive Z axis, with the top of the camera directly pointing along the positive Y axis. The yaw describes how far the camera is rotated along the X/Z axis. It effectively controls how the camera turns left and right. A positive value will rotate the camera clockwise (typically to the right). The pitch describes how far the camera is angled up or down. The pitch value should typically be between -90 and 90 degrees. Larger values will cause the camera to look in the opposite direction specified by the yaw value. For pitch values between -90 and 90, positive values angle the camera upwards, and negative values angle it downwards. The roll describes how the top of the camera is oriented. A roll value of 0 will angle the camera so the top of the camera points upward, towards the positive Y axis. A positive roll value "twists" the camera clockwise, and a negative value will twist it counter-clockwise.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Camera
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.DirectionalLight
class Main is Game
action Main
StartGame()
end
action CreateGame
Color color
Model box
box:LoadBox(2, 4, 2, color:Green())
box:SetPosition(0, 0, 0)
Add(box)
Model floor
floor:LoadBox(10, 2, 10, color:Maroon())
floor:SetPosition(0, -3, 0)
Add(floor)
DirectionalLight light
light:SetColor(color:White())
light:SetDirection(2, -2, 4)
Add(light)
Camera camera = GetCamera3D()
camera:SetPosition(-5, 2, -5)
// The camera will be looking 45 degrees to the right and 30 degrees
// down, and be tilted 30 degrees clockwise.
camera:SetYawPitchRoll(45, -30, 30)
end
end
```

#### Parameters

- number yaw: The yaw angle, measured in degrees.
- number pitch: The pitch angle, measured in degrees.
- number roll: The roll angle, measured in degrees.

### SetZoom(number zoom)

The SetZoom action will set the zoom level of the camera. A value of 1 will use the default zoom. A smaller value will zoom the camera out, while a larger value will zoom the camera in.

#### Parameters

### Transform(Libraries.Compute.Matrix4 transform)

This action will transform the position, direction, and up vector of this camera by the given matrix. The matrix should typically be primed using the "SetTo..." actions, such as "SetToTranslation" to set the position, "SetToRotation" or "SetToLookAt" to determine the camera's angle, etc.

**Example Code**

```
use Libraries.Game.Game
use Libraries.Game.Graphics.Color
use Libraries.Game.Graphics.Model
use Libraries.Game.Graphics.Camera
use Libraries.Compute.Matrix4
use Libraries.Game.Graphics.AmbientLight
use Libraries.Game.Graphics.DirectionalLight
class Main is Game
action Main
StartGame()
end
action CreateGame
Color color
Model cube
cube:LoadBox(2, 2, 2, color:Orange())
Add(cube)
AmbientLight ambient
ambient:SetColor(0.4, 0.4, 0.4, 1)
SetAmbientLight(ambient)
DirectionalLight light
light:SetColor(0.8, 0.8, 0.8, 1)
light:SetDirection(-0.5, -1.5, 1)
Add(light)
Matrix4 matrix
matrix:SetToTranslation(-3, 3, 3)
matrix:SetToRotation(0, 1, 0, 45)
Camera camera = GetCamera3D()
camera:Transform(matrix)
end
action Update(number seconds)
end
end
```

#### Parameters

- Libraries.Compute.Matrix4: The Matrix4 containing transformations.

### Update()

This action recalculates the camera's position and data. This should be used after the camera has been manipulated in any way.

### WorldToScreenCoordinates(number x, number y, number z)

This action will return the screen coordinates of a point in the world space. The returned point will be stored in a new Vector3 object.

#### Parameters

#### Return

### WorldToScreenCoordinates(Libraries.Compute.Vector3 coords)

This action will return the screen coordinates of a point in the world space. The returned point will be stored in the same coordinate vector used to indicate the world coordinates.

#### Parameters

#### Return

### WorldToScreenCoordinates(Libraries.Compute.Vector3 coords, number viewportX, number viewportY, number viewportWidth, number viewportHeight)

This action will return the screen coordinates of a point in the world space. The returned point will be stored in the same coordinate vector used to indicate the world coordinates. This action will calculate the point using the given position and dimensions of the viewport.