pixi-viewport
    Preparing search index...

    Class Viewport

    A Container that acts as a 2D camera: add your world to it, then turn on plugins for the interactions you want (drag, pinch, wheel, clamp, and so on).

    const viewport = new Viewport({ worldWidth: 2000, worldHeight: 2000, events: app.renderer.events });

    app.stage.addChild(viewport);
    viewport.drag().pinch().wheel().decelerate();

    Plugins always run in a fixed order, whatever order you add them in. Use Viewport.plugins to pause, resume, or remove them, or to add your own Plugin.

    Listen with viewport.on(name, callback). These are in addition to pixi's own Container events.

    Event Callback receives When
    clicked ClickedEvent a pointer is pressed and released without moving past the threshold
    drag-start, drag-end DragEvent a drag starts or ends
    pinch-start, pinch-end Viewport a two-finger pinch starts or ends
    wheel-start WheelStartEvent the wheel or a trackpad pinch zooms
    wheel-scroll Viewport the wheel scrolls (drag plugin with wheel: true)
    snap-start, snap-end Viewport Viewport.snap starts or finishes
    snap-zoom-start, snap-zoom-end Viewport Viewport.snapZoom starts or finishes
    bounce-x-start, bounce-x-end, bounce-y-start, bounce-y-end Viewport a bounce starts or ends
    edge-scroll-start, edge-scroll-end Viewport Viewport.edgeScroll starts or stops scrolling
    mouse-edge-start, mouse-edge-end Viewport the deprecated Viewport.mouseEdges starts or stops
    animate-end Viewport Viewport.animate finishes
    moved MovedEvent the viewport moves (every frame while moving)
    zoomed ZoomedEvent the viewport zooms (every frame while zooming)
    moved-end, zoomed-end Viewport moving or zooming stops
    frame-end Viewport after each update
    plugin-remove string (plugin name) a plugin is removed

    Inherited Container members aren't listed here; see pixi's documentation.

    Hierarchy

    Index
    constructor
    input lastViewport? moving? options plugins screenHeight screenWidth threshold zooming?
    bottom center corner dirty forceHitArea left pause right scaled screenHeightInWorldPixels screenWidthInWorldPixels screenWorldHeight screenWorldWidth top worldHeight worldScreenHeight worldScreenWidth worldWidth
    animate bounce clamp clampZoom decelerate destroy drag edgeScroll ensureVisible findCover findFit findFitHeight findFitWidth fit fitHeight fitWidth fitWorld follow getVisibleBounds mouseEdges moveCenter moveCorner OOB pinch resize setZoom snap snapZoom toScreen toWorld update wheel zoom zoomPercent
    input: InputManager
    lastViewport?: IViewportTransformState | null
    moving?: boolean

    Flags whether the viewport is being panned

    options: ICompleteViewportOptions

    The options passed when creating this viewport, merged with the default values

    plugins: PluginManager

    Use this to add user plugins or access existing plugins (e.g., to pause, resume, or remove them)

    screenHeight: number
    screenWidth: number
    threshold: number

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

    zooming?: boolean

    Flags whether the viewport zoom is being changed.

    • get bottom(): number

      World coordinates of the bottom edge of the screen

      Returns number

    • set bottom(value: number): void

      Parameters

      • value: number

      Returns void

    • get dirty(): boolean

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

      Returns boolean

    • set dirty(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get forceHitArea(): IHitArea | null | undefined

      Permanently changes the Viewport's hitArea

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

      Returns IHitArea | null | undefined

    • set forceHitArea(value: IHitArea | null | undefined): void

      Parameters

      Returns void

    • get left(): number

      World coordinates of the left edge of the screen

      Returns number

    • set left(value: number): void

      Parameters

      • value: number

      Returns void

    • get pause(): boolean

      Pause viewport (including animation updates such as decelerate)

      Returns boolean

    • set pause(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get right(): number

      World coordinates of the right edge of the screen

      Returns number

    • set right(value: number): void

      Parameters

      • value: number

      Returns void

    • get scaled(): number

      Changes scale of viewport and maintains center of viewport

      Returns number

    • set scaled(scale: number): void

      Parameters

      • scale: number

      Returns void

    • get screenHeightInWorldPixels(): number

      Get how many world pixels fit on screen's height

      Returns number

    • get screenWidthInWorldPixels(): number

      Get how many world pixels fit in screen's width

      Returns number

    • get screenWorldHeight(): number

      World height in screen coordinates

      Returns number

    • get screenWorldWidth(): number

      World width in screen coordinates

      Returns number

    • get top(): number

      World coordinates of the top edge of the screen

      Returns number

    • set top(value: number): void

      Parameters

      • value: number

      Returns void

    • get worldHeight(): number

      World height, in pixels

      Returns number

    • set worldHeight(value: number): void

      Parameters

      • value: number

      Returns void

    • get worldScreenHeight(): number

      Screen height in world coordinates

      Returns number

    • get worldScreenWidth(): number

      Screen width in world coordinates

      Returns number

    • get worldWidth(): number

      World width, in pixels

      Returns number

    • set worldWidth(value: number): void

      Parameters

      • value: number

      Returns void

    • 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

      Parameters

      Returns Viewport

      this

    • 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).

      Parameters

      Returns Viewport

      this

    • 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.

      Parameters

      Returns Viewport

      this

    • Move the viewport so the bounding box is visible

      Parameters

      • x: number

        left

      • y: number

        top

      • width: number
      • height: number
      • OptionalresizeToFit: boolean

        Resize the viewport so the box fits within the viewport

      Returns void

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

      Parameters

      • width: number

        in world pixels

      • height: number

        in world pixels

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

      Parameters

      • width: number

        in world pixels

      • height: number

        in world pixels

      Returns number

      scale

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

      Parameters

      • height: number

        Height in world pixels

      Returns number

      • scale

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

      Parameters

      • width: number

        Width in world pixels

      Returns number

      • scale

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

      Parameters

      • Optionalcenter: boolean

        maintain the same center of the screen after zoom

      • Optionalwidth: number = ...

        desired width

      • Optionalheight: number = ...

        desired height

      Returns Viewport

      this

    • Change zoom so the height fits in the viewport

      Parameters

      • Optionalheight: number = ...

        in world coordinates

      • Optionalcenter: boolean

        maintain the same center of the screen after zoom

      • OptionalscaleX: boolean = true

        whether to set scaleX = scaleY

      • OptionalnoClamp: boolean

        whether to disable clamp-zoom

      Returns Viewport

      this

    • Change zoom so the width fits in the viewport

      Parameters

      • width: number = ...

        width in world coordinates

      • Optionalcenter: boolean

        maintain the same center

      • scaleY: boolean = true

        whether to set scaleY=scaleX

      • OptionalnoClamp: boolean

        whether to disable clamp-zoom

      Returns Viewport

      this

    • Change zoom so it fits the entire world in the viewport

      Parameters

      • Optionalcenter: boolean

        maintain the same center of the screen after zoom

      Returns Viewport

      this

    • 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')

      Parameters

      Returns Viewport

      this

      'moved' event

    • Get visible world bounds of viewport (normalized so width and height are positive when scale is negative)

      Parameters

      • out: Rectangle = ...

        rectangle to write into instead of creating a new one

      Returns Rectangle

    • 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

      Parameters

      Returns Viewport

      use Viewport.edgeScroll instead: its speed is in screen pixels per second, while mouseEdges' speed scrolls by speed * speed * 0.06 world pixels per frame (so it changes with zoom and frame rate). mouseEdges keeps its current behavior for compatibility.

    • Move Viewport's top-left corner; also clamps and resets decelerate and bounce (as needed)

      Parameters

      • x: number
      • y: number

      Returns Viewport

    • move Viewport's top-left corner; also clamps and resets decelerate and bounce (as needed)

      Parameters

      Returns Viewport

    • Is container out of world bounds

      Returns {
          bottom: boolean;
          cornerPoint: Point;
          left: boolean;
          right: boolean;
          top: boolean;
      }

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

      Parameters

      • screenWidth: number = ...

        defaults to window.innerWidth

      • screenHeight: number = ...

        defaults to window.innerHeight

      • OptionalworldWidth: number
      • OptionalworldHeight: number

      Returns void

    • Zoom viewport to specific value.

      Parameters

      • scale: number

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

      • Optionalcenter: boolean

        maintain the same center of the screen after zoom

      Returns Viewport

      this

    • Update viewport on each frame.

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

      Parameters

      • elapsed: number

        time in milliseconds since last update

      Returns void

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

      Parameters

      • change: number

        in pixels

      • Optionalcenter: boolean

        maintain the same center of the screen after zoom

      Returns Viewport

      this

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

      Parameters

      • percent: number

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

      • Optionalcenter: boolean

        maintain the same center of the screen after zoom

      Returns Viewport

      this

    Settings
    Member Visibility

    On This Page
    Events
    Constructors
    Properties
    Accessors
    Methods