pixi-viewport

Class: Viewport

Viewport

Main class to use when creating a Viewport

new Viewport (ViewportOptions)

Viewport.js:56
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

Viewport.js:813

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

Viewport.js:710

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)

Viewport.js:669

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

Viewport.js:839

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

Viewport.js:685

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 ()

Viewport.js:100

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

drag (options)Viewport

Viewport.js:635

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)

Viewport.js:888

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

Viewport.js:352

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

Viewport.js:339

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)

Viewport.js:328

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)

Viewport.js:318

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

Viewport.js:447

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

Viewport.js:393

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

Viewport.js:366

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

Viewport.js:417

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

Viewport.js:771

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 ()

Viewport.js:196

Get visible world bounds of viewport

mouseEdges (options)

Viewport.js:862

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

Viewport.js:252

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

Viewport.js:285

MoveCorner

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

OOB ()

Viewport.js:541

Is container out of world bounds

pinch (options)Viewport

Viewport.js:725

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)

Viewport.js:161

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

Viewport.js:476

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

Viewport.js:747

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)

Viewport.js:536

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

Viewport.js:217

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

Viewport.js:205

Changes coordinate from screen to world

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

update (elapsed)

Viewport.js:117

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

Viewport.js:791

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

Viewport.js:508

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

Viewport.js:498

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

Viewport.js:974

Fires when a bounce ends in the x direction

Type:

bounce-x-start

Viewport.js:969

Fires when a bounce starts in the x direction

Type:

bounce-y-end

Viewport.js:984

Fires when a bounce ends in the y direction

Type:

bounce-y-start

Viewport.js:979

Fires when a bounce starts in the y direction

Type:

clicked

Viewport.js:915

Fires after a mouse or touch click

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

drag-end

Viewport.js:931

Fires when a drag ends

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

drag-start

Viewport.js:923

Fires when a drag starts

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

frame-end

Viewport.js:1039

Fires at the end of an update frame

Type:

mouse-edge-end

Viewport.js:1009

Fires when the mouse-edge scrolling ends

Type:

mouse-edge-start

Viewport.js:1004

Fires when a mouse-edge starts to scroll

Type:

moved

Viewport.js:1014

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

Viewport.js:1029

Fires when viewport stops moving

Type:

pinch-end

Viewport.js:944

Fires when a pinch end

Type:

pinch-start

Viewport.js:939

Fires when a pinch starts

Type:

snap-end

Viewport.js:954

Fires when a snap ends

Type:

snap-start

Viewport.js:949

Fires when a snap starts

Type:

snap-zoom-end

Viewport.js:964

Fires when a snap-zoom ends

Type:

snap-zoom-start

Viewport.js:959

Fires when a snap-zoom starts

Type:

wheel

Viewport.js:989

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

Viewport.js:999

Fires when a wheel-scroll occurs

Type:

zoomed

Viewport.js:1022

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

Viewport.js:1034

Fires when viewport stops zooming

Type: