Class Canvas

The virtual tabletop environment is implemented using a WebGL powered HTML 5 canvas using the powerful PIXI.js library. The canvas is comprised by an ordered sequence of layers which define rendering groups and collections of objects that are drawn on the canvas itself.

Hook Events

hookEvents.canvasConfig hookEvents.canvasInit hookEvents.canvasReady hookEvents.canvasPan hookEvents.canvasTearDown

Example: Canvas State

canvas.ready; // Is the canvas ready for use?
canvas.scene; // The currently viewed Scene document.
canvas.dimensions; // The dimensions of the current Scene.

Example: Canvas Methods

canvas.draw(); // Completely re-draw the game canvas (this is usually unnecessary).
canvas.pan(x, y, zoom); // Pan the canvas to new coordinates and scale.
canvas.recenter(); // Re-center the canvas on the currently controlled Token.

Index

Accessors

initialized scene manager dimensions grid ready colors masks id layers activeLayer darknessLevel layers

Methods

initialize _configurePerformanceMode draw tearDown getGLParameter initializeCanvasPosition getLayerByEmbeddedName getCollectionLayer activateFPSMeter deactivateFPSMeter pan animatePan recenter highlightObjects ping _constrainView createBlurFilter addBlurFilter clientCoordinatesFromCanvas canvasCoordinatesFromClient isOffscreen _onDragRightStart _onDragRightMove _onDragRightDrop _onDragRightCancel _onDragCanvasPan #initializePlugins #createApplication #attachToRunners #mapBlendModes #mapPremultipliedBlendModes #createGroups _initializeBlur #draw #handleRegionBehaviorStatusEvents #drawBlank #initialize #initializeCanvasLayer #initializeTokenControl #callManagerEvent #measureFPS updateBlur #addListeners #onMouseMove #onClickLeft #onClickLeft2 #onLongPress #canDragLeftStart #onDragLeftStart #onDragLeftMove #onDragLeftDrop #onDragLeftCancel #onClickRight #onClickRight2 #onDragSelect _onResize _onMouseWheel _onDrop #activateTicker #deactivateTicker #applyRenderFlags #testSupport getSceneManager clearContainer getRenderTexture #configureWebGL #createHTMLCanvas #configureCanvasSettings

Properties

blurFilters

blurFilters: Set<filters> = ...

A set of blur filter instances which are modified by the zoom level and the "soft shadows" setting

currentMouseManager

currentMouseManager: MouseInteractionManager = null

A reference to the MouseInteractionManager that is currently controlling pointer-based interaction, or null.

loadTexturesOptions

loadTexturesOptions: {
expireCache: boolean;
additionalSources: string[];
}

Configure options passed to the texture loaded for the Scene. This object can be configured during the canvasInit hook before textures have been loaded.

Type declaration

expireCache: boolean
additionalSources: string[]

visibilityOptions

visibilityOptions: {
persistentVision: boolean;
}

Configure options used by the visibility framework for special effects This object can be configured during the canvasInit hook before visibility is initialized.

Type declaration

persistentVision: boolean

blurOptions

blurOptions: {
    enabled: boolean;
    blurClass: Class;
    strength: number;
    passes: number;
    kernels: number;
}

Configure options passed to initialize blur for the Scene and override normal behavior. This object can be configured during the canvasInit hook before blur is initialized.

Type declaration

enabled: boolean
blurClass: Class
strength: number
passes: number
kernels: number

sceneTextures

sceneTextures: {} = {}

Configure the Textures to apply to the Scene. Textures registered here will be automatically loaded as part of the TextureLoader.loadSceneTextures workflow. Textures which need to be loaded should be configured during the "canvasInit" hook.

Type declaration

fps

fps: {
    average: number;
    values: number[];
    element: HTMLElement;
    render: number;
} = ...

Record framerate performance data.

Type declaration

average: number
values: number[]
element: HTMLElement
render: number

mouseInteractionManager

mouseInteractionManager: MouseInteractionManager

The singleton interaction manager instance which handles mouse interaction on the Canvas.

performance

performance: CanvasPerformanceSettings

Configured performance settings which affect the behavior of the Canvas and its renderer.

supported

supported: CanvasSupportedComponents

A list of supported webGL capabilities and limitations.

photosensitiveMode

photosensitiveMode: boolean

Is the photosensitive mode enabled?

screenDimensions

screenDimensions: number[] = ...

The renderer screen dimensions.

loading

loading: boolean = false

A flag to indicate whether a new Scene is currently being drawn.

initializing

initializing: Promise<void> = null

A promise that resolves when the canvas is first initialized and ready.

app

app: Application

The singleton PIXI.Application instance rendered on the Canvas.

stage

stage: Container

The primary stage container of the PIXI.Application.

rendered

rendered: RenderedCanvasGroup

The rendered canvas group which render the environment canvas group and the interface canvas group.

See

environment
interface

edges

edges: CanvasEdges

A singleton CanvasEdges instance.

fog

fog: FogManager

The singleton FogManager instance.

perception

perception: PerceptionManager

A perception manager interface for batching lighting, sight, and sound updates.

environment

environment: EnvironmentCanvasGroup

The environment canvas group which render the primary canvas group and the effects canvas group.

See

primary
effects

primary

primary: PrimaryCanvasGroup

The primary Canvas group which generally contains tangible physical objects which exist within the Scene. This group is a CachedContainer which is rendered to the Scene as a SpriteMesh. This allows the rendered result of the Primary Canvas Group to be affected by a BaseSamplerShader.

effects

effects: EffectsCanvasGroup

The effects Canvas group which modifies the result of the PrimaryCanvasGroup by adding special effects. This includes lighting, vision, fog of war and related animations.

visibility

visibility: CanvasVisibility

The visibility Canvas group which handles the fog of war overlay by consolidating multiple render textures, and applying a filter with special effects and blur.

interface

interface: InterfaceCanvasGroup

The interface Canvas group which is rendered above other groups and contains all interactive elements. The various InteractionLayer instances of the interface group provide different control sets for interacting with different types of Documents which can be represented on the Canvas.

overlay

overlay: OverlayCanvasGroup

The overlay Canvas group which is rendered above other groups and contains elements not bound to stage transform.

hud

hud: HeadsUpDisplay

The singleton HeadsUpDisplay container which overlays HTML rendering on top of this Canvas.

mousePosition

mousePosition: Point = ...

Position of the mouse on stage.

forceSnapVertices

forceSnapVertices: boolean = false

Force snapping to grid vertices?

pendingRenderFlags

pendingRenderFlags: any

Track objects which have pending render flags.

`Private` #throttleOnMouseMove

#throttleOnMouseMove: (() => any) = ...

A throttled function that handles mouse moves.

Type declaration

- (): any
- Returns any

`Private` #drawing

#drawing: Promise<Canvas> = ...

An internal reference to a Promise in-progress to draw the canvas.

`Private` #dragDrop

#dragDrop: DragDrop

The DragDrop instance which handles interactivity resulting from DragTransfer events.

`Private` #reload

#reload: {
    scene: string;
    layer: string;
    controlledTokens: string[];
    targetedTokens: string[];
} = {}

An object of data which caches data which should be persisted across re-draws of the game canvas.

Type declaration

scene: string
layer: string
controlledTokens: string[]
targetedTokens: string[]

`Private` _panTime

_panTime: number = 0

Track the last automatic pan time to throttle

`Private` #tickerFunctions

#tickerFunctions: Record<string, Function> = {}

Cached references to bound ticker functions which can be removed later.

Accessors

initialized

get initialized(): boolean
A flag for whether the game Canvas is fully initialized and ready for additional content to be drawn.

Returns boolean

scene

get scene(): Scene
A reference to the currently displayed Scene document, or null if the Canvas is currently blank.

Returns Scene

manager

get manager(): any
A SceneManager instance which adds behaviors to this Scene, or null if there is no manager.

Returns any

dimensions

get dimensions(): Readonly<CanvasDimensions>
The current pixel dimensions of the displayed Scene, or null if the Canvas is blank.

Returns Readonly<CanvasDimensions>

grid

get grid(): any
A reference to the grid of the currently displayed Scene document, or null if the Canvas is currently blank.

Returns any

ready

get ready(): boolean
A flag for whether the game Canvas is ready to be used. False if the canvas is not yet drawn, true otherwise.

Returns boolean

colors

get colors(): typeof Color
The colors bound to this scene and handled by the color manager.

Returns typeof Color

masks

get masks(): Container
Shortcut to get the masks container from HiddenCanvasGroup.

Returns Container

id

get id(): string
The id of the currently displayed Scene.

Returns string

layers

get layers(): CanvasLayer[]
An Array of all CanvasLayer instances which are active on the Canvas board

Returns CanvasLayer[]

activeLayer

get activeLayer(): CanvasLayer
Return a reference to the active Canvas Layer

Returns CanvasLayer

darknessLevel

get darknessLevel(): number
The currently displayed darkness level, which may override the saved Scene value.

Returns number

`Static` layers

get layers(): Record<string, CanvasLayer>
A mapping of named CanvasLayer classes which defines the layers which comprise the Scene.

Returns Record<string, CanvasLayer>

Methods

initialize

initialize(): void
Initialize the Canvas by creating the HTML element and PIXI application. This step should only ever be performed once per client session. Subsequent requests to reset the canvas should go through Canvas#draw

Returns void

_configurePerformanceMode

_configurePerformanceMode(): CanvasPerformanceSettings
Internal
Configure performance settings for hte canvas application based on the selected performance mode.

Returns CanvasPerformanceSettings

draw

draw(scene?): Promise<Canvas>
Draw the game canvas.
Parameters
- Optional scene: Scene
  A specific Scene document to render on the Canvas
Returns Promise<Canvas>
A Promise which resolves once the Canvas is fully drawn

tearDown

tearDown(): Promise<void>
When re-drawing the canvas, first tear down or discontinue some existing processes

Returns Promise<void>

getGLParameter

getGLParameter(parameter): any
Get the value of a GL parameter
Parameters
- parameter: string
  The GL parameter to retrieve
Returns any
The GL parameter value

initializeCanvasPosition

initializeCanvasPosition(): void
Initialize the starting view of the canvas stage If we are re-drawing a scene which was previously rendered, restore the prior view position Otherwise set the view to the top-left corner of the scene at standard scale

Returns void

getLayerByEmbeddedName

getLayerByEmbeddedName(embeddedName): PlaceablesLayer
Given an embedded object name, get the canvas layer for that object
Parameters
- embeddedName: string
Returns PlaceablesLayer

getCollectionLayer

getCollectionLayer(collectionName): PlaceablesLayer
Get the InteractionLayer of the canvas which manages Documents of a certain collection within the Scene.
Parameters
- collectionName: string
  The collection name
Returns PlaceablesLayer
The canvas layer

activateFPSMeter

activateFPSMeter(): void
Activate framerate tracking by adding an HTML element to the display and refreshing it every frame.

Returns void

deactivateFPSMeter

deactivateFPSMeter(): void
Deactivate framerate tracking by canceling ticker updates and removing the HTML element.

Returns void

pan

pan(position?): void
Pan the canvas to a certain {x,y} coordinate and a certain zoom level
Parameters
- position: CanvasViewPosition = {}
  The canvas position to pan to
Returns void

animatePan

animatePan(view?): Promise<any>
Animate panning the canvas to a certain destination coordinate and zoom scale Customize the animation speed with additional options Returns a Promise which is resolved once the animation has completed
Parameters
- view: CanvasViewPosition = {}
  The desired view parameters
Returns Promise<any>
A Promise which resolves once the animation has been completed

recenter

recenter(initial): Promise<void>
Recenter the canvas with a pan animation that ends in the center of the canvas rectangle.
Parameters
- initial: CanvasViewPosition
  A desired initial position from which to begin the animation
Returns Promise<void>
A Promise which resolves once the animation has been completed

highlightObjects

highlightObjects(active): void
Highlight objects on any layers which are visible
Parameters
- active: boolean
Returns void

ping

ping(origin, options?): Promise<boolean>
Displays a Ping both locally and on other connected client, following these rules:
1. Displays on the current canvas Scene
2. If ALT is held, becomes an ALERT ping
3. Else if the user is GM and SHIFT is held, becomes a PULL ping
4. Else is a PULSE ping
Parameters
- origin: Point
  Point to display Ping at
- Optional options: PingOptions
  Additional options to configure how the ping is drawn.
Returns Promise<boolean>

_constrainView

_constrainView(position): CanvasViewPosition
Internal
Get the constrained zoom scale parameter which is allowed by the maxZoom parameter
Parameters
- position: CanvasViewPosition
  The unconstrained position
Returns CanvasViewPosition
The constrained position

createBlurFilter

createBlurFilter(blurStrength, blurQuality?): BlurFilter
Create a BlurFilter instance and register it to the array for updates when the zoom level changes.
Parameters
- blurStrength: number
  The desired blur strength to use for this filter
- blurQuality: number = CONFIG.Canvas.blurQuality
  The desired quality to use for this filter
Returns BlurFilter

addBlurFilter

addBlurFilter(filter): BlurFilter
Add a filter to the blur filter list. The filter must have the blur property
Parameters
- filter: BlurFilter
  The Filter instance to add
Returns BlurFilter
The added filter for method chaining

clientCoordinatesFromCanvas

clientCoordinatesFromCanvas(origin): Point
Convert canvas coordinates to the client's viewport.
Parameters
- origin: Point
  The canvas coordinates.
Returns Point
The corresponding coordinates relative to the client's viewport.

canvasCoordinatesFromClient

canvasCoordinatesFromClient(origin): Point
Convert client viewport coordinates to canvas coordinates.
Parameters
- origin: Point
  The client coordinates.
Returns Point
The corresponding canvas coordinates.

isOffscreen

isOffscreen(position): boolean
Determine whether given canvas coordinates are off-screen.
Parameters
- position: Point
  The canvas coordinates.
Returns boolean
Is the coordinate outside the screen bounds?

_onDragRightStart

_onDragRightStart(event): void
Internal
Handle right-mouse start drag events occurring on the Canvas.
Parameters
- event: FederatedEvent
Returns void
See

_onDragRightMove

_onDragRightMove(event): void
Internal
Handle right-mouse drag events occurring on the Canvas.
Parameters
- event: FederatedEvent
Returns void
See

_onDragRightDrop

_onDragRightDrop(event): void
Internal
Handle the conclusion of a right-mouse drag workflow the Canvas stage.
Parameters
- event: FederatedEvent
Returns void
See

_onDragRightCancel

_onDragRightCancel(event): void
Internal
Handle the cancellation of a right-mouse drag workflow the Canvas stage.
Parameters
- event: FederatedEvent
Returns void
See

_onDragCanvasPan

_onDragCanvasPan(event): Promise<any>
Pan the canvas view when the cursor position gets close to the edge of the frame
Parameters
- event: MouseEvent
  The originating mouse movement event
Returns Promise<any>

`Private` #initializePlugins

#initializePlugins(): void
Initialize custom pixi plugins.

Returns void

`Private` #createApplication

#createApplication(canvas, config): void
Create the PIXI.Application and update references to the created app and stage.
Parameters
- canvas: HTMLCanvasElement
  The target canvas view element
- config: object
  Desired PIXI.Application configuration options
Returns void

`Private` #attachToRunners

#attachToRunners(): void
Attach specific behaviors to the PIXI runners.
- contextChange => Remap all the blend modes
Returns void

`Private` #mapBlendModes

#mapBlendModes(): void
Map custom blend modes and premultiplied blend modes.

Returns void

`Private` #mapPremultipliedBlendModes

#mapPremultipliedBlendModes(): void
Remap premultiplied blend modes/non premultiplied blend modes to fix PIXI bug with custom BM.

Returns void

`Private` #createGroups

#createGroups(parentName, parent): void
Initialize the group containers of the game Canvas.
Parameters
- parentName: string
- parent: DisplayObject
Returns void

`Private` _initializeBlur

_initializeBlur(options?): void
Private
TODO: Add a quality parameter Compute the blur parameters according to grid size and performance mode.
Parameters
- options: {} = {}
  Blur options.
Returns void

`Private` #draw

#draw(scene?): Promise<void>
Draw the game canvas. This method is wrapped by a promise that enqueues multiple draw requests.
Parameters
- Optional scene: Scene
  A specific Scene document to render on the Canvas
Returns Promise<void>

`Private` #handleRegionBehaviorStatusEvents

#handleRegionBehaviorStatusEvents(viewed): Promise<void>
Handle Region BEHAVIOR_STATUS events that are triggered when the Scene is (un)viewed.
Parameters
- viewed: boolean
  Is the scene viewed or not?
Returns Promise<void>

`Private` #drawBlank

#drawBlank(): void
A special workflow to perform when rendering a blank Canvas with no active Scene.

Returns void

`Private` #initialize

#initialize(): Promise<void>
Once the canvas is drawn, initialize control, visibility, and audio states

Returns Promise<void>

`Private` #initializeCanvasLayer

#initializeCanvasLayer(): void
Initialize a CanvasLayer in the activation state

Returns void

`Private` #initializeTokenControl

#initializeTokenControl(): void
Initialize a token or set of tokens which should be controlled. Restore controlled and targeted tokens from before the re-draw.

Returns void

`Private` #callManagerEvent

#callManagerEvent(fnName): Promise<void>
Safely call a function of the SceneManager instance, catching and logging any errors.
Parameters
- fnName: string
  The name of the manager function to invoke
Returns Promise<void>

`Private` #measureFPS

#measureFPS(): void
Measure average framerate per second over the past 30 frames

Returns void

`Private` updateBlur

updateBlur(strength?): void
Private
Update the blur strength depending on the scale of the canvas stage. This number is zero if "soft shadows" are disabled
Parameters
- Optional strength: number
  Optional blur strength to apply
Returns void

`Private` #addListeners

#addListeners(): void
Attach event listeners to the game canvas to handle click and interaction events

Returns void

`Private` #onMouseMove

#onMouseMove(): void
Handle mouse movement on the game canvas.

Returns void

`Private` #onClickLeft

#onClickLeft(event): void
Handle left mouse-click events occurring on the Canvas.
Parameters
- event: FederatedEvent
Returns void
See

`Private` #onClickLeft2

#onClickLeft2(event): void
Handle double left-click events occurring on the Canvas.
Parameters
- event: FederatedEvent
Returns void
See

`Private` #onLongPress

#onLongPress(event, origin): void
Handle long press events occurring on the Canvas.
Parameters
- event: FederatedEvent
  The triggering canvas interaction event.
- origin: Point
  The local canvas coordinates of the mousepress.
Returns void
See

`Private` #canDragLeftStart

#canDragLeftStart(user, event): boolean
Does the User have permission to left-click drag on the Canvas?
Parameters
- user: User
  The User performing the action.
- event: FederatedEvent
  The event object.
Returns boolean

`Private` #onDragLeftStart

#onDragLeftStart(event): any
Handle the beginning of a left-mouse drag workflow on the Canvas stage or its active Layer.
Parameters
- event: FederatedEvent
Returns any
See

`Private` #onDragLeftMove

#onDragLeftMove(event): any
Handle mouse movement events occurring on the Canvas.
Parameters
- event: FederatedEvent
Returns any
See

`Private` #onDragLeftDrop

#onDragLeftDrop(event): any
Internal
Handle the conclusion of a left-mouse drag workflow when the mouse button is released.
Parameters
- event: FederatedEvent
Returns any
See

`Private` #onDragLeftCancel

#onDragLeftCancel(event): boolean | void
Internal
Handle the cancellation of a left-mouse drag workflow
Parameters
- event: PointerEvent
Returns boolean | void
See

`Private` #onClickRight

#onClickRight(event): any
Handle right mouse-click events occurring on the Canvas.
Parameters
- event: FederatedEvent
Returns any
See

`Private` #onClickRight2

#onClickRight2(event): any
Handle double right-click events occurring on the Canvas.
Parameters
- event: FederatedEvent
Returns any
See

`Private` #onDragSelect

#onDragSelect(event): void
Determine selection coordinate rectangle during a mouse-drag workflow
Parameters
- event: FederatedEvent
Returns void

`Private` _onResize

_onResize(event?): boolean
Private
Handle window resizing with the dimensions of the window viewport change
Parameters
- event: Event = null
  The Window resize event
Returns boolean

`Private` _onMouseWheel

_onMouseWheel(event): void
Private
Handle mousewheel events which adjust the scale of the canvas
Parameters
- event: WheelEvent
  The mousewheel event that zooms the canvas
Returns void

`Private` _onDrop

_onDrop(event): any
Private
Event handler for the drop portion of a drag-and-drop event.
Parameters
- event: DragEvent
  The drag event being dropped onto the canvas
Returns any

`Private` #activateTicker

#activateTicker(): void
Activate ticker functions which should be called as part of the render loop. This occurs as part of setup for a newly viewed Scene.

Returns void

`Private` #deactivateTicker

#deactivateTicker(): void
Deactivate ticker functions which were previously registered. This occurs during tear-down of a previously viewed Scene.

Returns void

`Private` #applyRenderFlags

#applyRenderFlags(queue): void
Apply pending render flags which should be handled at a certain ticker priority.
Parameters
- queue: Set<RenderFlagObject>
  The queue of objects to handle
Returns void

`Private` #testSupport

#testSupport(renderer): {
    webGL2: boolean;
    readPixelsRED: boolean;
    offscreenCanvas: boolean;
}
Test support for some GPU capabilities and update the supported property.
Parameters
- renderer: Renderer
Returns {
    webGL2: boolean;
    readPixelsRED: boolean;
    offscreenCanvas: boolean;
}
- webGL2: boolean
- readPixelsRED: boolean
- offscreenCanvas: boolean

`Static` getSceneManager

getSceneManager(scene): any
Internal
Create a SceneManager instance used for this Scene, if any.
Parameters
- scene: Scene
Returns any

`Static` clearContainer

clearContainer(displayObject, destroy?): void
Remove all children of the display object and call one cleaning method: clean first, then tearDown, and destroy if no cleaning method is found.
Parameters
- displayObject: DisplayObject
  The display object to clean.
- destroy: boolean = true
  If textures should be destroyed.
Returns void

`Static` getRenderTexture

getRenderTexture(options?): RenderTexture
Get a texture with the required configuration and clear color.
Parameters
- options: {
  clearColor: number[];
  textureConfiguration: object;
  } = {}
  - clearColor: number[]
    The clear color to use for this texture. Transparent by default.
  - textureConfiguration: object
    The render texture configuration.
Returns RenderTexture

`Static` `Private` #configureWebGL

#configureWebGL(): void
Configure the usage of WebGL for the PIXI.Application that will be created.

Returns void
Throws
an Error if WebGL is not supported by this browser environment.

`Static` `Private` #createHTMLCanvas

#createHTMLCanvas(): HTMLCanvasElement
Create the Canvas element which will be the render target for the PIXI.Application instance. Replace the template element which serves as a placeholder in the initially served HTML response.

Returns HTMLCanvasElement

`Static` `Private` #configureCanvasSettings

#configureCanvasSettings(): object
Configure the settings used to initialize the PIXI.Application instance.

Returns object
Options passed to the PIXI.Application constructor.

Class Canvas

Hook Events

Example: Canvas State

Example: Canvas Methods

Index

Properties

Accessors

Methods

Properties

blurFilters

currentMouseManager

loadTexturesOptions

Type declaration

expireCache: boolean

additionalSources: string[]

visibilityOptions

Type declaration

persistentVision: boolean

blurOptions

Type declaration

enabled: boolean

blurClass: Class

strength: number

passes: number

kernels: number

sceneTextures

Type declaration

fps

Type declaration

average: number

values: number[]

element: HTMLElement

render: number

mouseInteractionManager

performance

supported

photosensitiveMode

screenDimensions

loading

initializing

app

stage

rendered

See

edges

fog

perception

environment

See

primary

effects

visibility

interface

overlay

hud

mousePosition

forceSnapVertices

pendingRenderFlags

Private #throttleOnMouseMove

Type declaration

Returns any

Private #drawing

Private #dragDrop

Private #reload

Type declaration

scene: string

layer: string

controlledTokens: string[]

targetedTokens: string[]

Private _panTime

Private #tickerFunctions

Accessors

initialized

Returns boolean

scene

Returns Scene

manager

Returns any

dimensions

Returns Readonly<CanvasDimensions>

`Private` #throttleOnMouseMove

`Private` #drawing

`Private` #dragDrop

`Private` #reload

`Private` _panTime

`Private` #tickerFunctions

`Static` layers