Using Drawing Elements

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);