Skip to main content

DisplayMode

Enum representing the different display modes available to Excalibur.

Index

Enumeration Members

Enumeration Members

FillContainer

FillContainer: FillContainer

Use the parent DOM container's css width/height for the game resolution dynamically

FillScreen

FillScreen: FillScreen

Fill the entire screen's css width/height for the game resolution dynamically. This means the resolution of the game will change dynamically as the window is resized. This is not the same as Screen.enterFullscreen

FitContainer

FitContainer: FitContainer

Fit to parent element width/height using as much space as possible while maintaining aspect ratio and resolution.

FitContainerAndFill

FitContainerAndFill: FitContainerAndFill

Fit the aspect ratio given by the game resolution within the container at all times will fill any gaps with canvas. The displayed area outside the aspect ratio is not guaranteed to be on the screen, only the Screen.contentArea is guaranteed to be on screen.

Behaves like DisplayMode.FitScreenAndFill but driven by the parent element size instead of the window. Same C-frame rooting rules apply: contentArea.topLeft === (0, 0) and unsafeArea spans the full resolution in the C-frame.

FitContainerAndZoom

FitContainerAndZoom: FitContainerAndZoom

Fit the viewport to the parent element maintaining aspect ratio given by the game resolution, but zooms in to avoid the black bars (letterbox) that would otherwise be present in FitContainer.

warning This will clip some drawable area from the user because of the zoom, use Screen.contentArea to know the safe to draw area.

The safe content area is centered on the (zoomed) unsafe area; the C-frame origin (CoordPlane.Screen) is at contentArea.topLeft. Screen.contentAreaOffset holds the per-axis half-clip in resolution space, and Screen.unsafeArea spans the full resolution in the same C-frame (was uninitialized before the fix).

FitScreen

FitScreen: FitScreen

Fit to screen using as much space as possible while maintaining aspect ratio and resolution. This is not the same as Screen.enterFullscreen but behaves in a similar way maintaining aspect ratio.

You may want to center your game here is an example

<!-- html -->
<body>
<main>
  <canvas id="game"></canvas>
</main>
</body>
// css
main {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
  width: 100%;
}

FitScreenAndFill

FitScreenAndFill: FitScreenAndFill

Fit the aspect ratio given by the game resolution the screen at all times will fill the screen. This displayed area outside the aspect ratio is not guaranteed to be on the screen, only the Screen.contentArea is guaranteed to be on screen.

Screen space (the CoordPlane.Screen frame, "C") is rooted at the top-left of the safe Screen.contentArea: contentArea.topLeft === (0, 0) and contentArea.bottomRight === (contentAreaWidth, contentAreaHeight). The unsafe area spans the full resolution but is expressed in the same C-frame, so it extends symmetrically past the content area by half the clip on each clipped axis. Screen.contentAreaOffset is the resolution-space ("R") location of the content area top-left, used to convert C<->R.

Horizontal-clip example (window wider than the content aspect ratio):

    Canvas / resolution frame (R)            Screen / CoordPlane.Screen (C)

      (0,0)                                          (0,0)
      +-------+------------------+-------+           +--------------------------+
      |unsafe |    contentArea   |unsafe |           |                          |
      |(clip, |   (safe area)    |(clip, |           |       contentArea       |
      | off-  |                  | off-  |   ====>   |   (0,0)..(contentW,H)    |
      |screen)| R-frame (0,0) is |screen)|           |                          |
      |       | here ----------> |       |           |                          |
      +-------+------------------+-------+           +--------------------------+
      ^-clip -^                  ^-clip -^

      contentAreaOffset.x = clip

       unsafeArea (C-frame): left = -clip,
                          right = contentRes.width + clip,
                          width = resolution.width
      contentArea.width   = contentRes.width
      resolution.width    = contentRes.width + 2*clip

Vertical-clip behaves analogously on the Y axis. DisplayMode.FitContainerAndFill follows the same rules but driven by the parent element size instead of the window.

FitScreenAndZoom

FitScreenAndZoom: FitScreenAndZoom

Fit the viewport to the device screen maintaining aspect ratio given by the game resolution, but zooms in to avoid the black bars (letterbox) that would otherwise be present in FitScreen.

warning This will clip some drawable area from the user because of the zoom, use Screen.contentArea to know the safe to draw area.

The safe content area is centered on the (zoomed) unsafe area; the C-frame origin (CoordPlane.Screen) is at contentArea.topLeft. Screen.contentAreaOffset holds the per-axis half-clip in resolution space, and Screen.unsafeArea spans the full resolution in the same C-frame (was uninitialized before the fix).

Fixed

Fixed: Fixed

Default, use a specified resolution for the game. Like 800x600 pixels for example.

Page Options