Camera

Camera preview, with weapon as camera child

1. Introduction

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

  1. TCastleTransform.Translation - observer position.

  2. TCastleTransform.Direction - direction in which you look.

  3. 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:

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:

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


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