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
Members
-
World coordinates of the bottom edge of the screen
-
Center of screen in world coordinates
-
Top-left corner of Viewport
-
Determines whether the viewport is dirty (i.e., needs to be rendered to the screen because of a change)
-
Permanently changes the Viewport's hitArea
NOTE: if not set then hitArea = PIXI.Rectangle(Viewport.left, Viewport.top, Viewport.worldScreenWidth, Viewport.worldScreenHeight)
-
World coordinates of the left edge of the screen
-
Pause viewport (including animation updates such as decelerate)
-
World coordinates of the right edge of the screen
-
Changes scale of viewport and maintains center of viewport
-
Get how many world pixels fit on screen's height
-
Get how many world pixels fit in screen's width
-
World height in screen coordinates
-
World width in screen coordinates
-
World coordinates of the top edge of the screen
-
World height, in pixels
-
Screen height in world coordinates
-
Screen width in world coordinates
-
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 to world boundaries or other provided boundaries There are three ways to clamp:
- 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
- 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
- none = the world is clamped but there is no special behavior
- center = the world is centered on the viewport
- 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 -
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 -
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
-
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 -
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 -
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
-
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 -
Get visible world bounds of viewport
-
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 -
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 -
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
-
Changes coordinate from world to screen
Name Type Description x
number | PIXI.Point y
number Returns:
Type Description PIXI.Point -
Changes coordinate from screen to world
Name Type Description x
number | PIXI.Point y
number Returns:
Type Description PIXI.Point -
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 defaultName 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
-
Fires when a bounce ends in the x direction
Type:
-
Fires when a bounce starts in the x direction
Type:
-
Fires when a bounce ends in the y direction
Type:
-
Fires when a bounce starts in the y direction
Type:
-
Fires after a mouse or touch click
Type:
- object
Properties:
Name Type Description screen
PIXI.Point world
PIXI.Point viewport
Viewport -
Fires when a drag ends
Type:
- object
Properties:
Name Type Description screen
PIXI.Point world
PIXI.Point viewport
Viewport -
Fires when a drag starts
Type:
- object
Properties:
Name Type Description screen
PIXI.Point world
PIXI.Point viewport
Viewport -
Fires at the end of an update frame
Type:
-
Fires when the mouse-edge scrolling ends
Type:
-
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)
-
Fires when viewport stops moving
Type:
-
Fires when a pinch end
Type:
-
Fires when a pinch starts
Type:
-
Fires when a snap ends
Type:
-
Fires when a snap starts
Type:
-
Fires when a snap-zoom ends
Type:
-
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 -
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)
-
Fires when viewport stops zooming
Type: