article_type: Reference

X-Plane 11 Material Model

X-Plane 11’s Physically Based Rendering (PBR) uses a new material model for solid textured objects and meshes.

Physical Simulation

The X-Plane lighting and material model divide the light interaction with materials into two categories:

• Specular reflection – this is light that bounces directly off the surface of a material. Speuclar reflection is responsible for mirror-like reflections, glossy appearances on materials and any white “sun spot”.
• Diffuse reflection – this is light that makes it past the surface of the material and is partly absorbed. Diffuse reflection is significantly less directional and may be strongly tinted.  Diffuse reflection gives materials a “matte” look.

X-Plane 11 conserves energy between diffuse and specular reflection – having a stronger specular reflection reduces the amount of diffuse reflection automatically; in this way highly glossy and reflective materials don’t appear to be overly bright compared to matte materials.

Comparison to X-Plane 10: in X-Plane 10, specularity could be added without reducing diffuse reflectance; this meant that most reflective materials were brighter than non-reflective ones. An artist could choose to manually darken the albedo of a texture to compensate.

The microsurface of a material is considered to be rough or glossy (or some measure in between); roughness and glossiness are measures of how smooth the surface is, not how reflective it is. A surface can be highly reflective and highly rough at the same time.

Roughness serves to spread out specular reflections; a mirror image in a rough surface appears blurry, as each ray of incoming light bounces in several directions.

X-Plane 11 conserves energy as roughness is adjusted; the same amount of energy is reflected in a rough or glossy surface. The difference is that a glossy surface has a highly focused reflection; a light source’s specular reflection will go in one direction on a glossy surface, resulting in a specular highlight that is very bright but small.

By comparison, a rough surface diffuses the specular energy in all directions; the specular reflection is visible over a wide range of angles but is not very strong.

Comparison to X-Plane 10: in X-Plane 10, all surfaces are glossy and only the overall specular reflectance could be changed. Therefore it was impossible in X-Plane 10 to model a surface like asphalt, which is simultaneously very reflective and very rough. An artist could attempt to simulate this by creating a high frequency noise pattern of highly reflective and non-reflective pixels to manually “break up” the reflection, but when zoomed out this effect is incorrect.

Surfaces become more reflective when viewed at glancing angles; this is called the Fresnel effect. X-Plane 11’s rendering engine simulates this automatically. The specular reflectance of a material that is specified by the artist is its minimum reflectance, when the material is viewed directly (e.g. the camera is orthogonal to the surface).

X-Plane 11 automatically decreases diffuse light as the effective reflectivity increases. This avoids materials appearing too bright at glancing angles.

(This is probably a bug – the incoming light is not more glancing based on view angle! The actual effect of fresnel is more complicated because it is affected by the integral of all incoming light.)

Comparison to X-Plane 10: X-Plane 10 does not provide camera-angle-based variable reflectivity; as a result, materials often have to be made too reflective at all angles to make glancing angles look adequately reflective.

Material Properties

The major properties of a material are controlled by two channels of the normal map of a model:

• Roughness is stored in the alpha channel of the object, with 1.0 (maximum opacity) being the most glossy surface, and 0.0 (the most transparent) being the roughest surface.
• Base reflectance (how much light is reflected off of the surface at an orthogonal angle) is optionally stored in the blue channel; no blue means no base reflectance and maximum blue means a completely reflective material at all viewing angles.

This scheme is opt-in; objects use the NORMAL_METALNESS directive to indicate that the blue channel is suitable for base reflectance. (Since legacy models typically have strong blue values from tangent space normal maps, the blue channel must be ignored in legacy models.)

If metalness is not used, a base reflectance of 0.04 is assigned to the entire material; this is a good approximation for most dielectrics (plastic, wood, concrete, etc.) and also a reasonable backward-compatible value for X-Plane 10 content. The roughness channel is intentionally encoded to have the highest gloss value in X-Plane 11 match the most reflective material in X-Plane 10. (Since X-Plane 10 specular reflections were all highly glossy, this means that at least plastics and matte materials “just work” in X-Plane 11.)

X-Plane 11’s treatment of the albedo color (day texture) changes as base reflectance increases:

• The albedo is used to tint specular reflections. While this is not strictly physically correct, it provides an affordable way to create tinted metallic reflections.
• Because base reflection is increasing, the diffuse color becomes darker due to energy conservation.

Glass Effects vs Decals

The alpha channel of the albedo (day texture) is used to create translucent rendering, e.g. the mesh being drawn is blended with the mesh behind it to create a mixture of both colors. There are two physical interpretations of this alpha effect:

• The top mesh is “translucent”, e.g. like tinted glass; the color taken from behind the mesh represents light transferred through the top mesh (translucency).
• The top mesh does not always exist in the alpha-clear parts of the texture, e.g. like the holes in a fence. The top texture acts like a ‘decal’ over what is behind it. In this situation, partial alpha represents a blend of both materials as if there is a pattern of holes in the top mesh so small that both the presence and absence of the material happen in a single pixel. (Think of zooming out with a chain-link fence – the result is translucency.)

In practice, authors use one effect (alpha blending) for both physical cases (translucency and decals). The meaning of alpha matters for physical correctness.

When alpha means ‘decal’, clear alpha removes all lighting effects from the mesh. This is the correct simulation of the mesh not existing.

When alpha means ‘glass’, clear alpha removes the diffuse but not specular component of lighting effects from the mesh. This is the correct simulation of light passing through the boundary layer from ‘stuff behind the mesh’, rather than being absorbed.

X-Plane 11’s default interpretation is the ‘decal’ interpretation, which:

• Matches X-Plane 10.
• Is HDR/deferred rendering compatible.
• Preserves decal behavior on surfaces like runway pavement.

Authors have the option in X-Plane 11 to use glass alpha as long as:

1. The object is attached to an aircraft and
2. The aircraft’s lighting mode is marked as “glass”.

In this situation, authors can put the BLEND_GLASS directive into an object header; this will cause alpha to make the diffuse channel translucent while keeping specular effects, for reflections on clear glass.

Panels For MSFS Developers

Terminology

X-Plane has two viewing modes for panels: a forward 2-d view that shows the 2-d panel and a 3-d view that shows the 3-d cockpit (which corresponds to the virtual cockpit in MSFS). Unlike MSFS, X-Plane does not provide multiple 2-d panel views – the 2-d side views may not contain working 2-d panels. X-Plane does not provide native support for popup panels, but it is possible to create them using a plugin or other tricks.

X-Plane’s panel consists of a background image (where alpha creates the transparent windshield) and a gray-scale or RGB overlay image that applies shadowing and some 2-d spot lighting to the panel. While MSFS has “gauges” X-Plane has “instruments” – the individual unit of placement.

Instrument Differences

The MSFS panel is created using an XML file; gauges can also be coded in C++ and can be in the form of *.dll or MSFS specific *.gau format.

X-Plane panels reside inside the ACF file in binary format (but can be exported as text from Plane-Maker); most panel editing is done using Plane-Maker’s near-WYSIWYG user interface.

X-Plane provides hundreds of types of instruments built in:

• Pre-made instruments model existing real world instruments; X-Plane ships with a complete set of real world instruments for VFR and IFR flight. Limited customization is possible by replacing bitmaps, and tuning a few parameters.
• Generic instruments provide basic “mechanism”, e.g. a needle that rotates, a button that toggles, etc. The generic instruments have a large number of customized parameters and visualize data from a “dataref” – that is, a sim variable from X-Plane itself or a plugin.

Therefore the closest thing to building gauges using the XML file is to build a panel out of multiple generic instruments. Typically a modern panel might be built primarily from generic instruments, but use the pre-built instruments for the moving map and a few other cases.

Custom Gauge DLL Vs. Plugin

While MSFS allows a custom gauge to be built via a DLL (where the gauge provides a bitmap of its 2-d image), X-Plane has a slightly more generic mechanism:

• An airplane can contain one or more plugins.
• Each plugin has full access to the X-Plane plugin SDK API – this includes building menus, custom UI and windows, creating and modifying sim variables, and drawing using OpenGL.
• Often the generic instruments can be customized by feeding a dataref from your plugin into the generic instrument – that is, the generic instrument rotates the needle (and X-Plane does the drawing) but the animation is keyed to output from your plugin.
• A plugin can also draw directly onto the panel – this happens on a panel-wide basis, not on a per-instrument basis. (This is how a complex custom nav display might be built.)

X-Plane does not provide a general mechanism to let an author “place” a custom plugin-drawn instrument into a panel using Plane-Maker; typically custom instrumentation is specific to a single plane. Where users have tried to build add-on instruments via plugins, they have had to create ad-hoc mechanisms to place those instruments.

The Virtual/3-d Cockpit

X-Plane’s 3-d cockpit environment is actually a rendering of the entire airplane in 3-d; all of the 3-d modeling work you do for airplane will be visible in the 3-d cockpit, allowing for the user to exit the VC and do a walk-around of the airplane. (See “Camera Restriction” below.)

Therefore the virtual cockpit is is simply modeled in 3-d using OBJ files, which contain meshes. Standard animation is used for instruments like steam-gauge airspeed indicators; this is similar to MSFS where a 3-d animation can be driven off of an animation source. Like MSFS, using “real animated 3-d” is often the fastest path for mechanical instruments.

X-Plane does have one “special” object (the “cockpit object”) that is intended particularly for VC work; it allows a 2-d panel to be UV mapped onto some 3-d surfaces, similar to using a material to indicate a 2-d panel mapping in MSFS. This work-flow is largely the same – you would create a snapshot of the “unwrapped” set of 2-d gauges (Plane-Maker can make this snapshot) and then UV map using it. The precise way to indicate “panel texture” depends on the 3-d editor you use.

Like MSFS, X-Plane provides a separate 2-d panel for the purpose of providing a material/texture for the 3-d virtual cockpit; therefore you can tightly pack this texture even if you want to ship a 2-d panel as well. In X-Plane, 2-d panels scroll and are often 2048 x 2048; it is important for performance to tightly pack the panel that is used in the 3-d cockpit.

Mouse-click interaction in the 3-d cockpit in X-Plane is annotated directly on the 3-d mesh; you mark a sub-section of the mesh with a “manipulator” describing what you want to have happen and the gesture. Typical manipulations include drags in 2-d or in arbitrary 3-d space, clicks, etc. Manipulations typically change an X-Plane dataref or run an X-Plane command (similar to an MSFS sim event) to affect the flight model.

Besides direct 3-d manipulation, you can mark any part of the 3-d mesh that has a panel texture mapped to it as “panel clickable” – this causes 3-d clicks to be passed through to the underlying 2-d panel, where the click operates as expected.

Things X-Plane Doesn’t Have Yet

Arbitrary Transforms

X-Plane can show and hide instruments but it cannot arbitrarily rotate or move them; there may be some XML transformations that are not yet possible in X-Plane. In many cases, a pre-built instrument will exist, and you can simply retexture it.

Things MSFS Doesn’t Have

Gradual Lighting Control

For any 3-d model in X-Plane, you can tie the level of the emissive (_LIT) texture using ATTR_lit_level, which arbitrarily scales the texture using a dataref. This has application for more realistic baked lighting, but can also be used to create gradual light faders in the 3-d cockpit or even to create instruments. (For example, the gear light LEDs can be made to appear by tying their lighting level to the gear status.)

Camera Restriction

You can restrict the movement of the camera in the 3-d cockpit by tagging a mesh as solid to the camera; this will stop your user from walking through the walls of the VC.

Use a hidden, simplified, manifold mesh to restrict the camera; the camera restriction will react better and use less CPU power with the simplified mesh.

You can use animations in your camera-restricting mesh. For example, if you animate the doors of your fuselage in the camera-restricting mesh, a user can exit the airplane only when the door is open.

See the default Cessna 172 in X-Plane for an example of this.

Non-Monotone Key Frames

What are Non-Monotone Key Frames

Non-Monotone key frames are key frames where the key frame table is not in order. Here are some examples:

N1     ANGLE
0		50
50		270
100	230

This key frame table makes the angle of the needle increase as N1 goes up, but then the needle will reverse and go back down a bit. In this case, “angle” is non-monotone.

In this table for a a rotary;

enum   image
0		0
1		2
2		1
4		3
3		4

Both the input and output are non-monotone.

When Would I Want Non-Monotone Key Frames?

Generally you’ll want non-monotone key frames under two cases:

1. If an instrument has to move forward and backward in response to data (e.g. the N1 needle example above).
2. If you need to remap the enumerated values for a rotary (e..g the rotary example).

When Are Non-Monotone Key Frames Allowed?

1. The value (but not dataref) key frame column can be non-monotone as long as the instrument reads but does not write the dataref. So non-monotone output can be used for a needle as long as it is not draggable, for example.
2. Rotaries may have non-monotone key frames for both input and output, as long as values are matched _exactly_ without interpolation.

Previewing Non-Monotone Key Frames in Plane-Maker

Plane-maker recognizes that if you have out-of-order non-monotone key framing tables then you are probably intending to use a dataref that EXACTLY hits the key frame, like an int dataref that passes in enums. (You would use this to re-order the mapping between enums and rotary positions.)

In this case Plane-Maker will snap-round the simulated dataref to exact key frames so that you can see a sane preview of the dataref.

If you have done this but the dataref in x-plane is NOT rounded to key frames, you will then see wrong interpolation in x-plane, since we can’t cleanly interpolate non-monotone functions!!

Manipulators

A manipulation is an action the user can take by clicking on your object. (That is, the user “manipulates” your OBJ with the mouse.) Manipulations can only be used on cockpit objects!

Types of Manipulators

There are six types of manipulators supported in X-Plane 920 and later:

• None
• Panel Click
• Drag-Axis
• 2-d Drag
• Command
• Command-Axis
• Opaque

No Manipulation

Triangles are ignored when clicking. This is the default, and is usually used for anything that is not clickable. This manipulation does not require any CPU resources, so when possible, you want to leave your meshes non-manipulatable. This is the only legal manipulation for non-cockpit objects.

The none manipulation is set using either

ATTR_no_cockpit
ATTR_manip_none

The none-type manipulation will show no tool tips, and uses the arrow (default) cursor.

Panel Click Manipulation

A click on the triangles is mapped through to the 2-d panel based on the panel texture’s mapping. This manipulation can only be specified for objects that are textured by the panel texture (or a panel texture region). Panel click manipulation is set using one of

ATTR_cockpit
ATTR_cockpit_region <region number>

Panel click manipulations show the tooltips and cursors of the 2-d panel.

Drag-Axis Manipulation

As the user drags along an axis in 3-d object-space, a dataref value is increased or decreased. The length of the axis defines how much mouse travel (in meters of object space) is required to completely change the dataref across a range defined by a pair of parameters. The drag-axis manipulator takes the form:

ATTR_manip_drag_axis <cursor> <x> <y> <z> <value1> < value2> <dataref> <tooltip>

Here, x, y and z define the length and direction of the drag axis, and value1 and value2 define the range of values over which the manipulator runs. If the mouse is dragged beyond either of these limits, the manipulator is clamped: the value of the dataref will remain the same until the mouse is again dragged or clicked within range. The current value is retained after the mouse is released, and determines the position of the manipulator’s drag-axis relative to the next mouse click. For example, if a manipulator is currently set to a value midway between it’s minimum and maximum values, then the mouse will automatically find itself halfway along that manipulator’s drag-axis when next it clicks on it.

Drag-axis manipulation is subject to object animation. The orientation of the manipulator’s drag-axis relative to the animated mesh to which it is attached is the same each time the mouse is clicked on it. For example, if a drag-axis manipulator on an animated throttle lever has an axis perpendicular to the lever shaft when clicked in the ‘idle’ position, that axis will still be perpendicular to the lever shaft when clicked in the ‘open’ position. However, for the duration of any given drag, the orientation of the drag-axis relative to the aircraft remains constant. So if the drag-axis of the previously-described manipulator happens to be perfectly horizontal at the moment the mouse is clicked on it, it will remain perfectly horizontal and ‘locked-in’ until the mouse is released, even though the visible throttle lever has been animated to a new position. This behaviour is more intuitive in practice than it may appear on paper!

2-d Drag Manipulation

The 2-d drag manipulator effectively combines two manipulators into one, allowing two datarefs to be modified simultaneously by dragging the mouse along a pair of perpendicular axes. To minimise input ambiguity, the axes are defined in 2-d screen space, not object space, and their respective orientations are fixed. The first dataref is modified by dragging the mouse horizontally across the screen and the second by dragging vertically. This type of manipulator would typically be used to control a yoke or joystick and takes the form:

 ATTR_manip_drag_xy <cursor> <x> <y> <ref1 value1> <ref1 value2> <ref2 value1> <ref2 value2> <dataref1> <dataref2> <tooltip>.

Here, x defines the distance the mouse must be dragged across the screen from left to right in order to modify the output of dataref1 from ref1 value1 to ref1 value2. Similarly, y defines the distance the mouse must be dragged up the screen in order to vary the output of dataref2 from ref2 value1 to ref2 value2.

In contrast to the drag-axis manipulator, the axis orientations of the 2-d drag manipulator are not subject to object animation. The x-axis is always horizontal and the y-axis is always vertical. However, the location of the manipulator’s click-region does follow any animation of it’s mesh.

The following example shows a 2-d drag manipulator configured to control a steering yoke. The x-axis controls roll (an 80-pixel drag), and the y-axis controls pitch (a 50-pixel drag). Note: since it is more intuitive to drag down rather than up the screen in order to increase pitch, the vertical axis has been assigned a negative value):

 ATTR_manip_drag_xy  four_arrows  80  -50  -1  1  -1 1  sim/cockpit2/controls/yoke_roll_ratio  sim/cockpit2/controls/yoke_pitch_ratio  I am a tooltip.

It is not obligatory for a 2-d drag manipulator to address two datarefs. A single dataref may be manipulated in 2-d screen-space by entering a value of 0 for each of the redundant numeric parameters and null for the dataref name of the unassigned axis.

Command Manipulation

A command manipulation invokes an X-Plane command when the mouse is clicked on it. The command continues to be invoked until the mouse is released. It takes the form:

 ATTR_manip_command <cursor> <command> <tooltip>

Command-Axis Manipulation

Dragging along a specified object-space axis actuates one of a pair of commands, subject to the direction of the drag. The command continues to be invoked (CommandContinue phase) until such time as the mouse is either released or else dragged back along the axis to the neutral position. Dragging right through the neutral position to the opposite end of the axis invokes the second command. The neutral position is centred on the location of the original mouse click and occupies 40% of the overall length of the axis Typical applications would be nudge-wheels and three-position toggle switches. The command-axis manipulator takes the form:

 ATTR_manip_command_axis <cursor> <x> <y> <z> <command1> <command2> <tooltip>

The x, y, and z parameters define the orientation and length in meters of the drag-axis. Dragging in the positive direction triggers command 1 and in the negative direction, command 2. The following example shows a command_axis manipulator configured as a pitch trim nudge-wheel/switch:

 ATTR_manip_command_axis up_down  0.00  0.00  -0.01 sim/flight_controls/pitch_trim_down  sim/flight_controls/pitch_trim_up I am also a tooltip.

The axis values in the above example would be appropriate for a standard-sized toggle switch mounted on a horizontal console panel. Dragging the mouse approximately 2mm towards the nose of the aircraft triggers pitch_trim_down, and dragging it 2mm towards the tail triggers pitch_trim_up (since the X-Plane acf z-axis runs positive nose to tail).

Opaque Manipulation

This sets the manipulation to ‘no-op’ (no operation). Unlike “none” manipulation, opaque manipulation “swallows” the mouse, preventing it from clicking on other manipulators that may lie behind it. It would typically be used to act as a safety-guard over a switch.

Dataref “Button” Manipulators

These manipulators change a dataref when the mouse is clicked or held, creating button-like functionality. There are five sub-flavors. The push-button, radio button, and toggle manipulators are meant to provide button-like behavior for a mesh. The delta and wrap manipulators are meant to be used to create invisible “hot spots” over a mesh.

Push-Button Manipulator

The push-button manipulator sets a dataref to a “down” value when the mouse is clicked, then back to an “up” value when the mouse button is released.

Radio Button Manipulator

The radio button manpiulator sets a dataref to a value each time it is clicked.

(It is considered to be a “radio button” because a set of these manipulators, sharing one dataref but using differing values, can create radio-button-like behavior.)

Toggle Manipulator

The toggle manipulator switches a dataref between one of two values each time it is clicked.

Delta Manipulator

The dataref is increased (or decreased) when the button is clicked (and/or held down). If the dataref exceeds its limit range, it is clamped to that limit.

Wrapping Manipulator

The dataref is increased (or decreased) when the button is clicked (and/or held down). If the dataref exceeds its limit range, it wraps around to the other end of the range.

Manipulator Properties

These properties apply to some or all of the manipulators except for:

• None and opaque manipulators (which have no real action).
• Panel manipulator (which gets its properties from the panel).

Cursor

All manipulators let you specify the cursor that appears when the mouse is over the manipulator. (The panel manipulator takes its cursor from the underlying panel.) The OBJ8 specification lists all possible cursor choices.

3-D Axis

The axis and command-axis manipulators allow a drag in 3-d; they require the specification of an axis.

• The axis is a 3-d axis, so it is specified as a length in X, Y, and Z (in meters).
• This axis is affected by animation; if the manipulator is inside a rotation, the axis will rotate.
• The axis manipulators imply an “increasing” and “decreasing” direction; the values specify the increasing direction.

EXAMPLE: for an axis of X = 1, Y = 1, Z = 0, as you drag to the upper right (in object coordinates) the dataref will increase.

The axis’s position in the 3-d cockpit is set based on the current value of the dataref when the user clicks. For example, if the dataref for the axis manipulator is the throttles and the throttles are at maximum value, the entire axis will be in the direction to decrease the throttles. If the throttles are at 50%, the mid-point of the axis will be at the click point. In other words, axis positioning is relative based on the dataref.

(For the command-axis, the axis center is always the anchor point.)

2-D Axis

The 2-d drag axis is a special case: it allows a drag in “screen space” – that is, the axes is always up-down and left-right no matter what the pilot head position. Thus the axes are lengths in pixels. A positive “x” means that a drag to the right increases the first dataref. A positive “y’ means a drag up increases the first dataref.

Datarefs and Values

For the axis and axis-2 manipulators, one or two datarefs is required, as well as low and high values. The low and high values “scale” the axis. For example, for a throttle, a low and high value of 0.0 and 1.0 would tell the manipulator what throttle values correspond with the end of the axis.

(In other words, the axis specifies the size in the 3-d cockpit of the drag, and the dataref values specify the size in terms of the actual dataref movement.)

Commands

A command can be specified for either the command manipulator (the command is invoked while the mouse button is held down) or the command-axis dataref (the command is invoked while the drag is to the left or right of the axis).

Tooltips

All manipulators let you specify a tooltip. When the mouse lingers over the manipulator region and the user enables “instrument explanations”, this tooltip will be shown. It provides a way to provide custom panel instructions. Tooltips may not have return characters. (For the panel manipulator, the tool tip is taken from the underlying 2-d manipulator.)

Setups For Typical Switches and Elements

Here are some typical setups for making 3-d animated switches and other cockpit parts.

Terms

• Rotary: any part with rotational movement.
• Momentary: any part that returns to its original position when released.
• 2-way,3-way,n-way, continuous: how many distinct positions a part can take. A dimmer is continuous; an on-off switch is 2-way.

Non-Momentary Parts

These parts retain their original position after being clicked.

2-way parts

Datarefs: use the “toggle” manipulator – the on and off values match the two possible values for the underlying dataref.

Command: if a “toggle” command (e.g. sim/flight_controls/landing_gear_toggle) exists, you can use a command manipulator. You cannot use a “set to X” command like sim/flight_controls/landing_gear_up.

N-way switch

Use the axis manipulator along the axis the user can drag. Important: to get “N”-way action, be sure the underlying dataref is of type “integer” so the switch “snaps” to each position.

N-way rotary

Use the 2-d axis manipulator, but only use the X axis. This will allow a horizontal drag to turn the rotary. To get “N”-way action, be sure the underlying dataref is of type “integer” so the switch “snaps” to each position.

Radio Buttons

Radio buttons can take on N positions, by having any one button pressed in. Set each button to have a manipulator of type “radio button”. All buttons should have the same datarefs but different values.

Continuous Switch

Use the axis manipulator along the axis the user can drag. The underlying dataref should be of type “float”.

Continuous Rotary

Use the 2-d axis manipulator, but only use the X axis. The dataref should be of type “float”.

Momentary Parts

These parts snap back when done.

2-way momentary

Dataref: use the “push button” manipulator with appropriate on and off dataref values. Command: if the action is a “hold-it-down” command (like sim/starters/engage_starter_1) you can use a command manipulator.

3-way momentary

Use the command-axis manipulator, with one command for each direction.