Camera | Manual | Castle Game Engine

Camera

Table of Contents

1. Introduction
2. The initial camera
3. Camera can have children, and be a child of other objects

1. Introduction

Camera determines what do you see in the viewport. Camera is a TCastleTransform descendant, and as such it defines:

TCastleTransform.Translation - observer position.
TCastleTransform.Direction - direction in which you look.
TCastleTransform.Up - together with direction, the up vector determines the camera orientation.

A common way to set all camera vectors is to use TCastleTransform.SetView.

Camera also defines projection:

TCastleCamera.ProjectionType - determines perspective or orthographic projection.
TCastleCamera.Perspective, TCastleCamera.Orthographic - these subcomponents allow to configure projection details.

See the Tutorial: Designing a 3D world and Tutorial: Designing a 2D world to see the typical workflow how do you manipulate the camera using the editor.

2. The initial camera

There are various ways to set the initial camera:

If you design your world using the Castle Game Engine editor, we recommend to set the initial camera following the Tutorial: Designing a 3D world. This means that you just move / rotate the camera as any other TCastleTransform.
Another approach is to just set the camera vectors by code during your view start. Call Viewport.Camera.SetView like this:
```
Viewport.Camera.SetView(
  Vector3(-11.34, 30.04, 96.07), // position
  Vector3(0.10, -0.49, -0.87), // direction
  Vector3(0.35, 0.83, -0.43), // up (current)
  Vector3(0.00, 1.00, 0.00) // gravity up
);
```
You can even generate such Pascal code: Use the "Clipboard → Print Current Camera (Viewpoint) (Pascal)" menu item in Castle Model Viewer.
Alternatively, automatically initialize the camera defaults (including position, direction, up vectors) based on the information in the model.

To activate this auto-detection, set TCastleViewport.AutoCamera to true.

The way this auto-detection works:
- If the scene set as Viewport.Items.MainScene defines a default camera, then use it.
  
  For example glTF format allows to define a default camera. Blender can export such glTF models.
  
  Models in In X3D can also define a default camera, using X3D Viewpoint or OrthoViewpoint nodes. If you write X3D files by hand, you can even generate such nodes using the "Clipboard → Print Current Camera (Viewpoint)" menu item in Castle Model Viewer.
- Otherwise (if there is no Viewpoint node,or you didn’t even set MainScene) then the camera will be auto-detected to look at the world bounding box.

3. Camera can have children, and be a child of other objects

Since camera is a TCastleTransform descendant:

Camera can be a child of another TCastleTransform.
- For example you can attach a camera to some object (like a car or character) to move camera along with that object.
- You can combine this with ExposeTransforms to attach a camera to an animated bone of your character.
Camera can have other TCastleTransform as children.
- For example you can attach a weapon carried by a player in FPS game as a child of camera. See examples/fps_game demo.
- You can make a headlight by simply placing a light (like TCastleDirectionalLight) as camera child. See examples/viewport_and_scenes/headlight demo.

When the camera is a child of other objects, you have to be careful when controlling camera translation / rotation from code.

Use TCastleTransform.GetView, TCastleTransform.SetView to get / set camera vectors in the local coordinate system.
Use TCastleTransform.GetWorldView, TCastleTransform.SetWorldView to get / set camera vectors in the world coordinate system.

To improve this documentation just edit this page and create a pull request to cge-www repository.