The following drawing elements are available in Flight Simulator 98:
The drawing elements used in Flight Simulator 98 have several things in common. For instance, the drawing elements are defined by C data structures.
The shared data elements aren't included in the declaration of each structure. Instead, a #define HEADER is present that, when expanded, produces the twelve data members. The following code examples show the drawing element ELEMENT_NEEDLE before and after expansion.
Before expansion:
typedef struct ELEMENT_NEEDLE
{
HEADER;
'Needle-specific data members
};
After expansion:
typedef struct ELEMENT_NEEDLE
{
ELEMENT_TYPE_ENUM element_type;
IDresource_id;
PIXPOINTposition;
PIXPOINTprevious_position;
PIXPOINTofs;
PGAUGEHDRgauge_header;
struct ELEMENT_HEADERprevious_element;
struct ELEMENT_HEADERnext_element;
PFAILURE_RECORDfailure_systems;
FLAGSimage_flags;
FLAGSaircraft_special_instrumentation;
FLAGS reserved;
'Needle-specific data members.
};
The first twelve data members are the same for all the drawing element structures. The data members are described in the following table.
Member | Description |
element_type | Specifies the element type. Set this member to be one of the following elements: ELEMENT_TYPE_STATIC_IMAGE ELEMENT_TYPE_NEEDLE ELEMENT_TYPE_STRING ELEMENT_TYPE_SLIDER ELEMENT_TYPE_ICON ELEMENT_TYPE_MOVING_IMAGE ELEMENT_TYPE_SPRITE |
resource_id | Specifies the resource ID of an 8-bit or 24-bit bitmap resource. All element types, with the exception of ELEMENT_STRING (which ignores this value), use this value. |
position | For ELEMENT_NEEDLE and ELEMENT_SPRITE, specifies the point that the drawing element pivots around. |
previous_position | Specifies the previous position of the element relative to the gauge position. Used by the Panel system. This value is ignored during initialization. |
ofs | Specifies an offset (pivot point) for an element to rotate around. This value is used by ELEMENT_NEEDLE and ELEMENT_SPRITE and ignored by the other elements. |
gauge_header | Pointer to the gauge header file. |
previous_element | Pointer to the previous element. This value is set by the Panel system. This value is ignored during initialization. |
next_element | Pointer to a list of graphical elements. The elements are drawn after the current element. This value is used to determine the drawing order of all the elements in your gauge. |
failure_systems | Pointer to a FAILURE_RECORD list. This list defines how an element will react during simulated aircraft system failure. For more information, see the topic Simulating System Failures. |
image_flags | Specifies how the element image will be rendered. This member can be a combination of the following values: IMAGE_USE_TRANSPARENCY Renders the image using transparency. If this flag is set, palette index 0 is treated as transparent in an 8-bit bitmap, and RGB color (0,0,0) is treated as transparent in a 24-bit bitmap. Because non-transparent rendering is faster than transparent rendering, you can use this flag to enhance performance. IMAGE_USE_ERASE Before the graphical element is rendered, a "snapshot" of the background is saved. As a result, the Panel system can erase the element as needed by plotting the contents of the save buffer to the screen. You can use this flag to increase performance and save memory if an element never needs to be erased. Static images use this flag extensively. IMAGE_USE_BRIGHT Maps the element’s image colors to the section of the Flight Simulator 98 palette that doesn't change during the transition from day to night. The image colors will not change. For more information, see the topic Color Mapping Table. IMAGE_NO_STATIC_BLENDING This flag is only valid on static images using IMAGE_USE_TRANSPARENCY and the first element in the list. IMAGE_HIDDEN |
You can set this flag dynamically to hide or show the element. | |
aircraft_special_ | |
instrumentation | Specifies how the element will react in a special instrument situation. Currently this is used only with autopilot. ASI_ALT_MANUALLY_TUNABLE Sets a global flag that causes Flight Simulator 98 to recognize that autopilot altitude hold is manually tunable. If this flag isn't set, turning on altitude hold holds the current altitude instead of the currently set altitude. ASI_HEADING_MANUALLY_TUNABLE Sets a global flag that causes Flight Simulator 98 to recognize that autopilot heading hold is manually tunable. If this flag isn't set, turning on heading hold would hold the current heading instead of the currently set heading. |
reserved | This value is reserved and must be set to 0. |
Drawing Element Structures
Each drawing element structure has one or more MODULE_VAR members. You can initialize these members to one of the values listed in the topic Token Variables. Call the function element_install or element_list_install to initialize the MODULE_VAR element(s).
The element_update or element_list_update function can be used to update the contents of the MODULE_VAR. The elements themselves use the MODULE_VAR information at render time to determine in what state they'll be rendered.
Graphical elements can use the MODULE_VAR structure member to determine the state that the element will be rendered in. Sometimes, however, MODULE_VAR may not be a useful value. The way around this problem is to use callbacks. For each of the MODULE_VAR structures listed in the element structure, you can set an associated PMODULE_VAR_CB pointer. The pointer points to a callback function that you can use to set the variable to a useful value. The callback function is called by the Panel system after the variable has been updated from the simulation state information. The callback function is usually used to normalize or scale the MODULE_VAR value into a range that can be used. You can also use the callback function to convert enumerated values, interpret a flag's variable, and so on.
For example, the following code uses a callback routine to clip the airspeed to a useful range that can be used by the airspeed gauge:
FLOAT64 convert_var_aspeed(PMODULE_VAR var)
{
if (var->var_value.n > GAUGE_MAX_AIRSPEED)
var->var_value.n = GAUGE_MAX_AIRSPEED;
if (var->var_value.n < 60)
var->var_value.n = 60;
return var->var_value.n;
}
You can set any callback pointer to NULL, and no call will occur.
NOTE: Any assignments to the MODULE_VAR in a callback routine are discarded. The final value set in the MODULE_VAR is the return value of the callback function.
Drawing Element Lists
In code, the drawing elements are organized in a tree structure using the previous_element and next_element variables in the element structures. This element list is used to define the drawing order of the gauge elements. The first element in the list in the gauge header is drawn first. Each subsequent element in the list is drawn in the order it appears in the list. Before drawing the next element in the list, the current element’s element list pointer is examined. If the pointer is not NULL, the element’s element list is drawn using the same logic.
You don't need to set the previous_element pointer. The previous_element pointers are initialized by the Panel system when the gauge is initialized.
The following Panel API functions also use the element list structure to perform an operation on all elements in the gauge:
void element_list_query(PELEMENT_HEADER element);
void element_list_install(PELEMENT_HEADER element, HINSTANCE resource_file_handle);
void element_list_initialize(PELEMENT_HEADER element);
void element_list_update(PELEMENT_HEADER element);
void element_list_generate(PELEMENT_HEADER element, GENERATE_PHASE phase);
void element_list_plot(PELEMENT_HEADER element);
void element_list_erase(PELEMENT_HEADER element);
void element_list_kill(PELEMENT_HEADER element);