Nasal CDU Framework

2011-05-09T18:29:21Z

Hcc23: /* CDU */

This page is a rather technical description of the Nasal code for the framework used to implement a Boeing style [[CDU]].

{{WIP|[[User:Hcc23|Hcc23]] is working on this. Find him in the FG IRC channel to discuss this page.}}

'''Note:''' Although this is meant as a documentation for the code, it obviously will (always) be (slightly) outdated. However, after reading through this page, the actual source code at https://gitorious.org/fg/fgdata/trees/master/Aircraft/Instruments-3d/cdu should not present any major surprises. [[User:Hcc23|Hcc23]] 10:07, 7 May 2011 (EDT)

= Basic Classes =

== Line ==

The line class represents data to be shown on a row of the CDU's display matrix. This does not mean that a line has to span a complete row of the CDU's display matrix.

<code>
var Line = {
# "Static"
vector byID,
func registerInPropTree(path),
func formatOutput(input_data),
func getScreenTextVector(),
func new(line_data,ptp),

# "Public"
scalar me.id,
scalar me.ptp,
vector me.used_properties,
vector me.line_data,
scalar me.line_string_length,
func me.enable(),
func me.disable(),

# "Private"
scalar me.active,
};
</code>

== Field ==
A field holds two lines, the label and the data line, as well as information about what the associated line select key does.

<code>
var Field = {
# "Static"
vector byID,
func registerInPropTree(path=nil),
func new(label,data,key_action=nil,ptp=nil),

# "Public"
scalar me.id,
scalar me.ptp,

func me.get_label_line(),
func me.get_label_line(),
func me.used_properties(),
func me.lsk_binding(),
func me.enable_lsk(),
func me.disable_lsk(),

# "Private"
(Line) me.label_line,
(Line) me.data_line,
scalar me.lsk_active,
};
</code>

== SubPage ==
A SubPage is actually the main element in the CDU framework. It holds the content via its fields and manages the updating of the CDU screen.

<code>
var SubPage = {
# "Static"
vector byID,
(Field) blankField,
func registerInPropTree(path=nil),
func updateField(field, side, lsk_index),
func displayFields(field_vector, side),
func displayPage(),
func new(parent_base_page,name=nil,ptp=nil),

# "Public"
scalar me.id,
scalar me.separator,
scalar me.ptp,
func me.register_field(field_pos,field),
func me.activate(),
(Field) me.home

# "Private"
scalar me.parent,
scalar me.title,
scalar me.status,
vector me.left_field,
vector me.right_field,
};
</code>

== BasePage ==
A BasePage is exactly that: a base to hold sub pages. A base page most closely represents the concept of a '''page''' in a CDU.

<code>
var BasePage = {
# "Static"
vector byID,
func displayPage(),
func regiserInPropTree(path)
func new(name,ptp=nil),

# "Public"
scalar me.id,
scalar me.active_sub_page_id,
func me.activate(),
(Field) me.home,
scalar me.ptp,

# "Private"
vector me.sub_pages,
scalar me.title,
scalar me.status,

};
</code>

== CDU ==
The CDU is the main class for the instrument. Each simulated CDU should have one and only one CDU instance associated to it. This is intended to support multiple CDUs showing different content in the future.

<code>
var CDU = {
# "STATIC"
func M_ERROR(message_string),
func M_WARNING(message_string),
func M_NOTE(message_string),
func M_HINT(message_string),

func updateDisplay(),
scalar activeBasePageID,

(ScratchPad) scratchPad,
(Timer) timer,
(ListenerCollection) listOfListeners,
};
</code>

= Additional Infrastructure =
The previous section was more concerned with the conceptually necessary pieces for a/the CDU. This section introduces the other elements the framework introduces in order to code a functional CDU.

== ScratchPad ==

The ScratchPad is the input/output line in the CDU(s). The scratch pas as such is kind of different from the rest of the CDU(s) as the scratch pad messages are truly static, i.e. they happen to be displayed on all CDUs in the cockpit, no matter what the individual CDU is otherwise showing.

<code>
var ScratchPad = {
# "STATIC"
vector messages,
scalar deleteString, # "DELETE"~""
func displayScratchPad(),
func new(),

# "PUBLIC"
scalar me.input_string,
func me.erase,

# "PRIVATE"
scalar me.pm_trigger,
func me.plusminus(),
func me.clear(pressedTime),
func me.erase(),
};
</code>

== ListenerCollection ==
In order to update fields that are tied to a (potentially changing) property, fields that need a (potentially changing) property to compute their data can (and automatically will) register a property listener on the relevant properties whenever the relevant field is displayed. In order to unregister the listener for pages that are no longer displayed, the class CDU keeps a collection of the currently active listeners, such allowing the unregisterling for unneeded listeners.

<code>
var ListenerCollection = {
# "STATIC"
func registerInPropTree(path),
func add(prop, field_id, subpage_id, side, lsk_index),
func clearAll(),
func new(ptp=nil),

# "PRIVATE"
scalar me.ptp,
vector me.listener_list,
vector me.property_list,
};
</code>

Nasal CDU Framework

2011-05-09T18:23:31Z

Howto:Animate models

2011-04-28T13:43:47Z

Hcc23: /* Conditions */ added some details on the order of comparisons

The real world is full of motion. To simulate this in [[FlightGear]], '''models must be animated'''.

This document provides basic information for all kind of animations. For more complex animations, you are advised to check the available [[aircraft]] for examples.

== A note about animation order ==
{{stub}}

Animations are executed by FlightGear in the order that they are read in the model's .xml file. Therefore, it is very important to pay attention to the order, especially when multiple animations are applied to the same object(s).

== Special code parts ==
=== Axis ===
An axis part is required in every animation that involves a rotating or moving thing.

<source>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</source>

The axis are similar to the ones of the 3D model. There is a difference between rotation and translation:
* In rotation animations, the axis part defines around what axis the object rotates. Negative/positive values make the difference between counterclockwise and clockwise rotations.
* In translate animations, the part defines along what axis the object moves. If the x-axis is poiting backwards, an x-value of -1 will result in forward motion.

You could also define two points, between which FlightGear will calculate the correct axis. This makes the use of a [[#Center|<nowiki><center></nowiki>]] tag redundant! Such coordinates are extremely useful for animating control surfaces (rudder, elevators etc.).

<source>
<axis>
<x1-m> 4.9</x1-m>
<y1-m> 7.1</y1-m>
<z1-m>-1.0</z1-m>
<x2-m> 5.9</x2-m>
<y2-m>11.2</y2-m>
<z2-m>-0.5</z2-m>
</axis>
</source>

=== Center ===
Various animations ([[#Rotate|rotate]], [[#Spin|spin]]) move around a center point.

<source>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
</source>

The axis are similar to the ones of the 3D model, so finding coordinates is easily done in 3D modeling software.

=== Conditions ===
Multiple animations can make use of a conditional. Check <tt>$FGDATA/Docs/README.conditions</tt> for some more details.

* '''equals:''' property value (or second property) is equal to value/(first)property.
* '''greater-than:''' property value (or second property) is larger than value/(first)property.
* '''greater-than-equals:''' property value (or second property) is greater than or equal to value/(first)property.
* '''less-than:''' property value (or second property) is smaller than value/(first)property.
* '''less-than-equals:''' property value (or second property) is smaller than or equal to value/(first)property.

The example below is true when n1 has a value greater than 25.
<source>
<condition>
<greater-than>
<property>engines/engine[1]/n1</property>
<value>25</value>
</greater-than>
</condition>
</source>

Then there are some special tags:

* '''and:'''
* '''not:'''
* '''or:'''

In the example below, the condition is true when either n1 is greater than 25% or equal to 0%.
<source>
<condition>
<or>
<greater-than>
<property>engines/engine[1]/n1</property>
<value>25</value>
</greater-than>
<equals>
<property>engines/engine[1]/n1</property>
<value>0</value>
</equals>
</or>
</condition>
</source>

An example of implementation into an animation looks as follows:

<source>
<animation>
<object-name>Object</object-name>
<type>rotate</type>
<property>suface-positions/left-aileron-pos-norm</property>
<factor>25</factor>
<condition>
<greater-than>
<property>suface-positions/left-aileron-pos-norm</property>
<value>10</value>
</greater-than>
</condition>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

=== Interpolation ===
For non-fixed factors, an interpolation "table" can be created.

<source>
<interpolation>
<entry>
<ind> 0.0</ind>
<dep> 0.0</dep>
</entry>
<entry>
<ind> 0.667</ind>
<dep> 0.0</dep>
</entry>
<entry>
<ind> 1.0</ind>
<dep> 0.5</dep>
</entry>
</interpolation>
</source>

The lines above represent the following table:

{|
!Input
!Output
|-
|0.0
|0.0
|-
|0.667
|0.0
|-
|1.0
|0.5
|}

You can add as many entries as you need. Interpolation tables are often used for gear animations (eg. to open doors during gear-movements and close them again once the gear is either retracted or fully extended).

=== Name ===
With a name animation, you can group multiple objects.

<source>
<animation>
<name>Collection1</name>
<object-name>Object1</object-name>
<object-name>Object2</object-name>
<object-name>Object3</object-name>
</animation>
</source>

The example above creates a "virtual object" with the name Collection1. In animation, we can animate this group of objects, by using:

<source>
<object-name>Collection1</object-name>
</source>

=== Object-name ===
These names are set in the 3D model. Each single object has a unique name; for easy identification it is advised to use descriptive names (LeftElevator, Rudder etc.). Animations are only applied to those objects that are mentioned in an object-name line (one object per line!). Animations lacking those, will be applied to the entire model.

== Animation types ==
=== Alpha-test ===
<source>
<animation>
<type>alpha-test</type>
<object-name>Object</object-name>
<alpha-factor>0.01</alpha-factor>
</animation>
</source>

=== Billboard ===
This faces an object towards the viewer. Often used on 2D objects, like clouds, trees and lights.

<source>
<animation>
<type>billboard</type>
<object-name>Object</object-name>
<spherical type="bool">true</spherical>
</animation>
</source>

* '''spherical:'''

=== Dist-scale ===
Used to scale an object, based on the distance to the viewer.

<source>
<animation>
<type>dist-scale</type>
<object-name>Object</object-name>
<interpolation>
<entry>
<ind>0</ind>
<dep>1</dep>
</entry>
<entry>
<ind>300</ind>
<dep>4</dep>
</entry>
<entry>
<ind>1500</ind>
<dep>8</dep>
</entry>
</interpolation>
</animation>
</source>

=== Enable-hot ===
Scenery objects are automatically defined as solid by FlightGear, meaning that an aircraft can taxi on them and/or crash when touching. For certain objects (groundmarkings, beacon light-beams etc.) this might be an unwanted feature. The solidness can be disabled with the following animation:

<source>
<animation>
<object-name>Object</object-name>
<enable-hot type="bool">false</enable-hot>
</animation>
</source>

* '''enable-hot:''' can be either true or false. Remember that objects are automatically solid, so it should not be nesecarily to set this at all when wanting solidness.

=== Flash ===
<source>
<animation>
<type>flash</type>
<object-name>Object</object-name>
<offset>0.0</offset>
<factor>1.0</factor>
<power>2</power>
<two-sides type="bool">false</two-sides>
<min>0.0</min>
<max>1.0</max>
<center>
<x-m>0.0</x-m>
<y-m>0.0</y-m>
<z-m>0.0</z-m>
</center>
<axis>
<x>0.0</x>
<y>-1</y>
<z>0.1</z>
</axis>
</animation>
</source>

* '''offset:'''
* '''factor:'''
* '''power:'''
* '''two-sides:'''
* '''min:'''
* '''max:'''

=== Interactions ===
<source>
<animation>
<type>interaction</type>
<object-name>Object</object-name>
<interaction-type>carrier-wire</interaction-type>
</animation>
</source>

* '''interaction-type:''' can have the following values:
** '''carrier-catapult:'''
** '''carrier-wire:''' makes the object act as an arresting wire, as used on [[aircraft carrier]]s.

=== Material ===
An animation type that can be used in various ways. Of course you can combine the below mentiond systems into one (big) animation.

<source>
<animation>
<type>material</type>
<object-name>Object</object-name>
<property-base>sim/model/c172p/material</property-base>
<global type="bool">true</global>
...
lines as mentioned below
...
</animation>
</source>

'''Optional:'''
* '''property-base:''' when using prop(erties), you might want to set a property-base. All props will be relative to this path.
* '''global:''' by setting this to <tt>true</tt>, all objects using the same material as the defined object(s) (via <tt><object-name></tt>) will be affected by the animation. This is preferred to listing several objects in <object-name> tags. It's not only faster, but also doesn't break animations by forcing objects together.

'''Notes:'''
* Numbers are clamped to 0.0-1.0, except "shininess", which is clamped to 0-128.
* By appending <tt>-prop</tt> each of the material properties can read its value from another property.

==== Ambient ====
<source>
<ambient>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
</ambient>
</source>

==== Diffuse ====
<source>
<diffuse>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
</diffuse>
</source>

==== Emission ====
{{Main article|Howto: Illuminate faces}}
<source>
<emission>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
<factor-prop>controls/lighting/panel-norm</factor-prop>
</emission>
</source>

Emission colors are multiplied by the factor-prop value. 1 is maximum coclor intensity, while 0 is the minimum. Colors are calculated according to the [http://en.wikipedia.org/wiki/RGB_color_model RGB color model].

==== Shininess ====
Shininess is clamped to 0-128.
<source>
<shininess>105</shininess>
</source>

==== Specular ====
<source>
<specular>
<red>1.0</red>
<green>0.2</green>
<blue>0.0</blue>
</specular>
</source>

==== Texture ====
Used for the [[Livery over MP]] system.

<source>
<property-base>sim/model/livery</property-base>
<texture-prop>engine</texture-prop>
<texture>KLM.png</texture>
</source>

==== Transparency ====
<source>
<transparency>
<alpha-prop>rotors/tail/rpm</alpha-prop>
<factor>-0.0015</factor>
<offset>1</offset>
</transparency>
</source>

==== Threshold ====
<source>
<threshold>0.001</threshold>
</source>

=== Noshadow ===
<source>
<animation>
<type>noshadow</type>
<object-name>Object</object-name>
</animation>
</source>

=== Pick ===
{{Main article|Howto: Make a clickable panel#Pick}}

=== Range ===
To prevent objects -like instruments- being drawn when the aircraft is actually too far away for them to be seen anyway, a range animation is used.

<source>
<animation>
<type>range</type>
<min-m>0</min-m>
<max-m>30</max-m>
</animation>
</source>

* '''min-m:''' the shortest distance (in meters) from the object center at which it is visible.
* '''max-m:''' the largest distance (in meters) from the object center at which it is visible.

You could also use the generic level of detail (LOD) properties, which can be set by the user through View > Adjust LOD rangers:
* <tt>/sim/rendering/static-lod/bare</tt> distance at which only a rough exterior model is required.
* <tt>/sim/rendering/static-lod/rough</tt> distance at which most should be visible.
* <tt>/sim/rendering/static-lod/detailed</tt> distance at which all details should be visible.

The animation code will look like this:
<source>
<animation>
<type>range</type>
<min-m>0</min-m>
<max-property>sim/rendering/static-lod/bare</max-property>
</animation>
</source>

You can have both ranges (max and min) bound to a property, or just one of them.
* '''min-property:'''
* '''max-property:'''

=== Rotate ===
One of the most important and frequently used animations of all. It rotates an object to an absolute position in degrees, as provided by the property-value.

<source>
<animation>
<object-name>Object</object-name>
<type>rotate</type>
<property>suface-positions/left-aileron-pos-norm</property>
<factor>25</factor>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

* '''factor:''' is optional.

=== Scale ===
A scale animation scales (resizes) an object. This can be either property-value dependant (first example) or a fixed scale (second example).

<source>
<animation>
<type>scale</type>
<object-name>Object</object-name>
<property>sim/time/sun-angle-rad</property>
<x-min>1.0</x-min>
<y-min>1.0</y-min>
<z-min>1.0</z-min>
<x-factor>1.4</x-factor>
<y-factor>1.4</y-factor>
<z-factor>2.0</z-factor>
</animation>
</source>

* ?-min: the mimimum scale factor for each axis. If the property value would result in a smaller factor than this setting, the scale animation will hold.
* ?-factor: the scale factor for each axis (factor*property=scale factor).

<source>
<animation>
<type>scale</type>
<x-offset>0.5</x-offset>
<y-offset>0.5</y-offset>
<z-offset>0.5</z-offset>
</animation>
</source>

* x.offset: the scale factor.

=== Select ===
This animation selects (or unselects) objects when certain conditions are true (or false). The example below shows the object when the n1 of engine[1] is higher than 25%.

<source>
<animation>
<object-name>Object</object-name>
<type>select</type>
<condition>
<greater-than>
<property>engines/engine[0]/n1</property>
<value>25</value>
</greater-than>
</condition>
</animation>
</source>

=== Shader ===
<source>
<animation>
<type>shader</type>
<shader>chrome</shader>
<texture>chrome2.png</texture>
<object-name>Object</object-name>
</animation>
</source>

* '''shader:'''
* '''texture:''' path to the texture used by the shader.

=== Spin ===
Very similar to [[#Rotate|rotate]], but the property provides a value in revolutions per minute (RPM) rather than an absolute position in degrees, and offset cannot be used.

<source>
<animation>
<object-name>Object</object-name>
<type>spin</type>
<property>engines/engine[0]/n1</property>
<factor>25</factor>
<center>
<x-m>-1.50</x-m>
<y-m> 1 </y-m>
<z-m> 0.25</z-m>
</center>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

* '''factor:''' is optional.

=== Textranslate ===
A very important animation for cockpits! This animation moves textures over a surface.

<source>
<animation>
<type>textranslate</type>
<object-name>Object</object-name>
<property>autopilot/settings/target-speed-kt</property>
<factor>0.001</factor>
<step>100</step>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

* '''factor:'''
* '''step:'''
property * factor * step * texture width/height = the amount of pixels that the texture should be translated. If your texture is 256 pixels, an textranslate of 0.1 will result in the texture moving with 26 pixels, into the direction specified by the axis settings.

=== Timed ===
Swtiches between objects at specified intervals. This example switches between a lights-on model and a lights-off model. Lights on are shown 0.2 seconds, while lights off are displayed for 0.8 seconds.

<source>
<animation>
<type>timed</type>
<object-name>BacklightOn</object-name>
<object-name>BacklightOff</object-name>
<use-personality type="bool">true</use-personality>
<branch-duration-sec>0.8</branch-duration-sec>
<branch-duration-sec>0.2</branch-duration-sec>
</animation>
</source>

=== Translate ===
The same as [[#Textranslate|textranslate]], but this animation moves a whole object (so including fixed textures). The example below will move an object 5 meters in the y-direction.

<source>
<animation>
<type>translate</type>
<object-name>Object</object-name>
<property>controls/seat/pilot/position-norm</property>
<factor>5</factor>
<axis>
<x>0</x>
<y>1</y>
<z>0</z>
</axis>
</animation>
</source>

==References==
* [http://www.opensubscriber.com/message/flightgear-devel@flightgear.org/958955.html "material" animation (and the bo105 as an example)]
by Melchior Fanz, March 22 2005.

[[Category:Aircraft enhancement|Animate models]]
[[Category:Howto|Animate models]]
[[Category:Modeling|Animate models]]
[[Category:Scenery enhancement|Animate models]]

Howto:Coding a Boeing CDU

2011-04-08T21:05:53Z

Hcc23: /* Examples */

{{WIP|[[User:Hcc23|Hcc23]] is working on this. Find him in the FG IRC channel to discuss this page.}}

[[User:Gijs|Gijs]] has started an effort to bring a generic Boeing [[CDU]] to [[FlightGear]]. This page tries to describe the coding for this effort.

= The Sources =
The [[CDU]] currently resides in '''$FGDATA/Aircraft/Instruments-3d/cdu/'''.

'''Graphics''':
* <tt>boeing.ac</tt>: This is a [[AC3D]] file, describing the 3D outline of the CDU model.
* <tt>boeing_brown.png</tt>: A texture bitmap.
* <tt>boeing_grey.png</tt>: A texture bitmap.

'''XML''':
* <tt>boeing.xml</tt>: This is the main [[XML]] file, providing the direct interface between the 3D model and the code. This file also defines the keypress interactions and the positioning of the text to be displayed in the screen.
* <tt>display-matrix-text.xml</tt>: An OSGText "model", used as a baseline for the texts on the screen. Compare to <tt>README.osgtext</tt>.

'''Nasal''':
* <tt>boeing_cdu.nas</tt>: This is the main [[Nasal]] script file to be edited by the ''user'' of the CDU Nasal framework.
* <tt>cdu_page_framework.nas</tt>: This is the main file of the CDU framework. It defines the main ''classes'' used for the CDU.
* <tt>display_matrix.nas</tt>: This file contains the Nasal relevant for the dispaly matrix. This code might be useful for other complex screen-based instruments.
* <tt>helping_functions.nas</tt>: This file contains functions which I found useful for my project, but which are totally generic and could be used for other stuff as well.
* <tt>timer.nas</tt>: This file contains a rudimentary timer ''class'' and an example of how to incorporate this with a generic class for an instrument button, allowing the button to call different Nasal scripts, depending on how long it has been pressed.

* <tt>README</tt>: Well, a readme.

== Loading a CDU into an Aircraft ==
Here is how the CDU is loaded into the Boeing 777-200:

In <tt>777-22ER-set.xml</tt> the Nasal node is expanded as follows:
<nasal>
...
<cdu>
<nowiki></nowiki>
<file>Aircraft/Instruments-3d/cdu/helping_functions.nas</file>
<file>Aircraft/Instruments-3d/cdu/display_matrix.nas</file>
<file>Aircraft/Instruments-3d/cdu/timer.nas</file>
<file>Aircraft/Instruments-3d/cdu/cdu_page_framework.nas</file>
<nowiki></nowiki>
<file>Aircraft/Instruments-3d/cdu/b777_cdu.nas</file>
</cdu>
</nasal>
Note the difference in the framework files and the actual ''instance'' used for this aircraft. To code pages for the CDU, one would normally not have to mess with the framework files. [[User:Hcc23|Hcc23]]

'''NOTE:''' Somewhere in the actual 3D model of the aircraft the <tt>boeing.xml</tt> for the 3D model of the CDU has to be loaded. I haven't looked for that yet as that was already done for the 777-200. [[User:Hcc23|Hcc23]] 14:42, 8 April 2011 (EDT)

== 3D Graphics ==
The 3D model resides in the file '''<tt>$FGDATA/Models/Cockpit/Instruments/CDU/cdu.ac</tt>'''. This is a [[AC3D]] file format, but it should be importable by [[Blender]].
{|
|-valign="top"
| [[File:CDU_3D_wireframe.png|thumb|270px|The wireframe of the 3D model and the corresponding coordinate system. ATTENTION: the axis are not right: RED is +X, GREEN is +Z, BLUE is -Y !]]
| [[File:CDU.png|thumb|270px|The texture of the CDU, a 512x512 PNG bitmap.]]
| [[File:CDU_3D_textures.png|thumb|270px|The resulting 3D model, after the textures have been added.]]
|}
The model also specifies the model internal coordinate system. It is indicated in the pictures through the corresponding axis: X (red), Y (green), and Z (blue). The origin of this coordinate system seems to coincide with the geometric center of the back plane of the [[CDU]], i.e. the YZ-plane is coplanar with the back of the [[CDU]]. The unit of the coordinate system is the SI unit ''Meter''.

The 3D model has bindings defined to each button. So when a certain button is clicked, something happens. Right now most buttons are only used
to open other [[CDU]]-pages.

=== The Screen of the CDU ===
With respect to the model coordinate frame, the screen is the rectangle given by:

Top edge: z= 0.111, x=0.004
Lower edge: z= 0.019, x=0.004
Left edge: y=-0.051, x=0.004
Right edge: y= 0.051, x=0.004

= The Code Framework =

The CDU framework is implemented following some classic object-oriented ideas, completely implemented in Nasal. All variables are instanciated using <tt>var</tt> so that the global namespace should not be tainted.

The idea for the framework stems from the fact that a CDU is based upon the idea of ''pages'', some of which could occupy several screens. This, in conjunction with the idea of the ''fields'' (stipulated from the screen layout of the CDU) resulted in the following framework:
CDU
|
|-BasePage
| |
| |-SubPage
| | |
| | |-Field
| | |-Field
| | |-...
| |
| |-SubPage
| | |-Field
| | |-Field
| | |-...
| |
| |-...
|
|-BasePage
| |
| |-SubPage
| |
| |-Field
| |-Field
| |-...
|
|-...
Well, you get the idea....

These three ''classes'' (BasePage, SubPage, Field) are defined in <tt>cdu_framework.nas</tt>. The constructors are generally called <tt>.new()</tt>, all ''memberss'' are created within the constructors, all ''static'' parts are implemented directly on the hash level.

Beside these three classes the class <tt>ScreenText</tt> (defined in <tt>display_matrix.nas</tt>) is used to house the actual text to be printed.

All text is then kept internal to Nasal within the beforementioned structure. The text is then also kept in the FlightGear property tree so that an interface to osgtext can be established via <tt>boeing.xml</tt>.

'''NOTE:''' There is a <tt>DEBUG</tt> variable set in the CDU framework. Setting this variable to non-zero enables a bunch of console printouts, implemented via <tt>DEBUG?print('....'):;</tt> Furthermore, when calling a constructor, the parameter <tt>ptp</tt> (for path-to-property) can be set, enabling some member variables of the classes to register themselves in the property tree, allowing an easier debugging during runtime. [[User:Hcc23|Hcc23]] 15:20, 8 April 2011 (EDT)

== Examples ==
Maybe looking at the actual code is the easiest way of understanding how the framework works. (I also tried to be fairly explicit in my in-code comments, so looking at the sources should actually be helpful, too. [[User:Hcc23|Hcc23]] 15:46, 8 April 2011 (EDT))

As the framework is separate from the ''instanciation'', let's focus on that as that is the part a ''user'' should care mostly about. The relevant file for the Boeing 777-200 is <tt>boeing_cdu.nas</tt>

=== Preliminaries===
#####################################################
# These variables have already been defined in
# cdu_page_framework but can (?) be redifined here
# for slightly changed versions.
#####################################################

var ROWS = 14; # the number of lines the CDU has
var COLS = 24; # the number of characters each line can hold
var PROP = "/instrumentation/cdu"; # generic path to the properties of this CDU
var DEBUG = 1; # enable a more verbose "debug" mode, i.e. register all kinds of stuff in the property tree

resetDisplayMatrix();
This essential defines the size of the dispaly matrix, enables the debug printout and clears the display matrix in the property tree.
(<tt>resetDisplayMatrix();</tt> fills the complete display matrix with spaces ( ) and also set the style to <tt>"off"</tt>.)

===Making the BasePages===
# make the pages
var page_menu = BasePage.new("MENU",PROP~"/page_menu");
KeyBinding["MENU"] = func() {page_menu.displayPage(); }; # Note : do NOT forget to wrap displayPage with a function!
var page_index = BasePage.new("INDEX",PROP~"/page_index");
var page_ident = BasePage.new("IDENT",PROP~"/page_ident");
var page_pos = BasePage.new("POS",PROP~"/page_pos");
var page_perf = BasePage.new("PERF",PROP~"/page_perf");
var page_thrustLim = BasePage.new("THRUST LIM",PROP~"/page_thurstLim");
var page_takeoff = BasePage.new("TAKEOFF",PROP~"/page_takeoff");
var page_approach = BasePage.new("APPROACH",PROP~"/page_approach");
var page_navData = BasePage.new("NAV DATA",PROP~"/page_navData");
var page_maint = BasePage.new("MAINT",PROP~"/page_maint");
This section creates the base pages of the CDU. The constructor for base pages is this one:
new: func(name,ptp=nil) {...};
What this essentially does is creating a container to house sub pages. The <tt>name</tt> element is used as the title of the page (but this could be overwritten in a sub page), the <tt>ptp</tt>, if set, registers the base page at that path. (However, if the <tt>DEBUG</tt> variable is set, the the pages are registered by their internal ID in a <tt>DEBUG</tt> path underneath the CDU.)

When a base page constructor is called, it also creates a ''home''-method. This function can be used to make the corresponding base page the active page, i.e. display that page. As you can see above, the corresponding method of the MENU page is assigned to the related button of the CDU. <tt>KeyBinding</tt> is defined in <tt>cdu_framework.nas</tt>, for a list of the available buttons see <tt>boeing.xml</tt>.

===Making a SubPage (and the corresponding Fields)===
#######################
# DETAILS PAGE MENU
#######################
#
DEBUG?print("CDU_NOTE: Starting to make details for page "~"MENU"):;

# create the subpages
var page_menu_default = SubPage.new(page_menu,"MENU",page_menu.ptp~"/sub_default");

# create the fields
var field_fmc = Field.new("","FMC",page_ident.activate);

# register the fields in the subpage, remember, it's zero indexed
page_menu_default.left_field[0]=field_fmc;

#activate the page (and display it consequentially)
page_menu_default.activate();
This code section starts to fill in the details of the page MENU. As outlined in the framework, each base page houses sub pages, which in turn house the fields (which hold the actual content). So we need to start by making a sub page:
# create the subpages
var page_menu_default = SubPage.new(page_menu,"MENU",page_menu.ptp~"/sub_default");
The constructor for a sub page looks like this:
new: func(parent_base_page,name=nil,ptp=nil) {...};
The elements are fairly straight forward:
* parent_base_page: parent node of this sub page (which is a base page). Note that this is not the name of that page, but the actual page, i.e. put down the name of the variable you made earlier. Here, this is a sub page of <tt>page_menu</tt>, i.e. the MENU page, which was made earlier.
* name: similar to the name of a base page, it is used as the title entry of the sub page. If a sub page has a name (which it doesn't need to have), the name of the sub page overwrites the name of the base page, such allowing for slightly different titles on each "screen" of a CDU "page". Note, however, that the display of the page count is taken care of, i.e. you do not have to put that into the title.
* ptp: same as with the base page. Also identical, the registration is changed to registration by ID when the DEBUG variable is non-zero.

After a sub page has been made, one needs to make fields to actually hold content:
# create the fields
var field_fmc = Field.new("","FMC",page_ident.activate);

# register the fields in the subpage, remember, it's zero indexed
page_menu_default.left_field[0]=field_fmc;
The first part creates a field, the field constructor is:
new: func(label,data,key_action=nil,ptp=nil) {...};
This constructor is a little more complex than the previous ones:
* <tt>label</tt>: the entry for the label line (the top line) of the field.
* <tt>data</tt>: the entry for data line (the lower line) of the field.
* <tt>key_action</tt>: as fields have an line select key associated with them, <tt>key_action</tt>, a function element, determines what happens when the LSK next to the data line is pressed.
* <tt>ptp</tt>: registering the field. As for base and sub pages, a non-zero DEBUG changes the ptp.

In order to make the construction of a field a little more convenient, some very limited type of constructor overloading is incorporated. Both lines could be initialized with either an element of type <tt>ScreenText.new()</tt> (defined in <tt>display_matrix.nas</tt>), i.e. a hash, or it can be initialized with a vector or elements, i.e. with <tt>[ScreenText.new() ScreenText.new() ...]</tt>. (More on why this is nice to have later.)

# register the fields in the subpage, remember, it's zero indexed
page_menu_default.left_field[0]=field_fmc;
This part of the code puts this field into the top-left position in the sub page. Each sub page has two columns (<tt>SubPage.left_field[]</tt> and <tt>SubPage.right_field[]</tt>) of six elements each. The columns are zero indexed.
#activate the page (and display it consequentially)
page_menu_default.activate();
This part activates this sup page. Sub page activation is slightly different from base page displaying. The later jumps to the base page and displays whatever sub page is active, <tt>SubPage.activate()</tt> activates the corresponding sub page in the parent base page and then calls the display function of that page, effectively displaying the sub page.

===Making a more complex SubPage===
Here just the code:
#######################
# DETAILS PAGE IDENT
#######################
#
DEBUG?print("CDU_NOTE: Starting to make details for page "~"IDENT"):;

# create the subpages
var page_ident_default = SubPage.new(page_ident,name=nil,ptp="/sub_default");

DEBUG?print("CDU_NOTE: Starting to make fields for page "~"IDENT"):;
# create the fields
var field_model = Field.new("MODEL",ScreenText.new(['%s','/instrumentation/cdu/ident/model'],ScreenText["WHITE"]));
var field_engines = Field.new("ENGINES",ScreenText.new(['%s','/instrumentation/cdu/ident/engines'],ScreenText["WHITE"]));
var field_navData = Field.new("NAV DATA","----");
var field_navData_active = Field.new("ACTIVE","----");
var field_navData_inactive = Field.new(ScreenText.new("INACTIVE",ScreenText["off"],nil),"----");
var field_dragFf = Field.new("DRAG/FF","+0.0/+0.0");

# register the fields in the subpage, remember, it's zero indexed
page_ident_default.left_field[0]=field_model;
page_ident_default.left_field[1]=field_navData;
page_ident_default.left_field[5]=page_index.home;
page_ident_default.right_field[0]=field_engines;
page_ident_default.right_field[1]=field_navData_active;
page_ident_default.right_field[2]=field_navData_inactive;
page_ident_default.right_field[4]=field_dragFf;
page_ident_default.right_field[5]=page_pos_init.home;

# place the separators
page_ident_default.separators = [11];

#activate the page (and display it consequentially)
page_ident_default.activate();
The only new thing here is the use of the more complex version of the screen text constructor and the line
page_ident_default.right_field[5]=page_pos_init.home;
What this does is assigning an auto-generate field of a sub page to a field in another sub page. Thes auto-generated fields can be used to directly activate these sub pages.

= The CDU Screen =
One of the major problems of the CDU is the representation of the actual screen. According to the Honeywell manual, the CDU utilized by Boeing has a fixed setup.

== Details of the (LCD) Screen ==
The LCD has '''14 lines''' with a total of '''24 characters per line'''. The page format is formatted as follows:

* Title Field: The top line of the display area. Id identifies the subject or title of the data displayed on the page in view. It also identifies page number and the number of pages in series, e.g., <tt>1/2</tt> identifies a page as the first in a series of two pages.
* Left Field: 6 pairs of lines, 11 characters per line. It extends from the left side of the screen to the center. The pilot has access to one line of each pair through a LSK (Line-Select Key) on the left side of the CDU. A line pair is made up of a label and a data line.
* Right Field: This field is similar to the left field, extending from the center of the screen to the right side. Pilot access is available by a LSK on the right side.
* Scratchpad: The bottom line of the display screen. This line displays alphanumeric data or messages. Data can be entered with the alphanumeric keys or the LSK, or by the FMC. Scratchpad entry cannot, normally, be made with a FMC message in the scratchpad. Scratchpad entries are independent of page selection, and remain until cleared even when page changes occur. Scratchpad data entries and erases affect only the associated CDU. Messages can appear and be erased on both CDUs simultaneously.

== Internal Representation ==
[[File:CDU HelloWorld.png|thumb|270px|The utilizes display matrix, showing the text bounding boxes for clarity.]]
As the screen has a "fixed" resolution, internally the screen is represented as a 14-by-24(-by-2) matrix. The zero-indexed matrix is held in the property tree:

/instrumentation/cdu/display/row-0/col-0/char # the character printed on the screen
/instrumentation/cdu/display/row-0/col-0/style # the style or format of the printed screen.

<tt>.../char</tt> is a Nasal string-type variable. <tt>.../style</tt> is a Nasal double-type variable (although it is only integers).

The style of the char is encoded via a binary key-map:

# styles binary # wmcgLS -> decimal
"off": 0, # 000000 0
# small and LARGE types
"white": 32, # 100000 -> 32 # the default style
"magenta": 16, # 010000 -> 16
"cyan": 8, # 001000 -> 8
"green": 4, # 000100 -> 4
"WHITE": 34, # 100010 -> 34
"MAGENTA": 18, # 010010 -> 18
"CYAN": 10, # 001010 -> 10
"GREEN": 6, # 000110 -> 6
# shaded small and shaded LARGE types
"white_": 33, # 100001 -> 33
"magenta_": 7, # 010001 -> 7
"cyan_": 9, # 001001 -> 9
"green_": 5, # 000101 -> 5
"WHITE_": 35, # 100011 -> 35
"MAGENTA_": 19, # 010011 -> 19
"CYAN_": 11, # 001011 -> 11
"GREEN_": 9, # 000111 -> 9

Each style has a name (used in the Nasal code for the CDU), which is resolved into a decimal integer. The integer is defined via a binary key:
the first group represents the colors: white (<tt>w</tt>), magenta (<tt>m</tt>), cyan (<tt>c</tt>), and green (<tt>g</tt>). The second group represents the font style: large fonts (<tt>L</tt>) and a shaded background (<tt>S</tt>).

This concept is translated into the names of the style: it is the name of the color, all lowercase for small fonts, all uppercase for large fonts, and an attached underscore (<tt>_</tt>) to indicate the selection of a shaded background.

'''NOTE:''' The styles are currently not yet implemented. [[User:Hcc23|Hcc23]] 14:01, 8 April 2011 (EDT)

== Nasal Code ==
The [[Nasal]] code for the display matrix is mainly held in <tt>display_matrix.nas</tt>.
The key element of making text appear on the 3D screen is the Nasal class <tt>ScreenText</tt>

<tt>ScreenText</tt>-elements make up the label and data lines of fields. Several elements can be concattenated in a single line by stacking them in a vector. The constructor for screen text is:
new: func(t,s=32,ptp=nil)
The two elements are text (t) and style (s). Let's look at them in detail:
* <tt>s</tt>: style is an integer according to the above binary key. In order to make life easier, one can directly use the ''static'' hash members, e.g. <tt>ScreenText["white"]</tt> for small, white text; or <tt>ScreenText["GREEN_"]</tt> for large, green text with a shaded background.
* <tt>t</tt>: is the text element. Here some limited constructor overloading can be used.

The constructor overlaoding allows for an easy creating of ''just'' plain text:
var test_text = ScreenText.new("Hello World!",ScreenText["WHITE"]);
However, it could also be used to get a property from the property tree.
var test_prop = ScreenText.new(["This is a %s aircraft","/instrumentation/cdu/ident/aircraft"],ScreenText["WHITE"]);
The last call uses the property <tt>/instrumentation/cdu/ident/aircraft<tt> in a screen text element. The result is comparable to
sprintf("This is a %s aircraft",getprop("/instrumentation/cdu/ident/aircraft"));
Furthermore, whenever a property is used in a screen text element on a subpage, the suppage, when displayed, registers listeners on all utilized properties, resulting in updated data on the screen. When the sup page is changed, the listeners are de-registered.

== XML Code ==
The [[XML]] side of the display matrix comes in multiple parts. <tt>boeing.xml</tt> contains all the [[XML]] code for the CDU.
Other than loading the 3D model and defining the button names, <tt>boeing.xml</tt> also interfaces with [[osgtext]] to actually display text in the 3D model.

In <tt>boeing.xml</tt> you will find sections like this one:

<model>
<path>Aircraft/Instruments-3d/cdu/display_matrix_text.xml</path>
<overlay>
<params>
<property type="string">/instrumentation/cdu/display/row-0/col-0/char</property>
</params>
<offsets>
<x-m>0.005</x-m>
<y-m>-0.044</y-m>
<z-m>0.103</z-m>
</offsets>
</overlay>
</model>

This section defines which node of the matrix to display, indicated by <tt><property type="string">/instrumentation/cdu/display/row-0/col-0/char</property></tt> for the (0,0) node of the matrix, i.e. to first character in the topmost line.

This [[XML]] section expands on <tt>Aircraft/Instruments-3d/cdu/display_matrix_text.xml</tt> which gives some underlying structure. For more details on this, please consult <tt>$FGDATA/Docs/README.osgtext</tt>.

'''NOTE:''' I haven't completely understood how this <tt><overlay /></tt> node actually works, but this setup does what I want it to do. Please feel free to change and explain it here. [[User:Hcc23|Hcc23]] 14:23, 8 April 2011 (EDT)

'''NOTE:''' As mentioned above, the style information is not yet implemented. I would like to put that into the [[XML]] in <tt>Aircraft/Instruments-3d/cdu/display_matrix_text.xml</tt>, but I don't know how to do conditionals in XML. [[User:Hcc23|Hcc23]] 14:23, 8 April 2011 (EDT)

=== Generating the offset code ===
As you might have figured, there is a lot of identical XML code, just differing in the offset parameters and the row and column index. To make life easier I have written this Matlab script to auto-generate these sections:

<code>
clear all, close all, clc

%% Parameters
% These are to be set by the user

FILENAME = 'autocoded.xml';

ROWS = 14;
COLS = 24;

TOP = 0.106; % z-axis
BOTTOM = 0.024; % z-axis
LEFT = -0.046; % y-axis
RIGHT = 0.046; % y-axis

ELEV = 0.005; % x-axis

TEMPLATE = 'Aircraft/Instruments-3d/cdu/display_matrix_text.xml';

%% Creating the printout

fid = fopen(FILENAME,'wb');

width_of_screen = abs(RIGHT-LEFT);
hight_of_screen = abs(TOP-BOTTOM);

delta_col = width_of_screen/COLS;
delta_row = hight_of_screen/ROWS;

x_off = ELEV;
z_off = TOP - 0.5*delta_row;
y_off_zero = LEFT + 0.5*delta_col;

for row = 0:1:ROWS-1
y_off = y_off_zero;
for col = 0:1:COLS-1

propertyPath = sprintf('/instrumentation/cdu/display/row-%d/col-%d/char',row,col);

fprintf(fid,[...
'<model>\n',...
'\t<path>%s</path>\n',...
'\t<overlay>\n',...
'\t\t<params>\n',...
'\t\t\t<property type="string">%s</property>\n',...
'\t\t</params>\n',...
'\t\t<offsets>\n',...
'\t\t\t<x-m>%.3f</x-m>\n',...
'\t\t\t<y-m>%.3f</y-m>\n',...
'\t\t\t<z-m>%.3f</z-m>\n',...
'\t\t</offsets>\n',...
'\t</overlay>\n',...
'</model>\n',...
],...
TEMPLATE,...
propertyPath,...
x_off,y_off,z_off);

y_off = y_off + delta_col;

end
z_off = z_off - delta_row;
end

fclose(fid);
</code>

= The Property Tree =

The [[CDU]] also has some properties in the general [[FlightGear]] [[Property Tree]].
In general it is located in <code>/instrumentation/cdu/</code>.

= A Brief History of the Boeing CDU in FlightGear =
Find some more information on the [[CDU]] at these pages:
* [[CDU]]
* [[Howto: Implement a Control Display Unit]]

Howto:Coding a Boeing CDU

2011-04-08T21:01:58Z

Hcc23: /* Nasal Code */

{{WIP|[[User:Hcc23|Hcc23]] is working on this. Find him in the FG IRC channel to discuss this page.}}

[[User:Gijs|Gijs]] has started an effort to bring a generic Boeing [[CDU]] to [[FlightGear]]. This page tries to describe the coding for this effort.

= The Sources =
The [[CDU]] currently resides in '''$FGDATA/Aircraft/Instruments-3d/cdu/'''.

'''Graphics''':
* <tt>boeing.ac</tt>: This is a [[AC3D]] file, describing the 3D outline of the CDU model.
* <tt>boeing_brown.png</tt>: A texture bitmap.
* <tt>boeing_grey.png</tt>: A texture bitmap.

'''XML''':
* <tt>boeing.xml</tt>: This is the main [[XML]] file, providing the direct interface between the 3D model and the code. This file also defines the keypress interactions and the positioning of the text to be displayed in the screen.
* <tt>display-matrix-text.xml</tt>: An OSGText "model", used as a baseline for the texts on the screen. Compare to <tt>README.osgtext</tt>.

'''Nasal''':
* <tt>boeing_cdu.nas</tt>: This is the main [[Nasal]] script file to be edited by the ''user'' of the CDU Nasal framework.
* <tt>cdu_page_framework.nas</tt>: This is the main file of the CDU framework. It defines the main ''classes'' used for the CDU.
* <tt>display_matrix.nas</tt>: This file contains the Nasal relevant for the dispaly matrix. This code might be useful for other complex screen-based instruments.
* <tt>helping_functions.nas</tt>: This file contains functions which I found useful for my project, but which are totally generic and could be used for other stuff as well.
* <tt>timer.nas</tt>: This file contains a rudimentary timer ''class'' and an example of how to incorporate this with a generic class for an instrument button, allowing the button to call different Nasal scripts, depending on how long it has been pressed.

* <tt>README</tt>: Well, a readme.

== Loading a CDU into an Aircraft ==
Here is how the CDU is loaded into the Boeing 777-200:

In <tt>777-22ER-set.xml</tt> the Nasal node is expanded as follows:
<nasal>
...
<cdu>
<nowiki></nowiki>
<file>Aircraft/Instruments-3d/cdu/helping_functions.nas</file>
<file>Aircraft/Instruments-3d/cdu/display_matrix.nas</file>
<file>Aircraft/Instruments-3d/cdu/timer.nas</file>
<file>Aircraft/Instruments-3d/cdu/cdu_page_framework.nas</file>
<nowiki></nowiki>
<file>Aircraft/Instruments-3d/cdu/b777_cdu.nas</file>
</cdu>
</nasal>
Note the difference in the framework files and the actual ''instance'' used for this aircraft. To code pages for the CDU, one would normally not have to mess with the framework files. [[User:Hcc23|Hcc23]]

'''NOTE:''' Somewhere in the actual 3D model of the aircraft the <tt>boeing.xml</tt> for the 3D model of the CDU has to be loaded. I haven't looked for that yet as that was already done for the 777-200. [[User:Hcc23|Hcc23]] 14:42, 8 April 2011 (EDT)

== 3D Graphics ==
The 3D model resides in the file '''<tt>$FGDATA/Models/Cockpit/Instruments/CDU/cdu.ac</tt>'''. This is a [[AC3D]] file format, but it should be importable by [[Blender]].
{|
|-valign="top"
| [[File:CDU_3D_wireframe.png|thumb|270px|The wireframe of the 3D model and the corresponding coordinate system. ATTENTION: the axis are not right: RED is +X, GREEN is +Z, BLUE is -Y !]]
| [[File:CDU.png|thumb|270px|The texture of the CDU, a 512x512 PNG bitmap.]]
| [[File:CDU_3D_textures.png|thumb|270px|The resulting 3D model, after the textures have been added.]]
|}
The model also specifies the model internal coordinate system. It is indicated in the pictures through the corresponding axis: X (red), Y (green), and Z (blue). The origin of this coordinate system seems to coincide with the geometric center of the back plane of the [[CDU]], i.e. the YZ-plane is coplanar with the back of the [[CDU]]. The unit of the coordinate system is the SI unit ''Meter''.

The 3D model has bindings defined to each button. So when a certain button is clicked, something happens. Right now most buttons are only used
to open other [[CDU]]-pages.

=== The Screen of the CDU ===
With respect to the model coordinate frame, the screen is the rectangle given by:

Top edge: z= 0.111, x=0.004
Lower edge: z= 0.019, x=0.004
Left edge: y=-0.051, x=0.004
Right edge: y= 0.051, x=0.004

= The Code Framework =

The CDU framework is implemented following some classic object-oriented ideas, completely implemented in Nasal. All variables are instanciated using <tt>var</tt> so that the global namespace should not be tainted.

The idea for the framework stems from the fact that a CDU is based upon the idea of ''pages'', some of which could occupy several screens. This, in conjunction with the idea of the ''fields'' (stipulated from the screen layout of the CDU) resulted in the following framework:
CDU
|
|-BasePage
| |
| |-SubPage
| | |
| | |-Field
| | |-Field
| | |-...
| |
| |-SubPage
| | |-Field
| | |-Field
| | |-...
| |
| |-...
|
|-BasePage
| |
| |-SubPage
| |
| |-Field
| |-Field
| |-...
|
|-...
Well, you get the idea....

These three ''classes'' (BasePage, SubPage, Field) are defined in <tt>cdu_framework.nas</tt>. The constructors are generally called <tt>.new()</tt>, all ''memberss'' are created within the constructors, all ''static'' parts are implemented directly on the hash level.

Beside these three classes the class <tt>ScreenText</tt> (defined in <tt>display_matrix.nas</tt>) is used to house the actual text to be printed.

All text is then kept internal to Nasal within the beforementioned structure. The text is then also kept in the FlightGear property tree so that an interface to osgtext can be established via <tt>boeing.xml</tt>.

'''NOTE:''' There is a <tt>DEBUG</tt> variable set in the CDU framework. Setting this variable to non-zero enables a bunch of console printouts, implemented via <tt>DEBUG?print('....'):;</tt> Furthermore, when calling a constructor, the parameter <tt>ptp</tt> (for path-to-property) can be set, enabling some member variables of the classes to register themselves in the property tree, allowing an easier debugging during runtime. [[User:Hcc23|Hcc23]] 15:20, 8 April 2011 (EDT)

== Examples ==
Maybe looking at the actual code is the easiest way of understanding how the framework works. (I also tried to be fairly explicit in my in-code comments, so looking at the sources should actually be helpful, too. [[User:Hcc23|Hcc23]] 15:46, 8 April 2011 (EDT))

As the framework is separate from the ''instanciation'', let's focus on that as that is the part a ''user'' should care mostly about. The relevant file for the Boeing 777-200 is <tt>boeing_cdu.nas</tt>

=== Preliminaries===
#####################################################
# These variables have already been defined in
# cdu_page_framework but can (?) be redifined here
# for slightly changed versions.
#####################################################

var ROWS = 14; # the number of lines the CDU has
var COLS = 24; # the number of characters each line can hold
var PROP = "/instrumentation/cdu"; # generic path to the properties of this CDU
var DEBUG = 1; # enable a more verbose "debug" mode, i.e. register all kinds of stuff in the property tree

resetDisplayMatrix();
This essential defines the size of the dispaly matrix, enables the debug printout and clears the display matrix in the property tree.
(<tt>resetDisplayMatrix();</tt> fills the complete display matrix with spaces ( ) and also set the style to <tt>"off"</tt>.)

===Making the BasePages===
# make the pages
var page_menu = BasePage.new("MENU",PROP~"/page_menu");
KeyBinding["MENU"] = func() {page_menu.displayPage(); }; # Note : do NOT forget to wrap displayPage with a function!
var page_index = BasePage.new("INDEX",PROP~"/page_index");
var page_ident = BasePage.new("IDENT",PROP~"/page_ident");
var page_pos = BasePage.new("POS",PROP~"/page_pos");
var page_perf = BasePage.new("PERF",PROP~"/page_perf");
var page_thrustLim = BasePage.new("THRUST LIM",PROP~"/page_thurstLim");
var page_takeoff = BasePage.new("TAKEOFF",PROP~"/page_takeoff");
var page_approach = BasePage.new("APPROACH",PROP~"/page_approach");
var page_navData = BasePage.new("NAV DATA",PROP~"/page_navData");
var page_maint = BasePage.new("MAINT",PROP~"/page_maint");
This section creates the base pages of the CDU. The constructor for base pages is this one:
new: func(name,ptp=nil) {...};
What this essentially does is creating a container to house sub pages. The <tt>name</tt> element is used as the title of the page (but this could be overwritten in a sub page), the <tt>ptp</tt>, if set, registers the base page at that path. (However, if the <tt>DEBUG</tt> variable is set, the the pages are registered by their internal ID in a <tt>DEBUG</tt> path underneath the CDU.)

When a base page constructor is called, it also creates a ''home''-method. This function can be used to make the corresponding base page the active page, i.e. display that page. As you can see above, the corresponding method of the MENU page is assigned to the related button of the CDU. <tt>KeyBinding</tt> is defined in <tt>cdu_framework.nas</tt>, for a list of the available buttons see <tt>boeing.xml</tt>.

===Making a SubPage (and the corresponding Fields)===
#######################
# DETAILS PAGE MENU
#######################
#
DEBUG?print("CDU_NOTE: Starting to make details for page "~"MENU"):;

# create the subpages
var page_menu_default = SubPage.new(page_menu,"MENU",page_menu.ptp~"/sub_default");

# create the fields
var field_fmc = Field.new("","FMC",page_ident.activate);

# register the fields in the subpage, remember, it's zero indexed
page_menu_default.left_field[0]=field_fmc;

#activate the page (and display it consequentially)
page_menu_default.activate();
This code section starts to fill in the details of the page MENU. As outlined in the framework, each base page houses sub pages, which in turn house the fields (which hold the actual content). So we need to start by making a sub page:
# create the subpages
var page_menu_default = SubPage.new(page_menu,"MENU",page_menu.ptp~"/sub_default");
The constructor for a sub page looks like this:
new: func(parent_base_page,name=nil,ptp=nil) {...};
The elements are fairly straight forward:
* parent_base_page: parent node of this sub page (which is a base page). Note that this is not the name of that page, but the actual page, i.e. put down the name of the variable you made earlier. Here, this is a sub page of <tt>page_menu</tt>, i.e. the MENU page, which was made earlier.
* name: similar to the name of a base page, it is used as the title entry of the sub page. If a sub page has a name (which it doesn't need to have), the name of the sub page overwrites the name of the base page, such allowing for slightly different titles on each "screen" of a CDU "page". Note, however, that the display of the page count is taken care of, i.e. you do not have to put that into the title.
* ptp: same as with the base page. Also identical, the registration is changed to registration by ID when the DEBUG variable is non-zero.

After a sub page has been made, one needs to make fields to actually hold content:
# create the fields
var field_fmc = Field.new("","FMC",page_ident.activate);

# register the fields in the subpage, remember, it's zero indexed
page_menu_default.left_field[0]=field_fmc;
The first part creates a field, the field constructor is:
new: func(label,data,key_action=nil,ptp=nil) {...};
This constructor is a little more complex than the previous ones:
* <tt>label</tt>: the entry for the label line (the top line) of the field.
* <tt>data</tt>: the entry for data line (the lower line) of the field.
* <tt>key_action</tt>: as fields have an line select key associated with them, <tt>key_action</tt>, a function element, determines what happens when the LSK next to the data line is pressed.
* <tt>ptp</tt>: registering the field. As for base and sub pages, a non-zero DEBUG changes the ptp.

In order to make the construction of a field a little more convenient, some very limited type of constructor overloading is incorporated. Both lines could be initialized with either an element of type <tt>ScreenText.new()</tt> (defined in <tt>display_matrix.nas</tt>), i.e. a hash, or it can be initialized with a vector or elements, i.e. with <tt>[ScreenText.new() ScreenText.new() ...]</tt>. (More on why this is nice to have later.)

# register the fields in the subpage, remember, it's zero indexed
page_menu_default.left_field[0]=field_fmc;
This part of the code puts this field into the top-left position in the sub page. Each sub page has two columns (<tt>SubPage.left_field[]</tt> and <tt>SubPage.right_field[]</tt>) of six elements each. The columns are zero indexed.
#activate the page (and display it consequentially)
page_menu_default.activate();
This part activates this sup page. Sub page activation is slightly different from base page displaying. The later jumps to the base page and displays whatever sub page is active, <tt>SubPage.activate()</tt> activates the corresponding sub page in the parent base page and then calls the display function of that page, effectively displaying the sub page.

= The CDU Screen =
One of the major problems of the CDU is the representation of the actual screen. According to the Honeywell manual, the CDU utilized by Boeing has a fixed setup.

== Details of the (LCD) Screen ==
The LCD has '''14 lines''' with a total of '''24 characters per line'''. The page format is formatted as follows:

* Title Field: The top line of the display area. Id identifies the subject or title of the data displayed on the page in view. It also identifies page number and the number of pages in series, e.g., <tt>1/2</tt> identifies a page as the first in a series of two pages.
* Left Field: 6 pairs of lines, 11 characters per line. It extends from the left side of the screen to the center. The pilot has access to one line of each pair through a LSK (Line-Select Key) on the left side of the CDU. A line pair is made up of a label and a data line.
* Right Field: This field is similar to the left field, extending from the center of the screen to the right side. Pilot access is available by a LSK on the right side.
* Scratchpad: The bottom line of the display screen. This line displays alphanumeric data or messages. Data can be entered with the alphanumeric keys or the LSK, or by the FMC. Scratchpad entry cannot, normally, be made with a FMC message in the scratchpad. Scratchpad entries are independent of page selection, and remain until cleared even when page changes occur. Scratchpad data entries and erases affect only the associated CDU. Messages can appear and be erased on both CDUs simultaneously.

== Internal Representation ==
[[File:CDU HelloWorld.png|thumb|270px|The utilizes display matrix, showing the text bounding boxes for clarity.]]
As the screen has a "fixed" resolution, internally the screen is represented as a 14-by-24(-by-2) matrix. The zero-indexed matrix is held in the property tree:

/instrumentation/cdu/display/row-0/col-0/char # the character printed on the screen
/instrumentation/cdu/display/row-0/col-0/style # the style or format of the printed screen.

<tt>.../char</tt> is a Nasal string-type variable. <tt>.../style</tt> is a Nasal double-type variable (although it is only integers).

The style of the char is encoded via a binary key-map:

# styles binary # wmcgLS -> decimal
"off": 0, # 000000 0
# small and LARGE types
"white": 32, # 100000 -> 32 # the default style
"magenta": 16, # 010000 -> 16
"cyan": 8, # 001000 -> 8
"green": 4, # 000100 -> 4
"WHITE": 34, # 100010 -> 34
"MAGENTA": 18, # 010010 -> 18
"CYAN": 10, # 001010 -> 10
"GREEN": 6, # 000110 -> 6
# shaded small and shaded LARGE types
"white_": 33, # 100001 -> 33
"magenta_": 7, # 010001 -> 7
"cyan_": 9, # 001001 -> 9
"green_": 5, # 000101 -> 5
"WHITE_": 35, # 100011 -> 35
"MAGENTA_": 19, # 010011 -> 19
"CYAN_": 11, # 001011 -> 11
"GREEN_": 9, # 000111 -> 9

Each style has a name (used in the Nasal code for the CDU), which is resolved into a decimal integer. The integer is defined via a binary key:
the first group represents the colors: white (<tt>w</tt>), magenta (<tt>m</tt>), cyan (<tt>c</tt>), and green (<tt>g</tt>). The second group represents the font style: large fonts (<tt>L</tt>) and a shaded background (<tt>S</tt>).

This concept is translated into the names of the style: it is the name of the color, all lowercase for small fonts, all uppercase for large fonts, and an attached underscore (<tt>_</tt>) to indicate the selection of a shaded background.

'''NOTE:''' The styles are currently not yet implemented. [[User:Hcc23|Hcc23]] 14:01, 8 April 2011 (EDT)

== Nasal Code ==
The [[Nasal]] code for the display matrix is mainly held in <tt>display_matrix.nas</tt>.
The key element of making text appear on the 3D screen is the Nasal class <tt>ScreenText</tt>

<tt>ScreenText</tt>-elements make up the label and data lines of fields. Several elements can be concattenated in a single line by stacking them in a vector. The constructor for screen text is:
new: func(t,s=32,ptp=nil)
The two elements are text (t) and style (s). Let's look at them in detail:
* <tt>s</tt>: style is an integer according to the above binary key. In order to make life easier, one can directly use the ''static'' hash members, e.g. <tt>ScreenText["white"]</tt> for small, white text; or <tt>ScreenText["GREEN_"]</tt> for large, green text with a shaded background.
* <tt>t</tt>: is the text element. Here some limited constructor overloading can be used.

The constructor overlaoding allows for an easy creating of ''just'' plain text:
var test_text = ScreenText.new("Hello World!",ScreenText["WHITE"]);
However, it could also be used to get a property from the property tree.
var test_prop = ScreenText.new(["This is a %s aircraft","/instrumentation/cdu/ident/aircraft"],ScreenText["WHITE"]);
The last call uses the property <tt>/instrumentation/cdu/ident/aircraft<tt> in a screen text element. The result is comparable to
sprintf("This is a %s aircraft",getprop("/instrumentation/cdu/ident/aircraft"));
Furthermore, whenever a property is used in a screen text element on a subpage, the suppage, when displayed, registers listeners on all utilized properties, resulting in updated data on the screen. When the sup page is changed, the listeners are de-registered.

== XML Code ==
The [[XML]] side of the display matrix comes in multiple parts. <tt>boeing.xml</tt> contains all the [[XML]] code for the CDU.
Other than loading the 3D model and defining the button names, <tt>boeing.xml</tt> also interfaces with [[osgtext]] to actually display text in the 3D model.

In <tt>boeing.xml</tt> you will find sections like this one:

<model>
<path>Aircraft/Instruments-3d/cdu/display_matrix_text.xml</path>
<overlay>
<params>
<property type="string">/instrumentation/cdu/display/row-0/col-0/char</property>
</params>
<offsets>
<x-m>0.005</x-m>
<y-m>-0.044</y-m>
<z-m>0.103</z-m>
</offsets>
</overlay>
</model>

This section defines which node of the matrix to display, indicated by <tt><property type="string">/instrumentation/cdu/display/row-0/col-0/char</property></tt> for the (0,0) node of the matrix, i.e. to first character in the topmost line.

This [[XML]] section expands on <tt>Aircraft/Instruments-3d/cdu/display_matrix_text.xml</tt> which gives some underlying structure. For more details on this, please consult <tt>$FGDATA/Docs/README.osgtext</tt>.

'''NOTE:''' I haven't completely understood how this <tt><overlay /></tt> node actually works, but this setup does what I want it to do. Please feel free to change and explain it here. [[User:Hcc23|Hcc23]] 14:23, 8 April 2011 (EDT)

'''NOTE:''' As mentioned above, the style information is not yet implemented. I would like to put that into the [[XML]] in <tt>Aircraft/Instruments-3d/cdu/display_matrix_text.xml</tt>, but I don't know how to do conditionals in XML. [[User:Hcc23|Hcc23]] 14:23, 8 April 2011 (EDT)

=== Generating the offset code ===
As you might have figured, there is a lot of identical XML code, just differing in the offset parameters and the row and column index. To make life easier I have written this Matlab script to auto-generate these sections:

<code>
clear all, close all, clc

%% Parameters
% These are to be set by the user

FILENAME = 'autocoded.xml';

ROWS = 14;
COLS = 24;

TOP = 0.106; % z-axis
BOTTOM = 0.024; % z-axis
LEFT = -0.046; % y-axis
RIGHT = 0.046; % y-axis

ELEV = 0.005; % x-axis

TEMPLATE = 'Aircraft/Instruments-3d/cdu/display_matrix_text.xml';

%% Creating the printout

fid = fopen(FILENAME,'wb');

width_of_screen = abs(RIGHT-LEFT);
hight_of_screen = abs(TOP-BOTTOM);

delta_col = width_of_screen/COLS;
delta_row = hight_of_screen/ROWS;

x_off = ELEV;
z_off = TOP - 0.5*delta_row;
y_off_zero = LEFT + 0.5*delta_col;

for row = 0:1:ROWS-1
y_off = y_off_zero;
for col = 0:1:COLS-1

propertyPath = sprintf('/instrumentation/cdu/display/row-%d/col-%d/char',row,col);

fprintf(fid,[...
'<model>\n',...
'\t<path>%s</path>\n',...
'\t<overlay>\n',...
'\t\t<params>\n',...
'\t\t\t<property type="string">%s</property>\n',...
'\t\t</params>\n',...
'\t\t<offsets>\n',...
'\t\t\t<x-m>%.3f</x-m>\n',...
'\t\t\t<y-m>%.3f</y-m>\n',...
'\t\t\t<z-m>%.3f</z-m>\n',...
'\t\t</offsets>\n',...
'\t</overlay>\n',...
'</model>\n',...
],...
TEMPLATE,...
propertyPath,...
x_off,y_off,z_off);

y_off = y_off + delta_col;

end
z_off = z_off - delta_row;
end

fclose(fid);
</code>

= The Property Tree =

The [[CDU]] also has some properties in the general [[FlightGear]] [[Property Tree]].
In general it is located in <code>/instrumentation/cdu/</code>.

= A Brief History of the Boeing CDU in FlightGear =
Find some more information on the [[CDU]] at these pages:
* [[CDU]]
* [[Howto: Implement a Control Display Unit]]

Howto:Coding a Boeing CDU

2011-04-08T20:43:12Z

2011-04-08T18:01:31Z

Hcc23: /* The CDU Screen */