Module gamejs/display

Methods to create, access and manipulate the display Surface.

You can just grab the canvas element whether it exists in the DOM or not (GameJs will create it if necessary):

var display = gamejs.display.getSurface();

If you need to resize the canvas - although it is recommended to style it with CSS - you can call the setMode() function, which conviniently returns the new display surface:

newDisplay = gamejs.display.setMode([800, 600]);

Browser window gets resized

When the canvas size is configured with CSS, the display surface might change when the browser window is resized. GameJs will internally deal with this and recreate the the display surface with the new size.

You will typically not have to worry about this but if you want to get informed about a display resize, you can register a callback with gamejs.event.onDisplayResize.

Flags

For advanced uses you can set a few modes which additionally change how the display behaves with regards to pixel smoothing and whether you want a fullscreen canvas with or withouth the mouse pointer locked inside the window (for endless mouse movement in all directions).

gamejs.display.setMode() understands three flags:

  • gamejs.display.FULLSCREEN
  • gamejs.display.DISABLE_SMOOTHING
  • gamejs.display.POINTERLOCK (implies FULLSCREEN)
For example:
 // disable smoothing
 gamejs.display.setMode([800, 600], gamejs.display.DISABLE_SMOOTHING);
 // disable smoothing and fullscreen
 gamejs.display.setMode(
           [800, 600],
           gamejs.display.DISABLE_SMOOTHING | gamejs.display.FULLSCREEN
     );

Fullscreen mode

When setMode() is called with the fullscreen flag then the fullscreen mode can be enabled by the player by clicking on the DOM element with id "gjs-fullscreen-toggle". Browser security requires that a user enables fullscreen with a "gesture" (e.g., clicking a button) and we can not enable fullscreen in code.

Fullscreen mode can be exited by many keys, e.g., anything window manager related (ALT-TAB) or ESC. A lot of keys will trigger a browser information popup explaining how fullscreen mode can be exited.

The following keys are "whitelisted" in fullscreen mode and will not trigger such a browser popup:

  • left arrow, right arrow, up arrow, down arrow
  • space
  • shift, control, alt
  • page up, page down
  • home, end, tab, meta

Relevant DOM node ids accessed by this module

You can provide your own tags with those ids

  • gjs-canvas - the display surface
  • gjs-loader - loading bar
  • gjs-fullscreen-toggle a clickable element to enable fullscreen
  • gjs-canvas-wrapper this wrapper is added when in fullscreen mode

Functions

Properties


DISABLE_SMOOTHING

Pass this flag to gamejs.display.setMode(resolution, flags) to disable pixel smoothing; this is, for example, useful for retro-style, low resolution graphics where you don't want the browser to smooth them when scaling & drawing.




getSurface (dimensions)

Drawing on the Surface returned by getSurface() will draw on the screen.

Parameters

dimensions

Returns

gamejs.Surface the display Surface



setCaption (title, icon)

Set the Caption of the Display (document.title)

Parameters

String title the title of the app
gamejs.Image icon FIXME implement favicon support

setMode (dimensions, flags)

Set the width and height of the Display. Conviniently this will return the actual display Surface - the same as calling gamejs.display.getSurface() later on.

Parameters

Array dimensions [width, height] of the display surface
Number flags gamejs.display.DISABLE_SMOOTHING | gamejs.display.FULLSCREEN | gamejs.display.POINTERLOCK