G3000 Display Overlay

Introduction

Each G3000 instrument (PFD, MFD, GTC) supports a display overlay. The display overlay is a layer that sits above the main G3000 screen content to which plugins can render arbitrary content.

The display overlay should only be used in special cases when a plugin needs to render something that lives outside of the normal G3000 UI structure. Otherwise, custom content should be preferentially rendered to a display pane (for GDUs) or to a GTC view.

Controlling the Display Overlay

By default, the display overlay is hidden, so anything rendered to it will not be visible. To control the visibility of the display overlay, use the DisplayOverlayController provided by the plugin binder:

import { registerPlugin } from '@microsoft/msfs-sdk';
import { AbstractG3000PfdPlugin } from '@microsoft/msfs-wtg3000-pfd';

class DisplayOverlayPlugin extends AbstractG3000PfdPlugin {

  public init(): void {
    // Make the display overlay visible.
    this.binder.displayOverlayController.showOverlay.set(true);
  }

}

registerPlugin(DisplayOverlayPlugin);

If you wish to show only the content of the display overlay, then you may also use DisplayOverlayController to hide the main G3000 screen content:

import { registerPlugin } from '@microsoft/msfs-sdk';
import { AbstractG3000PfdPlugin } from '@microsoft/msfs-wtg3000-pfd';

class DisplayOverlayPlugin extends AbstractG3000PfdPlugin {

  public init(): void {
    // Hide the main content.
    this.binder.displayOverlayController.hideMainContent.set(true);

    // Make the display overlay visible.
    this.binder.displayOverlayController.showOverlay.set(true);
  }

}

registerPlugin(DisplayOverlayPlugin);

Rendering Content to the Display Overlay

To render content to the display overlay, use the renderToDisplayOverlay() method available on any plugin:

import { registerPlugin } from '@microsoft/msfs-sdk';
import { AbstractG3000PfdPlugin } from '@microsoft/msfs-wtg3000-pfd';

class DisplayOverlayPlugin extends AbstractG3000PfdPlugin {

  public renderToDisplayOverlay(): VNode {
    return (
      <div>Hello, world!</div>
    );
  }

}

registerPlugin(DisplayOverlayPlugin);

If multiple plugins on the same instrument render content to the display overlay, then all content will be rendered. The order of rendering is the same as the order in which the plugins were loaded.

When rendering non-trivial content to the display overlay, it is recommended to render the content as DisplayComponents that implement the DisplayOverlayComponent interface. Any top-level DisplayOverlayComponent (i.e. one that is not a descendant of another DisplayComponent) rendered to the display overlay will automatically receive callbacks for when the display overlay is made visible or hidden and will have interaction events routed to them.

Event Routing and Handling

When the display overlay is visible, interaction events received by the parent instrument will first be routed to the display overlay before being routed to the main screen content. Interaction events include GDU bezel softkey interactions, GTC bezel softkey and knob/joystick interactions, and PFD controller interactions.

To handle events that are routed to the display overlay, you must render a DisplayOverlayComponent to the display overlay. The event can then be handled in the onInteractionEvent() method:

import { registerPlugin } from '@microsoft/msfs-sdk';
import { DisplayOverlayComponent, GduSoftkeyInteractionEvent } from '@microsoft/msfs-wtg3000-common';
import { AbstractG3000PfdPlugin } from '@microsoft/msfs-wtg3000-pfd';

class DisplayOverlayPlugin extends AbstractG3000PfdPlugin {

  public renderToDisplayOverlay(): VNode {
    return (
      <MyComponent />
    );
  }

}

class MyComponent extends DisplayComponent implements DisplayOverlayComponent {
  // ...

  public onInteractionEvent(event: string): boolean {
    if (event === GduSoftkeyInteractionEvent.SoftKey01) {
      console.log('Softkey 01 pressed!');
      return true;
    } else {
      return false;
    }
  }
}

registerPlugin(DisplayOverlayPlugin);

Events are routed to each DisplayOverlayComponent in the display overlay in the order in which the components were rendered. If an event is handled by a component, routing is halted. Otherwise, the event is routed to the next component. If nothing in the display overlay handles the event, it is routed to the main G3000 screen content unless the main content is hidden.