Graphics.DougGuiOverlays - lordmundi/wikidoctest GitHub Wiki

Create EDGE overlays (advanced)

« Using Trails | EDGE User’s Guide | Orbital sim integration »

On this page… (hide)

1. Description
2. Creating An Overlay Canvas
3. Associating An Overlay Canvas With An EDGE Display
4. Adding An Overlay To A Canvas
5. Turning An Overlay On And Off
6. Working In Multi-EDGE Environments
7. Dependencies
8. Putting It All Together

1. Description

This HOWTO describes the steps involved in placing TCL overlays on top of a EDGE display. Our example code will place a colorbars display on top of an EDGE display and discuss how to turn it on and off.

2. Creating An Overlay Canvas

Overlays are placed over EDGE displays using a transparent TCL canvas. Before overlays can be rendered this canvas needs to be created and associated with the display (or view) that it is to overlay. The size of an overlay canvas is defined in rows and columns.

First we need to define a canvas name:

set canvas_id overlays.${monitor_id}

Next we must create the canvas using the create_overlay_canvas routine. This routine will create a 20 row by 40 column canvas:

create_overlay_canvas ${canvas_id}

To create a custom size overlay canvas use the create_custom_overlay_canvas routine. This is useful when creating an odd size canvas for use as a mux side overlay.

create_custom_overlay_canvas ${canvas_id} ${cols} ${rows}

3. Associating An Overlay Canvas With An EDGE Display

Now that an overlay canvas has been created we need to associate it with our display:

associate_overlay_with_view ${canvas_id} ${monitor_id}

4. Adding An Overlay To A Canvas

Now that we have a valid canvas we can start building our overlay framework on top of it. When adding overlays be aware that they stack bottom to top. This means that if I have another data overlay, which was added to the canvas after the colorbars overlay, there may be data displayed on top of the colorbars overlay. If you define the colorbars overlay last, it will cover all other overlays in it's canvas when turned on.

build_colorbars ${canvas_id} COLORBARS_${monitor_id}

5. Turning An Overlay On And Off

Turning an overlay on and off is accomplished by hiding or unhiding the overlay on the canvas. This is done using the itemconfigure command on tags associated with your overlay. The itemconfigure command can also be used to turn elements of an overlay on and off, as well as updating text values.

The following line will hide the colorbars overlay:

${canvas_id} itemconfigure COLORBARS_${monitor_id} -flags HIDE

The following line will unhide the colorbars overlay:

${canvas_id} itemconfigure COLORBARS_${monitor_id} -flags !HIDE

6. Working In Multi-EDGE Environments

When running in an environment where multiple EDGE executables are being utilized it is necessary to determine which displays are in a particular EDGE's display context. To do this we can use a simple routine to determine if the display in question exists in an EDGE instance. The following routine will test a list of display names (MAIN, 1, 2 and 3) and return an array containing thoses in it's display context:

# CRITICAL: Determine which monitors (displays/views) can  be updated
 proc determine_monitor_list {} {
    set monitor_list {}

    # This foreach should contain a list of all views/display
    # that will utilize overlays.
    foreach monitor_id { MAIN 1 2 3 } {
        # If this is an invalid display then abort
        if { [dsp.view ${monitor_id} get -mapping] != "" } {
           lappend monitor_list ${monitor_id}
        }
    }

    return ${monitor_list}
 }

Overlays can now be applied to each display contained in the monitor_list array. Referencing displays not in the monitor_list array will cause EDGE to die unless the exception is properly caught in the TCL code.

7. Dependencies

The following libraries must be included at the top of your code body.

Overlay Management Library: Contains routines used to construct an overlay canvas and associate it with a display.

# Overlay management routines&hellip;
 if { [catch { source "$env(DOUG_HOME)/gui/interface_libraries/overlay_management_library.tcl" } results] != 0 } {
     puts "ERROR sourcing $env(DOUG_HOME)/gui/interface_libraries/overlay_management_library.tcl: ${results}"
     exit &minus;1
 }

Generic Interface Library: Contains generic overlays including colorbars, bargraphs, arrows, etc.

# Generic interface routines&hellip;
 if { [catch { source "$env(DOUG_HOME)/gui/interface_libraries/generic_overlay_library.tcl" } results] != 0 } {
     puts "ERROR sourcing $env(DOUG_HOME)/gui/interface_libraries/generic_overlay_library.tcl: ${results}"
     exit &minus;1
 }

8. Putting It All Together

The following code will create a bargraph overlay on each of the displays that exist within EDGE's display context. The bargraph overlay will be hidden at startup. If none of the defined displays exist in EDGE's display context no overlays will be applied.

# Overlay management routines&hellip;
 if { [catch { source "$env(DOUG_HOME)/gui/interface_libraries/overlay_management_library.tcl" } results] != 0 } {
     puts "ERROR sourcing $env(DOUG_HOME)/gui/interface_libraries/overlay_management_library.tcl: ${results}"
     exit &minus;1
 }

 # Generic interface routines&hellip;
 if { [catch { source "$env(DOUG_HOME)/gui/interface_libraries/generic_overlay_library.tcl" } results] != 0 } {
     puts "ERROR sourcing $env(DOUG_HOME)/gui/interface_libraries/generic_overlay_library.tcl: ${results}"
     exit &minus;1
 }

 # CRITICAL: Determine which monitors (displays/views) can  be updated
 proc determine_monitor_list {} {
    set monitor_list {}

    # This foreach should contain a list of all views/display
    # that will utilize overlays.
    foreach monitor_id { MAIN 1 2 3 } {
        # If this is an invalid display then abort
        if { [dsp.view ${monitor_id} get -mapping] != "" } {
           lappend monitor_list ${monitor_id}
        }
    }

    return ${monitor_list}
 }

 proc initialize_overlays { } {
    global env monitor_list text_element 

    set monitor_list [determine_monitor_list]

    foreach monitor_id ${monitor_list} {
        set canvas_id overlays.${monitor_id}
        set window_id ${monitor_id}

        # Create the canvas (primary and left/right muxed)
        puts "initialize_overlays(): Creating overlays ${canvas_id}"
        create_overlay_canvas ${canvas_id}

        puts "initialize_cev_overlays(): Associating monitor ${canvas_id} overlays with ${window_id} displays"
        associate_overlay_with_view ${canvas_id} ${window_id}

        # Place colorbar overlay in all views
        build_colorbars ${canvas_id} COLORBARS_${monitor_id}

        # Default colorbar overlay to hidden
        ${canvas_id} itemconfigure COLORBARS_${monitor_id} -flags HIDE
     }

     puts "initialize_overlays(): Done."
 }

 # Initialize Overlays
 if { [catch { initialize_overlays } results] != 0 } {
     puts "ERROR running initialize_overlays() : ${results}" 
 }

« Using Trails | EDGE User’s Guide | Orbital sim integration »