Introduction To Panels

X-Plane's panel system lets you customize the appearance of instruments and gauges in both the 2-d and 3-d view of your airplane. This document provides a general outline of how the panel system works.

X-Plane has two fundamentally different camera views that users can select:
 * A 2-d "forward with panel" view provides a 2-d image of the airplane's panel, for maximum clarity with minimum performance cost. The pilot's viewpoint is fixed out the window.
 * A 3-d "cockpit view" provides a real 3-d structured cockpit with the user able to move in 5 degrees of freedom about the entire airplane. The cockpit is modeled in 3-d; the airplane's panel may be modeled in 3-d or built by mapping a 2-d panel image onto the 3-d mesh.

= Basic Panel Structure =

In X-Plane, a panel is a 2-d screen consisting of:
 * A background image. This sits behind all other parts of the panel.  Typically the background image will include the shape of the cockpit as it appears, with alpha transparency for the windows.
 * Many instruments, each positioned somewhere on the panel. The instruments themselves consist of:
 * An instrument background, which sits on top of the panel background but behind all overlays.
 * Instrument overlays which sit on top of the instrument backgrounds.

Only instrument overlays can move, show/hide, and undergo dynamic lighting; the instrument background and panel background must be static.

Instruments come in two flavors:
 * Several hundred "pre-made" instruments cover nearly every function you can imagine in a modern airplane. X-Plane comes with premade instruments for the standard six, EFIS/EICAS, engine steam gauges, radios, etc.  The pre-made instruments come pre-animated and come with high quality default artwork.  Pre-made instruments allow for limited customization.
 * A dozen "generic" instruments that display arbitrary simulator data using a number of common mechanical motions. You specify all aspects of generic instruments; they provide complete customization for developers who need to control every aspect of an instrument.

= Panel File Conventions =

X-Plane locates the artwork for your panel using a two-step search process: first X-Plane looks in the 'cockpit' set of folders inside your airplane pack; if the image file is not found there, it is then located in X-Plane's default artwork folder, found in Resources/cockpit.

Therefore, to override any piece of panel artwork, simply make a new customized version of the image, duplicating the folder structure of the 'cockpit' folder. In Plane-Maker, the "copy_instrument_png" command (defaults to control-P) will copy the selected instruments bitmaps from X-Plane's system folder to your airplane's folder automatically so you can simply edit the copied file.

Note: the name of the panel background that X-Plane will load is affected by the panel type in the viewpoint dialog box. The current mapping of view modes to filenames is: General Aviation  Panel_General.png Airliner          Panel_Airliner.png Fighter           Panel_Fighter.png Glider            Panel_Glider.png Helicopter        Panel_Helo.png Auto-Gyro         Panel_Autogyro.png General-IFR       Panel_General_IFR.png Gyro-Twin         Panel_Autogyro_Twin.png Fighter-IFR       Panel_Fighter_IFR.png

= Panels and 3-D Cockpits =

A 3-d cockpit is a full 3-d environment, representing the inside of an airplane.

The Basic Structure of a 3-D Cockpit
A 3-d cockpit is created from one or more OBJs (3-d models) attached to the airplane. One particular OBJ (the "cockpit object") can utilize special features for the purpose of modeling cockpits.

Many parts of the cockpit can simply be modeled with 3-d objects: engine throttle levers, steam gauges, etc. However, you can also use a 2-d panel of instruments as a texture, mapped to parts of your 3-d cockpit object. This makes it possible to include moving maps, glass EFIS displays, and other 2-d elements in the 3-d cockpit; these elements would be nearly impossible to model out of 3-d meshes.

The basic steps to setting up a 3-d cockpit are:
 * Create a 2-d panel that will serve as a 'tetxure atlas' for your 3-d cockpit.
 * Create an additional texture atlas for the rest of the 3-d cockpit object.
 * Model the cockpit in 3-d, using the 2-d panel and additional cockpit object texture to UV-map the 3-d cockpit.
 * Attach your cockpit object in Plane-Maker.

X-Plane locates your panel object by loading an object in the same folder as your airplane, with the name of your airplane plus one of the following prefixes: _cockpit_inn.obj - used for internal views if present _cockpit_out.obj - used for external views if present _cockpit.obj - used for either view if one of the above is not present The main motivation for having separate cockpit objects for internal vs. external views is that you can put a 3-d pilot figure in the external cockpit object without having his or her hands get in the way in the internal 3-d cockpit view.

To use your panel as a texture in your object, you need to do two things: The precise way this is accomplished is usually specific to the particular 3-d modeling tool and export plugin you are using.
 * 1) Use the object command COCKPIT_REGION one or more times to map parts (or all) of the panel to UV space in your cockpit.
 * 2) Use the object command ATTR_cockpit_region to mark parts of your mesh as using the mapped panel instead of the object texture.

Note that the areas mapped to the panel will be clickable just like the 2-d panel, unless you override this behavior by assigning some other manipulator to the mesh. So at its simplest, you can simply 'map' the 2-d panel into the 3-d cockpit and you will have a functioning airplane.

A few notes on panel regions:
 * Panel regions cannot utilize transparency or any of the 2-d lighting effects (spot lights). Use real 3-d lighting instead.
 * Panel regions must be a power of 2 in size in both dimensions, but do not have to be square.
 * From a performance perspective, panel texture is more expensive than regular texture, so if a feature can be built without using a panel texture (e.g. an eyeball vent or a seat) use the cockpit object's normal texture.
 * You can attach 24 extra objects to your plane, but only the cockpit object can be clicked, so you may want to reserve the cockpit object for throttles, knobs, and other 'interactive' parts and save regular geometry (the windows, the floor) for regular objects.
 * When the user turns down X-Plane's resolution, the cockpit object maintains higher resolution than the rest of the plane, so do use it for details like labels, but not for less important textures.

Using a Separate Panel for the 3-d Cockpit
The above strategy assumes that you will use the 2-d panel as a texture for your 3-d cockpit. But sometimes this is not ideal:
 * The packing of useful instruments in the 2-d panel will be based on the real airplane layout. For the purpose of 3-d modeling, this means "wasted" space in the panel texture.
 * 2-d Instruments may be drawn with shadows, lighting, and perspective drawn in, making the 2-d panel inappropriate for use as an 'albedo' texture.

X-Plane allows you to make a second panel (the "3-d panel") which is used only as a texture for the 3-d cockpit.

Typically you'll want to make your 3-d panel smaller and more compact, with only the instruments that you must texture map, like a moving map or radio displays.

To use the 3-d panel:
 * Create a custom panel background, but place it in a folder inside your aircraft named cockpit_3d. This will signal to X-Plane that you are building a separate panel for 3-d texturing.
 * If you are using the same instruments in 2-d and 3-d, the 3-d panel will search the folder cockpit_3d in your airplane for images first. So you can have separate instrument artwork for your 2-d and 3-d panel.
 * Plane-Maker has two panel tabs, one labeled 2-d and one labeled 3-d. Simply switch to the 3-d tab and add instruments.

Tip: the X-Plane command "sim/operation/make_panel_previews" will save a PNG file with the texture that is being used for your 3-d cockpit. You can use this as a reference when you UV map your 3-d cockpit. The image will be saved in your cockpit_3d/-PANELS- folder in your airplane.

Other 3-d Cockpit Object Features
OBJ files have a few modeling capabilities that let you create panel-like features in 3-d without using a true flat 'panel' at all; some authors use this to improve performance and realism of their airplanes.
 * meshes can be animated; often a steam gauge or lever can be built entirely in 3-d.
 * meshes in the cockpit object can be tagged with 'manipulators'. A manipulator describes what happens to the mesh when the mouse is dragged over it.  You can use manipulators to directly implement various forms of buttons, knobs and levers.
 * the level of brightness from the emmissive (_LIT) texture can be changed via ATTR_light_level, which will scale this brightness based on any simulator or plugin dataref. This can be used to model annunciators and other cockpit elements.

There are two other OBJ features that are worth noting for 3-d cockpit construction:
 * A mesh can be marked as ATTR_draw_disable but still have a manipulator. You can use this to place an invisible "clickable hotspot" in front of a mesh. For example, a toggle switch might be too thin to easily grab with the mouse; the hot spot makes the panel more usable.
 * ATTR_solid_camera makes a mesh impassable to the camera in the 3-d cockpit; this can prevent the user from moving the camera behind the panel or outside the plane while the doors are closed. Use ATTR_draw_disable and ATTR_solid_camera together to make a simple, manifold mesh that constrains the camera.

Using a 3-d Cockpit for 2-D Views
Developing 2-d panels and 3-d cockpits is labor intensive; some authors choose to develop only a highly detailed, highly functional 3-d cockpit, and then use it even when the user selects a 2-d view. To do this, check the "show cockpit object in: 2-d forward panel views" check-box in the view tab of the viewpoint screen in Plane-Maker. This will cause the sim to show a straight-forwards 3-d view in place of the 2-d panel, which will (in turn) never be shown.

What Happens If You Do Not Provide a 3-d cockpit object
If you do not provide a 3-d cockpit object, X-Plane will simply show your 2-d panel in 3-d (as a rectangle) floating in space. While this does not look very good, it can be useful to allow users with head-tracking hardware (like TrackIR) to maintain full freedom of viewpoint while flying.

= Further Extensions of the Cockpit and Panels =

If you need to further customize panel behavior, the plugin system can interact with panels in two ways:
 * You can create custom datarefs in a plugin and then use those datarefs as data sources for generic instruments. Thus if there is already a generic instrument that already manages the graphics task you want (turning a needle, moving a lever) you only have to create datarefs.  See XPLMDataAccess for the APIs to do this.
 * For more complex drawing, you can register a drawing callback that will be called when the panel is drawn. You can then use OpenGL to draw any kind of custom drawing you wnat.  See XPLMDisplay and the X-Plane SDK Tech Notes for more info.