Class: Viewport

Viewport

Main class to use when creating a Viewport

new Viewport (ViewportOptions)

Name Type Default Description
ViewportOptions IViewportOptions
options.screenWidth number window.innerWidth optional
options.screenHeight number window.innerHeight optional
options.worldWidth number this.width optional
options.worldHeight number this.height optional
options.threshold number 5 optional

number of pixels to move to trigger an input event (e.g., drag, pinch) or disable a clicked event

options.passiveWheel boolean true optional

whether the 'wheel' event is set to passive (note: if false, e.preventDefault() will be called when wheel is used over the viewport)

options.stopPropagation boolean false optional

whether to stopPropagation of events that impact the viewport (except wheel events, see options.passiveWheel)

options.forceHitArea HitArea optional

change the default hitArea from world size to a new value

options.noTicker boolean optional

set this if you want to manually call update() function on each frame

options.ticker PIXI.Ticker PIXI.Ticker.shared optional

use this PIXI.ticker for updates

options.interaction PIXI.InteractionManager null optional

InteractionManager, available from instantiated WebGLRenderer/CanvasRenderer.plugins.interaction - used to calculate pointer position relative to canvas location on screen

options.divWheel HTMLElement document.body optional

div to attach the wheel event

options.disableOnContextMenu boolean optional

remove oncontextmenu=() => {} from the divWheel element

Fires:
  • event:clicked
  • event:drag-start
  • event:drag-end
  • event:drag-remove
  • event:pinch-start
  • event:pinch-end
  • event:pinch-remove
  • event:snap-start
  • event:snap-end
  • event:snap-remove
  • event:snap-zoom-start
  • event:snap-zoom-end
  • event:snap-zoom-remove
  • event:bounce-x-start
  • event:bounce-x-end
  • event:bounce-y-start
  • event:bounce-y-end
  • event:bounce-remove
  • event:wheel
  • event:wheel-remove
  • event:wheel-scroll
  • event:wheel-scroll-remove
  • event:mouse-edge-start
  • event:mouse-edge-end
  • event:mouse-edge-remove
  • event:moved
  • event:moved-end
  • event:zoomed
  • event:zoomed-end
  • event:frame-end

Classes

Viewport

Members

bottom

World coordinates of the bottom edge of the screen

center

Center of screen in world coordinates

corner

Top-left corner of Viewport

dirty

Determines whether the viewport is dirty (i.e., needs to be rendered to the screen because of a change)

forceHitArea

Permanently changes the Viewport's hitArea

NOTE: if not set then hitArea = PIXI.Rectangle(Viewport.left, Viewport.top, Viewport.worldScreenWidth, Viewport.worldScreenHeight)

left

World coordinates of the left edge of the screen

pause

Pause viewport (including animation updates such as decelerate)

World coordinates of the right edge of the screen

scaled

Changes scale of viewport and maintains center of viewport

screenHeightInWorldPixels

Get how many world pixels fit on screen's height

screenWidthInWorldPixels

Get how many world pixels fit in screen's width

screenWorldHeight

World height in screen coordinates

screenWorldWidth

World width in screen coordinates

top

World coordinates of the top edge of the screen

worldHeight

World height, in pixels

worldScreenHeight

Screen height in world coordinates

worldScreenWidth

Screen width in world coordinates

worldWidth

World width, in pixels

Methods

animate (options)Viewport

Animate the position and/or scale of the viewport To set the zoom level, use: (1) scale, (2) scaleX and scaleY, or (3) width and/or height

Name Type Description
options object
Name Type Default Description
time number 1000 optional

time to animate

position PIXI.Point viewport.center optional

position to move viewport

width number optional

desired viewport width in world pixels (use instead of scale; aspect ratio is maintained if height is not provided)

height number optional

desired viewport height in world pixels (use instead of scale; aspect ratio is maintained if width is not provided)

scale number optional

scale to change zoom (scale.x = scale.y)

scaleX number optional

independently change zoom in x-direction

scaleY number optional

independently change zoom in y-direction

ease function | string linear optional

easing function to use

callbackOnComplete function optional
removeOnInterrupt boolean optional

removes this plugin if interrupted by any user input

Returns:
Type Description
Viewport this

bounce (options)Viewport

Bounce on borders NOTES: screenWidth, screenHeight, worldWidth, and worldHeight needs to be set for this to work properly fires 'moved', 'bounce-x-start', 'bounce-y-start', 'bounce-x-end', and 'bounce-y-end' events

Name Type Description
options object optional
Name Type Default Description
sides string all optional

all, horizontal, vertical, or combination of top, bottom, right, left (e.g., 'top-bottom-right')

friction number 0.5 optional

friction to apply to decelerate if active

time number 150 optional

time in ms to finish bounce

bounceBox object optional

use this bounceBox instead of (0, 0, viewport.worldWidth, viewport.worldHeight)

Name Type Default Description
x number 0 optional
y number 0 optional
width number viewport.worldWidth optional
height number viewport.worldHeight optional
ease string | function easeInOutSine optional

ease function or name (see http://easings.net/ for supported names)

underflow string center optional

(top/bottom/center and left/right/center, or center) where to place world if too small for screen

Returns:
Type Description
Viewport this

clamp (options, direction, underflow)

Clamp to world boundaries or other provided boundaries There are three ways to clamp:

  1. direction: 'all' = the world is clamped to its world boundaries, ie, you cannot drag any part of offscreen direction: 'x' | 'y' = only the x or y direction is clamped to its world boundary
  2. left, right, top, bottom = true | number = the world is clamped to the world's pixel location for each side; if any of these are set to true, then the location is set to the boundary [0, viewport.worldWidth/viewport.worldHeight], eg: to allow the world to be completely dragged offscreen, set [-viewport.worldWidth, -viewport.worldHeight, viewport.worldWidth * 2, viewport.worldHeight * 2]

Underflow determines what happens when the world is smaller than the viewport

  1. none = the world is clamped but there is no special behavior
  2. center = the world is centered on the viewport
  3. combination of top/bottom/center and left/right/center (case insensitive) = the world is stuck to the appropriate boundaries

NOTES: clamp is disabled if called with no options; use { direction: 'all' } for all edge clamping screenWidth, screenHeight, worldWidth, and worldHeight needs to be set for this to work properly

Name Type Default Description
options object optional
Name Type Default Description
left number | boolean false optional

clamp left; true = 0

right number | boolean false optional

clamp right; true = viewport.worldWidth

top number | boolean false optional

clamp top; true = 0

bottom number | boolean false optional

clamp bottom; true = viewport.worldHeight

direction string optional

(all, x, or y) using clamps of [0, viewport.worldWidth/viewport.worldHeight]; replaces left/right/top/bottom if set

underflow string center optional

where to place world if too small for screen (e.g., top-right, center, none, bottomLeft) * @returns {Viewport} this

clampZoom (options)Viewport

Enable clamping of zoom to constraints

The minWidth/Height settings are how small the world can get (as it would appear on the screen) before clamping. The maxWidth/maxHeight is how larger the world can scale (as it would appear on the screen) before clamping.

For example, if you have a world size of 1000 x 1000 and a screen size of 100 x 100, if you set minWidth/Height = 100 then the world will not be able to zoom smaller than the screen size (ie, zooming out so it appears smaller than the screen). Similarly, if you set maxWidth/Height = 100 the world will not be able to zoom larger than the screen size (ie, zooming in so it appears larger than the screen).

Name Type Description
options object optional
Name Type Description
minWidth number optional

minimum width

minHeight number optional

minimum height

maxWidth number optional

maximum width

maxHeight number optional

maximum height

minScale number optional

minimum scale

maxScale number optional

minimum scale

Returns:
Type Description
Viewport this

decelerate (options)Viewport

Decelerate after a move

NOTE: this fires 'moved' event during deceleration

Name Type Description
options IDecelerateOptions optional
Name Type Default Description
friction number 0.95 optional

percent to decelerate after movement

bounce number 0.8 optional

percent to decelerate when past boundaries (only applicable when viewport.bounce() is active)

minSpeed number 0.01 optional

minimum velocity before stopping/reversing acceleration

Returns:
Type Description
Viewport this

destroy ()

Overrides PIXI.Container's destroy to also remove the 'wheel' and PIXI.Ticker listeners

drag (options)Viewport

Enable one-finger touch to drag

NOTE: if you expect users to use right-click dragging, you should enable viewport.options.disableOnContextMenu to avoid the context menu popping up on each right-click drag.

Name Type Description
options IDragOptions optional
Name Type Default Description
direction string all optional

direction to drag

pressDrag boolean true optional

whether click to drag is active

wheel boolean true optional

use wheel to scroll in direction (unless wheel plugin is active)

wheelScroll number 1 optional

number of pixels to scroll with each wheel spin

reverse boolean optional

reverse the direction of the wheel scroll

clampWheel boolean | string false optional

clamp wheel(to avoid weird bounce with mouse wheel)

underflow string center optional

where to place world if too small for screen

factor number 1 optional

factor to multiply drag to increase the speed of movement

mouseButtons string all optional

changes which mouse buttons trigger drag, use: 'all', 'left', 'right' 'middle', or some combination, like, 'middle-right'; you may want to set viewport.options.disableOnContextMenu if you want to use right-click dragging

keyToPress Array.<string> null optional

array containing https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code codes of keys that can be pressed for the drag to be triggered, e.g.: ['ShiftLeft', 'ShiftRight'}.

ignoreKeyToPressOnTouch boolean false optional

ignore keyToPress for touch events

lineHeight number 20 optional

scaling factor for non-DOM_DELTA_PIXEL scrolling events

Returns:
Type Description
Viewport this

ensureVisible (x, y, width, height, resizeToFit)

Move the viewport so the bounding box is visible

Name Type Description
x

left

y

top

width
height
resizeToFit

Resize the viewport so the box fits within the viewport

findCover (width, height)number

Finds the scale value that fits the larger of a world width and world height on the screen does not change the viewport (use fit... to change)

Name Type Description
width number

in world pixels

height number

in world pixels

Returns:
Type Description
number scale

findFit (width, height)number

Finds the scale value that fits the smaller of a world width and world height on the screen does not change the viewport (use fit... to change)

Name Type Description
width number

in world pixels

height number

in world pixels

Returns:
Type Description
number scale

findFitHeight (height)

Finds the scale value that fits a world height on the screens does not change the viewport (use fit... to change)

Name Type Description
height

Height in world pixels

Returns:
  • scale

findFitWidth (width)

Find the scale value that fits a world width on the screen does not change the viewport (use fit... to change)

Name Type Description
width

Width in world pixels

Returns:
  • scale

fit (center, width, height)Viewport

Change zoom so it fits the size or the entire world in the viewport

Name Type Default Description
center boolean optional

maintain the same center of the screen after zoom

width number this.worldWidth optional

desired width

height number this.worldHeight optional

desired height

Returns:
Type Description
Viewport this

fitHeight (height, center, scaleX, noClamp)Viewport

Change zoom so the height fits in the viewport

Name Type Default Description
height number this.worldHeight optional

in world coordinates

center boolean optional

maintain the same center of the screen after zoom

scaleX boolean true optional

whether to set scaleX = scaleY

noClamp boolean optional

whether to disable clamp-zoom

Returns:
Type Description
Viewport this

fitWidth (width, center, scaleY, noClamp)Viewport

Change zoom so the width fits in the viewport

Name Type Default Description
width

width in world coordinates

center

maintain the same center

scaleY true

whether to set scaleY=scaleX

noClamp

whether to disable clamp-zoom

Returns:
Type Description
Viewport this

fitWorld (center)Viewport

Change zoom so it fits the entire world in the viewport

Name Type Description
center boolean

maintain the same center of the screen after zoom

Returns:
Type Description
Viewport this

follow (target, options)Viewport

Follow a target

NOTES: uses the (x, y) as the center to follow; for PIXI.Sprite to work properly, use sprite.anchor.set(0.5) options.acceleration is not perfect as it doesn't know the velocity of the target. It adds acceleration to the start of movement and deceleration to the end of movement when the target is stopped. To cancel the follow, use: viewport.plugins.remove('follow')

Name Type Description
target PIXI.DisplayObject

to follow

options IFollowOptions optional
Name Type Default Description
speed number 0 optional

to follow in pixels/frame (0=teleport to location)

acceleration number optional

set acceleration to accelerate and decelerate at this rate; speed cannot be 0 to use acceleration

radius number optional

radius (in world coordinates) of center circle where movement is allowed without moving the viewport * @returns {Viewport} this

Fires:
  • event:'moved' event
Returns:
Type Description
Viewport this

getVisibleBounds ()

Get visible world bounds of viewport

mouseEdges (options)

Scroll viewport when mouse hovers near one of the edges or radius-distance from center of screen.

NOTES: fires 'moved' event; there's a known bug where the mouseEdges does not work properly with "windowed" viewports

Name Type Description
options IMouseEdgesOptions optional
Name Type Default Description
radius number optional

distance from center of screen in screen pixels

distance number optional

distance from all sides in screen pixels

top number optional

alternatively, set top distance (leave unset for no top scroll)

bottom number optional

alternatively, set bottom distance (leave unset for no top scroll)

left number optional

alternatively, set left distance (leave unset for no top scroll)

right number optional

alternatively, set right distance (leave unset for no top scroll)

speed number 8 optional

speed in pixels/frame to scroll viewport

reverse boolean optional

reverse direction of scroll

noDecelerate boolean optional

don't use decelerate plugin even if it's installed

linear boolean optional

if using radius, use linear movement (+/- 1, +/- 1) instead of angled movement (Math.cos(angle from center), Math.sin(angle from center))

allowButtons boolean optional

allows plugin to continue working even when there's a mousedown event

moveCenter (x, y)Viewport

Move center of viewport to (x, y)

Name Type Description
x number | PIXI.Point
y number optional
Returns:
Type Description
Viewport

moveCorner (x, y)Viewport

MoveCorner

Name Type Description
x number | PIXI.Point
y number optional
Returns:
Type Description
Viewport

Is container out of world bounds

pinch (options)Viewport

Enable pinch to zoom and two-finger touch to drag

Name Type Description
options PinchOptions optional
Name Type Default Description
noDrag boolean optional

disable two-finger dragging

percent number 1 optional

percent to modify pinch speed

factor number 1 optional

factor to multiply two-finger drag to increase the speed of movement

center PIXI.Point optional

place this point at center during zoom instead of center of two fingers

axis 'all' | 'x' | 'y' all optional

axis to zoom

Returns:
Type Description
Viewport this

resize (screenWidth, screenHeight, worldWidth, worldHeight)

Use this to set screen and world sizes, needed for pinch/wheel/clamp/bounce.

Name Type Default Description
screenWidth number window.innerWidth
screenHeight number window.innerHeight
worldWidth number optional
worldHeight number optional

setZoom (scale, center)Viewport

Zoom viewport to specific value.

Name Type Description
scale number

value (e.g., 1 would be 100%, 0.25 would be 25%)

center boolean optional

maintain the same center of the screen after zoom

Returns:
Type Description
Viewport this

snap (x, y, options)Viewport

Snap to a point

Name Type Description
x number
y number
options ISnapOptions optional
Name Type Default Description
topLeft boolean optional

snap to the top-left of viewport instead of center

friction number 0.8 optional

friction/frame to apply if decelerate is active

time number 1000 optional

time in ms to snap

ease string | function easeInOutSine optional

ease function or name (see http://easings.net/ for supported names)

interrupt boolean true optional

pause snapping with any user input on the viewport

removeOnComplete boolean optional

removes this plugin after snapping is complete

removeOnInterrupt boolean optional

removes this plugin if interrupted by any user input

forceStart boolean optional

starts the snap immediately regardless of whether the viewport is at the desired location

Returns:
Type Description
Viewport this

snapZoom (options)

Returns zoom to the desired scale

Name Type Description
options ISnapZoomOptions
Name Type Default Description
width number 0 optional

the desired width to snap (to maintain aspect ratio, choose width or height)

height number 0 optional

the desired height to snap (to maintain aspect ratio, choose width or height)

time number 1000 optional

time for snapping in ms

ease string | function easeInOutSine optional

ease function or name (see http://easings.net/ for supported names)

center PIXI.Point optional

place this point at center during zoom instead of center of the viewport

interrupt boolean true optional

pause snapping with any user input on the viewport

removeOnComplete boolean optional

removes this plugin after snapping is complete

removeOnInterrupt boolean optional

removes this plugin if interrupted by any user input

forceStart boolean optional

starts the snap immediately regardless of whether the viewport is at the desired zoom

noMove boolean optional

zoom but do not move

toScreen (x, y)PIXI.Point

Changes coordinate from world to screen

Name Type Description
x number | PIXI.Point
y number
Returns:
Type Description
PIXI.Point

toWorld (x, y)PIXI.Point

Changes coordinate from screen to world

Name Type Description
x number | PIXI.Point
y number
Returns:
Type Description
PIXI.Point

update (elapsed)

Update viewport on each frame.

By default, you do not need to call this unless you set options.noTicker=true.

Name Type Description
elapsed number

time in milliseconds since last update

wheel (options)Viewport

Zoom using mouse wheel

NOTE: the default event listener for 'wheel' event is document.body. Use Viewport.options.divWheel to change this default

Name Type Description
options IWheelOptions optional
Name Type Default Description
percent number 0.1 optional

percent to scroll with each spin

smooth number optional

smooth the zooming by providing the number of frames to zoom between wheel spins

interrupt boolean true optional

stop smoothing with any user input on the viewport

reverse boolean optional

reverse the direction of the scroll

center PIXI.Point optional

place this point at center during zoom instead of current mouse position

lineHeight number 20 optional

scaling factor for non-DOM_DELTA_PIXEL scrolling events

axis 'all' | 'x' | 'y' all optional

axis to zoom

Returns:
Type Description
Viewport this

zoom (change, center)Viewport

Zoom viewport by increasing/decreasing width by a certain number of pixels.

Name Type Description
change number

in pixels

center boolean optional

maintain the same center of the screen after zoom

Returns:
Type Description
Viewport this

zoomPercent (percent, center)Viewport

Zoom viewport by a certain percent (in both x and y direction).

Name Type Description
percent number

change (e.g., 0.25 would increase a starting scale of 1.0 to 1.25)

center boolean optional

maintain the same center of the screen after zoom

Returns:
Type Description
Viewport this

Events

bounce-x-end

Fires when a bounce ends in the x direction

Type:

bounce-x-start

Fires when a bounce starts in the x direction

Type:

bounce-y-end

Fires when a bounce ends in the y direction

Type:

bounce-y-start

Fires when a bounce starts in the y direction

Type:

clicked

Fires after a mouse or touch click

Type:
  • object
Properties:
Name Type Description
screen PIXI.Point
world PIXI.Point
viewport Viewport

drag-end

Fires when a drag ends

Type:
  • object
Properties:
Name Type Description
screen PIXI.Point
world PIXI.Point
viewport Viewport

drag-start

Fires when a drag starts

Type:
  • object
Properties:
Name Type Description
screen PIXI.Point
world PIXI.Point
viewport Viewport

frame-end

Fires at the end of an update frame

Type:

mouse-edge-end

Fires when the mouse-edge scrolling ends

Type:

mouse-edge-start

Fires when a mouse-edge starts to scroll

Type:

Fires when viewport moves through UI interaction, deceleration, ensureVisible, or follow

Type:
  • object
Properties:
Name Type Description
viewport Viewport
type string

(drag, snap, pinch, follow, bounce-x, bounce-y, clamp-x, clamp-y, decelerate, mouse-edges, wheel, ensureVisible)

moved-end

Fires when viewport stops moving

Type:

pinch-end

Fires when a pinch end

Type:

pinch-start

Fires when a pinch starts

Type:

snap-end

Fires when a snap ends

Type:

snap-start

Fires when a snap starts

Type:

snap-zoom-end

Fires when a snap-zoom ends

Type:

snap-zoom-start

Fires when a snap-zoom starts

Type:

Fires when for a mouse wheel event

Type:
  • object
Properties:
Name Type Description
wheel object
Properties
Name Type Description
dx number
dy number
dz number
viewport Viewport

wheel-scroll

Fires when a wheel-scroll occurs

Type:

Fires when viewport moves through UI interaction, deceleration, ensureVisible, or follow

Type:
  • object
Properties:
Name Type Description
viewport Viewport
type string

(drag-zoom, pinch, wheel, clamp-zoom, ensureVisible)

zoomed-end

Fires when viewport stops zooming

Type: