About Camera Control
The camera control APIs allows control of the viewpoint that the user sees the 3-d world from. We might want to control X-Plane's virtual "camera" to:
- Provide new views both inside and outside the cockpit.
- Build 3-d cockpits with a free-flowing camera.
- Use X-Plane as a 3-d renderer, allowing the user to browse scenery
X-Plane's Camera Environment
X-Plane defines a number of views. Some views are _interior_ views that appear to be inside the cockpit, while others are _exterior_views. For an interior view X-Plane draws a 2-d cockpit overlay if one is available. An overlay is always available for a straight-forward cockpit view. For interior views, the plane exterior may or may not be drawn depending on the currently loaded aircraft. For external views, the plane is always drawn.
The camera position is specified via seven values:
- Position (X, Y, Z). The camera is positioned in OpenGL coordinates. See the chapter on graphics for an explanation of how the OpenGL coordinate system correlates to real-world space.
- Heading. The camera points along a heading specified as a clockwise rotation from the +Z axis. This rotation is close to a true-north heading at the OpenGL origin.
- Pitch. The camera is tilted up or down.
- Roll. The camera can be rolled right or left around the axis the camera is pointing along.
- Zoom. A zoom factor magnifies the entire image. The default zoom is 1.0
The camera is also affected by the field of view.
Controlling the Camera
Plugins control X-Plane's camera by providing a camera control callback. A plugin provides a callback to the X-Plane plugin manager. That callback is called before X-Plane draws each frame. The callback returns the seven parameters that describe the camera position.
When we specify a camera control callback, we specify the duration we would like it to take affect for. We can have the callback take affect until another plugin takes over the camera (or the plugin cancels the callback) or until the user selects another view. Register our callback with a duration forever to permanently take over the camera; register with a duration until next view change to create new views that integrate smoothly witih X-Plane.
Using Camera Control
This section describes how to control the camera using a plugin.
Reading the Camera Position
Ww can read the current camera position using the camera APIs. We receive a structure containing seven components.
< Example Code : Reading the Camera >
Controlling the Camera
To control the camera, we must first write a camera control callback function. This function places the camera near the plane.
< Example Code: a camera control callback >
To activate our function, call the control camera function. Do this from another callback.
< Example: installing the callback. >
Once we install our callback, it will first be used the next time a frame render is started.
Creating New Views
To create a new view we need to set X-Plane's view properly (e.g. pick an external or internal view) and then control the camera.
< Example code: using the utility routines to set up the view and then controlling the camera. >
In this example we first set the camera to be outside the plane...this guarantees that no interior panels will be around. We then install the camera control function, which will actually position the camera as is needed.
Camera Control Reference
See the XPLMCamera API for more information on camera control.