article_type: Request for comment (RFC)

RFC: apt.dat 1050 Extensions

This RFC proposes new features to the apt.dat format for X-Plane 10.50 to support the X-Plane Scenery Gateway and static aircraft spawning. It consists of two parts: one for static spawning and one for airport identifiers.

This RFC is not a general call for feature requests for the apt.dat format – it aims to solve two specific problems.

Part 1: Static Aircraft Spawning and Aircraft Metrics

In order to make ramp positions more suitable to both AI and static aircraft, the apt.dat 1050 file format includes extra meta-data on parking spots and ATC taxi routes.

Clearance Widths on Taxi Edges

Clearances for aircraft are described using the standard ICAO category codes for aircraft, A-F. Roughly speaking the coding is:

Wheel Base Wing Span Category
4.5m 15m A
6m 24m B
9m 36m C
14m 52m D
14m 65m E
16m 80m F

Both parking spots and ATC taxi route (that are not runways) gain a new maximum ICAO category, describing the largest aircraft that can safely operate on this ATC taxi route or parking spot.

For ATC taxi route edges, this is accomplished with 6 new type tokens: where taxiway edges (record type 1202) could normally be one of “runway” or “taxiway”, new “sized” taxiways are permitted: taxiway_A, taxiway_B, taxiway_C, taxiway_D, taxiway_E, taxiway_F.  Edges corresponding to runways do not need sizes because X-Plane can determine the runway width from the actual runway (type 100) record.

Ramp Starts

Additional metadata is included in a new 1301 record, which follows the 1300 (new ramp start) record.

The 1301 record consists of an ICAO width code, an operations type code and zero or more space separated 3-letter airline codes, e.g.

1301 icao_width operations_type [airlines]
1301 C airline AAL SWA UAL

The ICAO width must be one of: A, B, C, D, E, F

The operations type must be one of: none, general_aviation, airline, cargo, military

Additional Equipment Classes

A new equipment class is introduced, “fighters” – it is allowed anywhere that the original five equipment classes (heavy, jets, turboprops, props and helos) are allowed.

Clearance Widths

For ramp starts, this is accomplished by allowing a size flag (A, B, C, D, E, or F) to be included in a new extended ramp start (type 1301) record.

Ramp Operation Types

Ramps gain a new field: “operations type,” indicating what kind of AI or static aircraft appear there. Can be set to: none, general_aviation, airline, cargo, military.

Airline Sets 

A ramp start may optionally tagged with a set of valid 3-letter ICAO airline codes, which must be entered as capital letters.

Part 2: Airport Identification Meta-Data

Historically, the apt.dat file provided a single identifier field, sometimes referred to as an ICAO identifier. This identifier was a mandatory primary key for the airport, and therefore if an ICAO code did not exist for an airport, some non-ICAO code had to be made up and stuffed in this field. For US airports, typically an FAA code was used, and for non-US airports, there was no clear standard. Recently the X-Plane Scenery Gateway project designed a fixed rule-set to create non-conflicting synthetic identifiers by extending the field beyond four characters.

Finding an airport by identifier can thus be challenging; if the identifier is synthetic, searching by an IATA code or a local authority code will not work.

This extension aims to solve this problem by separating the primary airport identifier key (whose goals are uniqueness and stability) from other meta-data keys aimed at airport discovery (e.g. to aid search).

Going forward, the airport identifier referred to in the type 1, 16 or 17 record is known as an airport identifier, and is required to be a globally unique identifier for a particular real-world airport. The identifier can be synthetic or match a real world authority, but it cannot be ambiguous, and it cannot be omitted.

Each airport may have zero or more meta-data records, record code 1302, which is defined as

1302 key value

For example:

1302 icao_id KBOS
1302 faa_id BOS
1302 iata_id BOS

A key may not appear more than once per airport amongst all 1302 records.  Keys must not contain white space or commas but values may.

The legal semantics of a given key (e.g. global uniqueness, accepted character set) is defined on a per-key basis; the only guarantees of the file format itself are file-valid (UTF8) characters, no white space or commas in keys, no newlines in keys or values, and no repeating keys. No key is mandatory.  An empty key is illegal. Only officially defined, supported, conforming, and non-empty keys are allowed.

For the purposes of the initial specification, the following keys are being officially defined:

Key Name Explanation Example
icao_id ICAO airport identifier code EDDF
faa_id FAA airport identifier (“LID”) MA52
iata_id IATA airport code FRA
city_id City name Boston
country_id Country name United States
region_id State/Province/Region Massachusetts
34 Comments

RFC: Airport-ID Based Exclusion

This RFC is for a scheme that allows overlay scenery elements (points, polygons/poly-lines and road networks) in a DSF to be associated with an airport ID; if the airport is specified by a higher priority scenery pack than the one that the DSF resides within, then those DSF elements are not loaded. This mirrors the behavior of apt.dat elements (where all apt.dat elements for an airport whose ID is replaced by a higher priority scenery pack are not loaded).

Implementation Details

This scheme is built on top of a number of layered extensions to the DSF file format.

Comment Types

The DSF file format has (since its inception over a decade ago) contained comment blocks. A comment is a blob of variable-sized arbitrary binary data in the DSF command stream. The comment’s size is known to a DSF parser even if the comment’s contents are opaque, allowing for extension to DSFs with forward compatibility.

Until now, X-Plane did not use comments. This scheme introduces comments with a 16-bit comment type starting the comment block, followed by data specific to the comment type. Comment types can be used in any comment command (8, 16, or 32-bit) as long as the comment’s payload is at least 2  bytes long.

Filter Index Comments

Comment type 1 is defined as a change of the filter index.  The filter index is a 32-bit signed integer indicating what filter is used to process certain DSF commands; a filter of -1 means “no filter is applied”. No filter is treated as the default state; as filter index comments go by, it effectively changes the filter applied to the next command.

Filters are applied to road network, polygon/poly-line and point commands, but not to patches and base mesh.

Filtering Scheme

X-Plane defines filters to include or not include overlay elements by airport ID code using new properties: the property sim/filter/aptid defines a new filter; the value of the property is the airport ID to match.  The filter is defined as including overlay elements if the airport whose ID matches the value is defined by this scenery pack, and as excluding overlay elements if the airport whose ID matches the value is defined by another scenery pack.

X-Plane also uses the filter properties to filter exclusion zone properties; any of the sim/exclude_XXX properties that are after a sim/filter/aptid property in the DSF property table will be included only if the filter is defined as including overlay elements. Exclusion zones defined before any of the filter/aptid filters are always included.

 

Leave a comment

Next-Gen Liveries RFC

Goals

  • Creating liveries/repaints needs to remain simple. Repainting a plane is one of the simplest ways to make X-Plane content – this simplicity should not be lost.
  • It should be possible to create a livery without copying airplane content. This is desirable for three reasons: (1) efficiency of implemetation, (2) enabling repaints while retaining content copyright and (3) allowing the author to update the core plane without repainters having to re-copy modified art assets.

Bug Fixing

  • If an aircraft package contains multiple aircraft files, liveries will be available to all of them. If the aircraft files represent different configurations (E.g. P&W vs. RR engines) a livery might be appropriate for one aircraft file but incomplete for another. Requested: some way to “limit” a livery to certain aircraft files in a package.
  • The tail number is part of the ACF file, but may change due to paint changes of an aircraft. Requested: a way to specify the tail number per livery.

Configuration Management

Airline authors would like to give repainters a choice of “cosmetic” (meaning they do not affect the FM) options for the airplane – this would include things like antenna placement and window location, but would not include things like engine selection or winglets. These cosmetic options would be created by the primary airplane author – the livery repainter would simply select the appropriate parts for the livery in question. (For example, a painter creating a British Airways livery would select Rolls Royce engines to match the real world planes.)

Livery Configuration Files

Proposed: a text file in the livery would provide a storage location for additional per-livery data. This file would be a simple keyed record file (like all X-Plane text files). The file wold have a package specific name like livery.txt, not an aircraft specific name, like ba20_livery.txt.

(This is because the livery might be shared across multiple configurations – file-specific liveries are discussed below. However, consider a Cessna 172, offered in two configurations – with or without G1000. This 2-d panel change would not affect repaints, thus the desire for package-wide liveries.)

Livery configuration files could be written by painters, or (more likely), if a plane author provides a “repainting kit” with starter images, annotated UV maps, etc. then a livery configuration file would be provided in the painting kit that would be customized by the painter.

Configuration File Options

File Matching

If present, a key would specify what ACF files the livery matches for. If no keys are present, the livery can be use for any file. Example:

REQUIRES_FILE b747-400.acf

Tail Number

If present, overrides the tail number for the ACF.

TAIL_NUMBER N4772Q

Object Mapping

The object mapping would allow the livery to remap what objects are attached to the plane, by specifying a file name substitution scheme. The intent is that the airplane author would attach the “default” objects for a configuration in Plane-Maker, but provide alternate objects that could be mapped.

Example:

# This selects to use the "direct_tv.obj" antennas OBJ instead of the regular
# antennas.obj.  A painter who wants to have the appearance of direct TV on the 
# plane might include this mapping.
MAP_OBJECT antennas.obj antennas_direct_tv.obj

OPEN ISSUE: this could go in one of two ways:

  1. The above scheme, which lets the painter remap objects directly or
  2. A scheme in which the primary airplane author enumerates legal combinations and the painter picks from among them. In this second option, the livery might only contain
CONFIG_CHOICE antennas  direct_tv

Where the meaning of the option and its legal configs were defined in the ACF package itself.

  • Advantages: slightly simpler liveries – livery authors don’t need to know where objects live and what is meant to go with what.
  • Disadvantages: whole system becomes more complex, including complexity in the main package.

Ben says: I was originally in favor of choice 2, but Peter has me leaning toward choice 1 for overall simplicity.

Authoring Information

Perhaps the livery should contain authoring information, e.g.

LIVERY_AUTHOR John Wharfing
LIVERY_COPYRIGHT Copyright 2008, All Rights Reserved.
3 Comments

Instrument Animation RFC

This RFC is a proposal to allow nested animation via groups in the panel/instrument system.

Under this proposal:

  • Groups would have an animation mode, which would be one of: none, rotation, or translation.
  • If a group’s animation mode was not “none” the group would have a primary dataref and key frame table. The key frame table’s output would be in pixels (translation) or degrees (rotation).
  • If a group’s animation mode is translation, the group would also have an “axis” property defining the direction of translation (as a DX, DY).
  • All sub-groups and instruments within the group would be affected by the animation.
Leave a comment

Generic Text RFC

Mutli-format font support

  • The generic-text instrument would be able to take a font bitmap with more than one line.
  • Each line could be used for a different font, different size, or different color text.
  • Control codes (ASCII 1-31) in a string DataRef (char-array type DataRef) would be interpreted as style changes. A line in the text would be selected by running the control code through the instrument’s key frame table.

OPEN ISSUE: where would line size and line formatting information be stored?

  • These could be in the instrument.
  • They could also be in a text file co-named with the PNG. This is a bit atypical of the generic instrument system, but since the PNG is a shared resource, it makes development simpler to have the metrics be shared too.

Text-font-based Numeric

  • A new gen_numeric instrument would use the same font formatting rules as the gen_text, for shared fonts, but use numeric datarefs.
  • The key frame table would do numeric conversion.
  • Numeric formatting would be by property (similar to the LED and rolling instruments).
  • Color selection would be done via range bounds, similar to the pie instrument (e.g. different stripes could be selected based on five zones of dataref values).

OPEN ISSUE: should it simply be legal to allow the gen_text instrument use numeric datarefs? Pro: reduces number of instruments Con: key frame table acts differently, properties needed are very different too!

Leave a comment

Physical Polygon RFC

Problem Specification

In X-Plane 9, you can create a draped polygon by specifying a polygonal outline in a DSF and a .pol text file with the properties for the polygon. The .pol file references a texture, and optionally applies a physical surface to the polygon. If a physical surface is applied, it acts “over” the base terrain. In this way, the image of a concrete pad (on top of base mesh grass) can act like concrete, with correct physics wherever the plane drives.

There is one limitation with this system: if the author places a large orthophoto (showing heterogeneous terrain) into the scenery, the orthophoto (whether via a .pol or .ter file) can have only one physical property. Thus an airport orthophoto must be “all grass” or “all concrete”.

There is a work-around for this problem, but it is very expensive: an author can place multiple polygons using the same orthophoto texture and shape each polygon to the distinct regions. So the author would put one polygon in place for the whole orthophoto, then a second polygon for only the concrete. Two .pol files reference separate surfaces but one texture.

While X-Plane will efficiently load the texture only once, the resulting polygon mesh is particularly inefficient, because:

  • X-Plane will dutifully clip the top polygon visually, even though there is no need to do so and
  • The concrete areas must be drawn twice (once for the bottom and once for the top). To avoid over-draw, the bottom polygon must be clipped as well, which makes even more triangles.

The Proposed Fix

The proposed fix is a new .pol attribute, something like “NO_DRAW”. When present, the polygon would only apply physical properties to the mesh, but not apply any paint. Under this scenario the author would:

  • Set the physical property of the orthophoto to the “lowest priority” surface, typically grass or dirt.
  • Use no-draw, concrete-surface polygons to “annotate” the hard physical areas on top of the orthophoto.

X-Plane would perform no clipping on the bottom orthophoto, for maximum mesh efficiency, and would have no overdraw since the texture is only drawn once.

Leave a comment

DSF Art Asset Storage RFC

This RFC proposes the ability to embed small directly accessed art assets inside DSFs.

A DSF_File_Specification file contains geographic/graphic data, but contains file-based references to the external art assets used to visualize the data. Every art asset in X-Plane is an external file, and those art assets are never image files. Image files are always further linked from a primary art asset. (Thus for a 2500 orthophoto scenery pack, there must be 2500 .ter “art asset” files that describe the meta data for the orthophotos.)

X-Plane can typically defer the loading of the image files associated with a DSF, but it must load all of the art asset meta data when a scenery pack is loaded, in order to configure the rendering engine properly. (Indeed one motivation for putting data in external meta-data files was to allow X-Plane to fully set up the rendering engine without having to touch image files, which might be coming in on another thread at a much slower rate, while the user flies.)

The problem is that as scenery packs have started to use large numbers of individual art asset files, disk seek time has become a bottleneck during initial scenery load. Multiple-minute load times are not uncommon.

This RFC aims to streamline this process by allowing a DSF to directly contain the contents of some primary art asset files. This is particularly a win for very small art asset files (e.g. .ter and .pol files which are often much smaller than a single disk block).

Conceptual Setup

Conceptually, a DSF would become both a DSF file and a container file system for some number of primary art asset files. Art assets would simply be referenced by ‘file name’ inside the DSF.

X-Plane would then attempt a direct match between referenced art asset name and a file ‘contained’ in the DSF. For example, if a polygon definition in the DSF polygon definition header atom contained the string ‘lakes/big_lake.pol’ and there was an entry in the DSF file table labeled ‘lakes/big_lake.pol’ then the .pol file would be loaded from the corresponding DSF data, without ever looking for a file called big_lake.pol in the lakes directory of the scenery pack.

Note that the ‘directory’ character in the DSF has no meaning – it is simply a convenience to be able to create ‘directory-like’ hierarchies; this is provided to make it simple to convert an existing scenery pack to use the DSF as ca container – see “Authoring Use” below.

Also note that this system cannot be combined with the library; library items must come from external disk storage.

DSF Syntax

A new files atom would contain three sub-atom:

  • A string table atom would contain the names of all contained ‘files’.
  • An offsets atom would contain a beginning and ending offset length pair (8 bytes per file) into the data atom. The order matches the files atom.
  • The data atom contains the back-to-back file data.

The string table must be sorted by file name (using a simple byte-sequence comparison like memcmp); the offsets atom follows this order. The data atom does not have to follow the same order as the offsets/names; the offsets allow files to be reordered from the sorted order.

Authoring Use

The most likely scenario for authoring use would be a pair of authoring tools to ‘pack’ and ‘unpack’ a DSF. Since the DSF file data is atomic, the DSF could have files added and removed ‘losslessly’ – that is, without reducing the quality of encoded mesh data. (By comparison, running a file through DSF2Text can reduce mesh precision.)

This would allow authors to work with the existing format, and then ‘pack’ the DSF at the end of development to speed up load time.

1 Comment

3d cockpit HUD RFC

This is an RFC for a HUD system in the 3-d cockpit. It proposes ways for authors to create HUDs in 3-d cockpit objects.

12/19/08 – Initial Draft

Current Technology and Limitations

Currently, the HUD instruments in a cockpit are not rendered into the panel texture when a 3-d cockpit object is used. (For 921, a feature was added to render the HUD instruments into the default cockpit object for planes like the 777.)

Burning HUD instruments into the panel has (in the past) been limited to only a subset of supported OpenGL cards – some computers will simply not show the effect. There are alternate possible OpenGL techniques; we do not yet know their affect on fps for low-end machines.

921 does not render the HUD instruments into the panel texture because some existing planes (see: F-22) make the assumption that this will not happen — the panel region behind the HUD is mapped to the 3-d object in some way … often behind a 2-d HUD that is drawn when the plane is in 2-d forward view with the 3-d cockpit object visible. In this case, burning in the HUD gives us a double-HUD!

It turns out that EFIS instruments can be used like a HUD, and they will be rendered to the panel texture on capable hardware even in custom cockpits. This makes it possible to create a HUD-like 2-d system using existing instruments, albeit on only some hardware.

Instruments over transparency does not work ever with ATTR_cockpit_region – the cockpit region system was specifically designed with alpha omitted; processing alpha correctly in the panel texture requires a bunch of special processing and extra VRAM use in the panel system – the plan was: optimize the no-alpha case, ATTR_cockpit_region “tells” X-Plane that we can take these optimizations, and implement HUDs using a different technology (see below).

Clearly two goals can be gleaned from the above:

  1. A HUD texturing system should not alter the look of existing planes or require authors to change their planes and
  2. It should run on the widest range of hardware possible.

Possible Future Extensions

2-d Approaches

2-d approaches basically involve burning the HUD to the panel texture and then using it. Advantages:

  • Simple.
  • Works the same as the rest of the panel to authors.

Disadvantages:

  • Potentially lower pixel resolution – HUD can appear aliased if a lot of panel texture isn’t consumed. VRAM inefficient.
  • Potential performance problems, due to additional panel texture use.
Relaxed Rules

Under a “relaxed rules” scheme, we simply publicly recognize that dragging instruments into the transparent area of the panel is okay.

  • An optional feature in the ACF would allow the author to specify HUD instruments are rendered to the 3-d panel.
  • This option could wrok with HUD-type lighting.

The big problem here is finding a way to support the HUD being visible on older hardware. This might be possible for HUD instruments and generic HUD-lighting instruments.

ATTR_region_HUD

With this scheme, a panel region could be turned into a “HUD” panel region. Unlike regular panel regions, HUD panel regions would:

  • Fully support alpha.
  • Work correctly only with HUD instruments and generic instruments with “glass” lighting. (See HUD-type lighting below.)
  • Not support mechanical or back-lit instruments, or non-HUD non-generic instruments.

The pros/consof this scheme are:

  • Pro: Really simple implementation. Because it is so restricted in what goes into the HUD region, the sim doesn’t have to do a lot of work with all of the edge cases. This is a case that could run at near-full-performance on just about any hardware.
  • Con: requires use of the ATTR_region system. This could mean rebuilding cockpits before the 3-d HUD can be used.
  • Con: all the problems with a 2-d approach (e.g. VRAM use, etc.).
HUD-type lighting

In either case, should there be a “HUD” lighting mode for generic instruments? It would work the same as glass, but it would follow the HUD lighting level rheostat (and disappear when the HUD was off).

3-d Approaches

 

In a 3-d approach, the HUD is actually drawn during OBJ drawing. While the HUD itself is 2-d, it is being drawn as part of the virtual cockpit. Advantages:

  • Really clean lines – lines are pixel perfect even at really huge zoom levels without a lot of VRAM. (BUT: if the HUD element in turn is based on a texture, we are limited by that texture’s resolution.)
  • No requirement for panel texture usage – easier to adopt in existing planes, assuming any cockpit space is left.

Disadvantages:

  • Unknown performance profile – might work well, might not.
  • Unknown whether this would create a limit on what instruments could be drawn.
  • Potentially incompatible with things like cockpit clicking, or putting cockpit texture over non-flat meshes.
  • Potentially difficult or confusing to authors to have two separate ways to create panel texture.
direct_panel_rect

In this scheme, a new OBJ command would induce the OBJ system to draw a rectangular sub-section of a panel at an arbitrary 3-d quad location in the panel. This would “directly” map the panel to the HUD, without the use of a separate texture.

1 Comment