This tech note describes how X-Plane's "camera" code is put together. The camera code is the code that sets up OpenGL to show parts of the 3-d world.
The major controller of how the camera code works is the view mode. View modes include the tower view, circling view, 3-d cockpit view, etc. View modes fall into a few major categories:
- Internal 2-d views (with or without the panel).
- Internal 3-d cockpit views.
- External Views
The current view mode can be read from:
Camera Control API
The camera control API allows a plugin to fully control the placement of the 3-d camera via a callback. This callback fully overrides any positioning and rotation information for the camera, but the view-mode is still in effect for purposes of drawing a 2-d or 3-d panel, and controlling sound.
The camera control is essentially an insert into the camera positioning code that fully replace positioning.
Rendering Settings for Multiple Cockpits
X-Plane has some rendering settings that change parts of the camera system, for the purpose of allowing users to set up cockpits using multiple copies of X-Plane.
The customizations to the view fall into two categories: view angle offsets and view ratios.
View Angle Offsets
These 3 offsets (vertical, horizontal, and roll), which are in the rendering settings and mirrored by datarefs, change the angle of view from its normal direction. These offsets apply to any 2-d view when a camera callback is not in use.
The 3 datarefs that mirror the user's settings are:
sim/graphics/view/field_of_view_vertical_deg sim/graphics/view/field_of_view_horizontal_deg sim/graphics/view/field_of_view_roll_deg
The roll angles are designed to set up monitors that wrap around the pilot.
These two offsets essentially move the edges of viewing around in two dimensions. You can think of this as if the X-Plane window were part of a huge screen made of many monitors. Each addition or subtraction of 1 from the ratios offsets which part of the screen we show such that one edge of the screen is fully moved to the other side.
(For example, if you are sitting on the runway and the right wingtip of your 747 is just off screen to the right, adding 1.0 to the lateral view offset ratio will pan the whole image such that the entire 747 is off-screen to the left except the previously hidden part of the wingtip, which will now be visible.)
These datarefs apply to all camera modes, even when plugin camera control is in effect!
These datarefs are designed to allow the user to construct a large view area from multiple monitors.
Please note that neither of these datarefs ever effectively "moves" the pilot's head.
Pilot's Head Position and Internal Views
X-Plane models the pilot's head position in 5 degrees of freedom: XYZ in airplane coordinates (that is, positive X moves to the right, Y is up, positive Z moves toward the tail).
The XYZ position of the pilot's head is used by X-Plane's camera code in 2-d and 3-d views. The roll and heading rotate the pilot's head only in 3-d mode. All of these datarefs are bypassed by camera control plugins.
sim/graphics/view/pilots_head_x sim/graphics/view/pilots_head_y sim/graphics/view/pilots_head_z sim/graphics/view/pilots_head_psi sim/graphics/view/pilots_head_the
Ways to Control the Viewoint
- A plugin that wants to customize the 3-d viewing experience within the cockpit can use the pilots_head_XXX datarefs.
- A plugin that wants to move the camera absolutely for one monitor near the airplane should use a camera control plugin.