DisplayOverlay

Displays a bitmap overlaying all screens.

Synopsis

Item DisplayOverlay (Item bitmap, int32 topedge();

Description

DisplayOverlay creates and installs an overlay onto the prevailing display. This presents critical information to the user. The underlying screen and application driving it continue to operate normally.

The specified bitmap is spliced into the prevailing display; its top edge is at the location specified by topedge. DisplayOverlay() returns an item representing the overlay or an error if unsuccessful. The specified bitmap will remain in front of all other screens until the overlay is removed using DeleteItem().

Only one overlay can be active at a time; the most recent bitmap supplied to DisplayOverlay() is displayed.

The top edge of the bitmap may be greater than or equal to 0, and the bottom edge must be no lower than the total height of the prevailing display mode (NTSC or PAL). The overlay is not be created if these bounds are violated.

Note

It is strongly recommended that this function is used only to display information of a time-critical and transient nature to the user. Using this facility for the purpose of permanently installing a static graphic (like a flight control panel) is expressly discouraged.

It is anticipated that, one day, overlays will be translucent. In anticipation of this eventuality, you are encouraged to observe the following rendering rules:

Translucent imagery should be rendered with the high bit (bit 15) set.
Opaque imagery (like text) should be rendered with the high bit clear.

Arguments

bitmapItem: Number of the bitmap to be displayed.

topedge: Y-position Where the top edge of the bitmap is to appear.

Result

Item: An item representing the overlay, or a negative error code.

Implementation

Folio call implemented in Graphics folio V22.

Associated Files

graphics.h: ANSI Prototype

graphics.lib: ARM Link Library

Caveats

Currently, if the top edge is 0, it is silently bumped to 1. This behavior will change in the future.

The internal nature of the overlay shall forever remain private, because its implementation is going to change. If you attempt to rely on any characteristics of an overlay item that aren't documented here your application will break.

The CLUT used for the overlay is the standard ascending color set; it cannot be changed.

All subpositioning and anti-aliasing features are turned off in the overlay region; they cannot be changed.

Due to a hardware, the top and bottom lines of the overlay can appear irregular if vertical averaging is enabled in the underlying screen. This is especially true of pseudo-24-bit displays.