Package edu.umd.cs.piccolo

Class PCamera

java.lang.Object
edu.umd.cs.piccolo.PNode
edu.umd.cs.piccolo.PCamera
All Implemented Interfaces:
Printable, Serializable, Cloneable
public class PCamera extends PNode
PCamera represents a viewport onto a list of layer nodes. Each camera maintains a view transform through which it views these layers. Translating and scaling this view transform is how zooming and panning are implemented.

Cameras are also the point through which all PInputEvents enter Piccolo. The canvas coordinate system and the local coordinate system of the topmost camera should always be the same.

Version:
1.0
Author:
Jesse Grosjean
See Also:

  • Field Details

    • PROPERTY_LAYERS

      public static final String PROPERTY_LAYERS
      The property name that identifies a change in the set of this camera's layers (see getLayer, getLayerCount, getLayersReference). A property change event's new value will be a reference to the list of this nodes layers, but old value will always be null.
      See Also:

    • PROPERTY_CODE_LAYERS

      public static final int PROPERTY_CODE_LAYERS
      The property code that identifies a change in the set of this camera's layers (see getLayer, getLayerCount, getLayersReference). A property change event's new value will be a reference to the list of this nodes layers, but old value will always be null.
      See Also:

    • PROPERTY_VIEW_TRANSFORM

      public static final String PROPERTY_VIEW_TRANSFORM
      The property name that identifies a change in this camera's view transform (see getViewTransform, getViewTransformReference). A property change event's new value will be a reference to the view transform, but old value will always be null.
      See Also:

    • PROPERTY_CODE_VIEW_TRANSFORM

      public static final int PROPERTY_CODE_VIEW_TRANSFORM
      The property code that identifies a change in this camera's view transform (see getViewTransform, getViewTransformReference). A property change event's new value will be a reference to the view transform, but old value will always be null.
      See Also:

    • VIEW_CONSTRAINT_NONE

      public static final int VIEW_CONSTRAINT_NONE
      Denotes that the view has no constraints.
      See Also:

    • VIEW_CONSTRAINT_ALL

      public static final int VIEW_CONSTRAINT_ALL
      Enforces that the view be able to see all nodes in the scene.
      See Also:

    • VIEW_CONSTRAINT_CENTER

      public static final int VIEW_CONSTRAINT_CENTER
      Constrains the the view to be centered on the scene's full bounds.
      See Also:

  • Constructor Details

    • PCamera

      public PCamera()
      Create a new camera with an empy list of layers.

  • Method Details

    • getComponent

      public PComponent getComponent()
      Return the component for this camera, or null if no component has been associated with this camera, as may be the case for internal cameras.
      Returns:
      the component for this camera, or null if no such component exists

    • setComponent

      public void setComponent(PComponent component)
      Set the component for this camera to component. The component, if non-null, receives repaint notification from this camera.
      Parameters:
      component - component for this camera

    • repaintFrom

      public void repaintFrom(PBounds localBounds, PNode sourceNode)
      Repaint this camera and forward the repaint request to the component for this camera, if it is non-null.
      Overrides:
      repaintFrom in class PNode
      Parameters:
      localBounds - bounds that require repainting, in local coordinates
      sourceNode - node from which the repaint message originates, may be the camera itself

    • repaintFromLayer

      public void repaintFromLayer(PBounds viewBounds, PLayer repaintedLayer)
      Repaint from one of the camera's layers. The repaint region needs to be transformed from view to local in this case. Unlike most repaint methods in Piccolo2D this one must not modify the viewBounds parameter.
      Parameters:
      viewBounds - bounds that require repainting, in view coordinates
      repaintedLayer - layer dispatching the repaint notification
      Since:
      1.3

    • repaintFromLayer

      public void repaintFromLayer(PBounds viewBounds, PNode repaintedLayer)
      Deprecated.
      by repaintFromLayer(PBounds, PLayer). Will be removed in version 2.0.
      Parameters:
      viewBounds - bounds that require repainting, in view coordinates
      repaintedLayer - layer dispatching the repaint notification

    • getLayersReference

      public List getLayersReference()
      Return a reference to the list of layers viewed by this camera.
      Returns:
      the list of layers viewed by this camera

    • getLayerCount

      public int getLayerCount()
      Return the number of layers in the list of layers viewed by this camera.
      Returns:
      the number of layers in the list of layers viewed by this camera

    • getLayer

      public PLayer getLayer(int index)
      Return the layer at the specified position in the list of layers viewed by this camera.
      Parameters:
      index - index of the layer to return
      Returns:
      the layer at the specified position in the list of layers viewed by this camera
      Throws:
      IndexOutOfBoundsException - if the specified index is out of range (index < 0 || index >= getLayerCount())

    • indexOfLayer

      public int indexOfLayer(PLayer layer)
      Return the index of the first occurrence of the specified layer in the list of layers viewed by this camera, or -1 if the list of layers viewed by this camera does not contain the specified layer.
      Parameters:
      layer - layer to search for
      Returns:
      the index of the first occurrence of the specified layer in the list of layers viewed by this camera, or -1 if the list of layers viewed by this camera does not contain the specified layer

    • addLayer

      public void addLayer(PLayer layer)
      Inserts the specified layer at the end of the list of layers viewed by this camera. Layers may be viewed by multiple cameras at once.
      Parameters:
      layer - layer to add

    • addLayer

      public void addLayer(int index, PLayer layer)
      Inserts the specified layer at the specified position in the list of layers viewed by this camera. Layers may be viewed by multiple cameras at once.
      Parameters:
      index - index at which the specified layer is to be inserted
      layer - layer to add
      Throws:
      IndexOutOfBoundsException - if the specified index is out of range (index < 0 || index >= getLayerCount())

    • removeLayer

      public PLayer removeLayer(PLayer layer)
      Removes the first occurrence of the specified layer from the list of layers viewed by this camera, if it is present.
      Parameters:
      layer - layer to be removed
      Returns:
      the specified layer

    • removeLayer

      public PLayer removeLayer(int index)
      Removes the element at the specified position from the list of layers viewed by this camera.
      Parameters:
      index - index of the layer to remove
      Returns:
      the layer previously at the specified position
      Throws:
      IndexOutOfBoundsException - if the specified index is out of range (index < 0 || index >= getLayerCount())

    • getUnionOfLayerFullBounds

      public PBounds getUnionOfLayerFullBounds()
      Return the union of the full bounds of each layer in the list of layers viewed by this camera, or empty bounds if the list of layers viewed by this camera is empty.
      Returns:
      the union of the full bounds of each layer in the list of layers viewed by this camera, or empty bounds if the list of layers viewed by this camera is empty

    • paint

      protected void paint(PPaintContext paintContext)
      Paint this camera and then paint this camera's view through its view transform.
      Overrides:
      paint in class PNode
      Parameters:
      paintContext - context in which painting occurs

    • paintCameraView

      protected void paintCameraView(PPaintContext paintContext)
      Paint all the layers in the list of layers viewed by this camera. This method is called after the view transform and clip have been applied to the specified paint context.
      Parameters:
      paintContext - context in which painting occurs

    • paintDebugInfo

      protected void paintDebugInfo(PPaintContext paintContext)
      Renders debug info onto the newly painted scene. Things like full bounds and bounds are painted as filled and outlines.
      Parameters:
      paintContext - context in which painting occurs

    • fullPaint

      public void fullPaint(PPaintContext paintContext)
      Paint this node and all of its descendants. Most subclasses do not need to override this method, they should override paint or paintAfterChildren instead.

      Pushes this camera onto the specified paint context so that it can be accessed later by PPaintContext.getCamera().

      Overrides:
      fullPaint in class PNode
      Parameters:
      paintContext - the paint context to use for painting this node and its children

    • pick

      public PPickPath pick(double x, double y, double halo)
      Generate and return a PPickPath for the point x,y specified in the local coord system of this camera. Picking is done with a rectangle, halo specifies how large that rectangle will be.
      Parameters:
      x - the x coordinate of the pick path given in local coordinates
      y - the y coordinate of the pick path given in local coordinates
      halo - the distance from the x,y coordinate that is considered for inclusion in the pick path
      Returns:
      the picked path

    • pickAfterChildren

      protected boolean pickAfterChildren(PPickPath pickPath)
      Try to pick this node after its children have had a chance to be picked. Most subclasses the define a different geometry will need to override this method.

      After the direct children of this camera have been given a chance to be picked all of the layers in the list of layers viewed by this camera are given a chance to be picked.

      Overrides:
      pickAfterChildren in class PNode
      Parameters:
      pickPath - the pick path used for the pick operation
      Returns:
      true if any of the layers in the list of layers viewed by this camera were picked

    • pickCameraView

      protected boolean pickCameraView(PPickPath pickPath)
      Try to pick all of the layers in the list of layers viewed by this camera. This method is called after the view transform has been applied to the specified pick path.
      Parameters:
      pickPath - pick path
      Returns:
      true if any of the layers in the list of layers viewed by this camera were picked

    • getViewBounds

      public PBounds getViewBounds()
      Return the bounds of this camera in the view coordinate system.
      Returns:
      the bounds of this camera in the view coordinate system

    • setViewBounds

      public void setViewBounds(Rectangle2D centerBounds)
      Animates the camera's view so that the given bounds (in camera layer's coordinate system) are centered within the cameras view bounds. Use this method to point the camera at a given location.
      Parameters:
      centerBounds - the targetBounds

    • getViewScale

      public double getViewScale()
      Return the scale applied by the view transform to the list of layers viewed by this camera.
      Returns:
      the scale applied by the view transform to the list of layers viewed by this camera

    • scaleView

      public void scaleView(double scale)
      Scale the view transform applied to the list of layers viewed by this camera by scale about the point [0, 0].
      Parameters:
      scale - view transform scale

    • scaleViewAboutPoint

      public void scaleViewAboutPoint(double scale, double x, double y)
      Scale the view transform applied to the list of layers viewed by this camera by scale about the specified point [x, y].
      Parameters:
      scale - view transform scale
      x - scale about point, x coordinate
      y - scale about point, y coordinate

    • setViewScale

      public void setViewScale(double scale)
      Set the scale applied by the view transform to the list of layers viewed by this camera to scale.
      Parameters:
      scale - view transform scale

    • translateView

      public void translateView(double dx, double dy)
      Translate the view transform applied to the list of layers viewed by this camera by [dx, dy].
      Parameters:
      dx - translate delta x
      dy - translate delta y

    • setViewOffset

      public void setViewOffset(double x, double y)
      Set the offset for the view transform applied to the list of layers viewed by this camera to [x, y].
      Parameters:
      x - offset x
      y - offset y

    • getViewTransform

      public PAffineTransform getViewTransform()
      Return a copy of the view transform applied to the list of layers viewed by this camera.
      Returns:
      a copy of the view transform applied to the list of layers viewed by this camera

    • getViewTransformReference

      public PAffineTransform getViewTransformReference()
      Return a reference to the view transform applied to the list of layers viewed by this camera.
      Returns:
      the view transform applied to the list of layers viewed by this camera

    • setViewTransform

      public void setViewTransform(AffineTransform viewTransform)
      Set the view transform applied to the list of layers viewed by this camera to viewTransform.
      Parameters:
      viewTransform - view transform applied to the list of layers viewed by this camera

    • animateViewToCenterBounds

      public PTransformActivity animateViewToCenterBounds(Rectangle2D centerBounds, boolean shouldScaleToFit, long duration)
      Animate the camera's view from its current transform when the activity starts to a new transform that centers the given bounds in the camera layer's coordinate system into the cameras view bounds. If the duration is 0 then the view will be transformed immediately, and null will be returned. Else a new PTransformActivity will get returned that is set to animate the camera's view transform to the new bounds. If shouldScale is true, then the camera will also scale its view so that the given bounds fit fully within the cameras view bounds, else the camera will maintain its original scale.
      Parameters:
      centerBounds - the bounds which the animation will pace at the center of the view
      shouldScaleToFit - whether the camera should scale the view while animating to it
      duration - how many milliseconds the animations should take
      Returns:
      the scheduled PTransformActivity

    • animateViewToPanToBounds

      public PTransformActivity animateViewToPanToBounds(Rectangle2D panToBounds, long duration)
      Pan the camera's view from its current transform when the activity starts to a new transform so that the view bounds will contain (if possible, intersect if not possible) the new bounds in the camera layers coordinate system. If the duration is 0 then the view will be transformed immediately, and null will be returned. Else a new PTransformActivity will get returned that is set to animate the camera's view transform to the new bounds.
      Parameters:
      panToBounds - the bounds to which the view will animate to
      duration - the duration of the animation given in milliseconds
      Returns:
      the scheduled PTransformActivity

    • animateViewToIncludeBounds

      public PTransformActivity animateViewToIncludeBounds(Rectangle2D includeBounds, long duration)
      Deprecated.
      Renamed to animateViewToPanToBounds
      Pan the camera's view from its current transform when the activity starts to a new transform so that the view bounds will contain (if possible, intersect if not possible) the new bounds in the camera layers coordinate system. If the duration is 0 then the view will be transformed immediately, and null will be returned. Else a new PTransformActivity will get returned that is set to animate the camera's view transform to the new bounds.
      Parameters:
      includeBounds - the bounds to which the view will animate to
      duration - the duration of the animation given in milliseconds
      Returns:
      the scheduled PTransformActivity

    • animateViewToTransform

      public PTransformActivity animateViewToTransform(AffineTransform destination, long duration)
      Animate the cameras view transform from its current value when the activity starts to the new destination transform value.
      Parameters:
      destination - the transform to which the view should be transformed into
      duration - the duraiton in milliseconds the animation should take
      Returns:
      the scheduled PTransformActivity

    • getViewConstraint

      public int getViewConstraint()
      Return the constraint applied to the view. The view constraint will be one of VIEW_CONSTRAINT_NONE, VIEW_CONSTRAINT_CENTER, or VIEW_CONSTRAINT_CENTER. Defaults to VIEW_CONSTRAINT_NONE.
      Returns:
      the view constraint being applied to the view

    • setViewConstraint

      public void setViewConstraint(int viewConstraint)
      Set the view constraint to apply to the view to viewConstraint. The view constraint must be one of VIEW_CONSTRAINT_NONE, VIEW_CONSTRAINT_CENTER, or VIEW_CONSTRAINT_CENTER.
      Parameters:
      viewConstraint - constraint to apply to the view
      Throws:
      IllegalArgumentException - if viewConstraint is not one of VIEW_CONSTRAINT_NONE, VIEW_CONSTRAINT_CENTER, or VIEW_CONSTRAINT_CENTER

    • applyViewConstraints

      protected void applyViewConstraints()
      Transforms the view so that it conforms to the given constraint.

    • viewToLocal

      public Point2D viewToLocal(Point2D viewPoint)
      Convert the point from the camera's view coordinate system to the camera's local coordinate system. The given point is modified by this.
      Parameters:
      viewPoint - the point to transform to the local coordinate system from the view's coordinate system
      Returns:
      the transformed point

    • viewToLocal

      public Dimension2D viewToLocal(Dimension2D viewDimension)
      Convert the dimension from the camera's view coordinate system to the camera's local coordinate system. The given dimension is modified by this.
      Parameters:
      viewDimension - the dimension to transform from the view system to the local coordinate system
      Returns:
      returns the transformed dimension

    • viewToLocal

      public Rectangle2D viewToLocal(Rectangle2D viewRectangle)
      Convert the rectangle from the camera's view coordinate system to the camera's local coordinate system. The given rectangle is modified by this method.
      Parameters:
      viewRectangle - the rectangle to transform from view to local coordinate System
      Returns:
      the transformed rectangle

    • localToView

      public Point2D localToView(Point2D localPoint)
      Convert the point from the camera's local coordinate system to the camera's view coordinate system. The given point is modified by this method.
      Parameters:
      localPoint - point to transform from local to view coordinate system
      Returns:
      the transformed point

    • localToView

      public Dimension2D localToView(Dimension2D localDimension)
      Convert the dimension from the camera's local coordinate system to the camera's view coordinate system. The given dimension is modified by this method.
      Parameters:
      localDimension - the dimension to transform from local to view coordinate systems
      Returns:
      the transformed dimension

    • localToView

      public Rectangle2D localToView(Rectangle2D localRectangle)
      Convert the rectangle from the camera's local coordinate system to the camera's view coordinate system. The given rectangle is modified by this method.
      Parameters:
      localRectangle - the rectangle to transform from local to view coordinate system
      Returns:
      the transformed rectangle