Package ca.corbett.extras.image.animation

Class ImageScroller

java.lang.Object
ca.corbett.extras.image.animation.ImageScroller
public class ImageScroller extends Object
Displays an oversized image and slowly scrolls it either horizontally back-and-forth (for landscape images) or vertically up-and-down (for portrait images). The trick here is that when a scroll limit is reached, instead of just "bouncing" and immediately reversing the scroll direction at full speed, the image scrolling will slow down as it approaches the scroll limit, bounce, and then slowly accelerate as it moves away from the scroll limit. This makes the scrolling feel a lot more natural.

Controlling the bounce parameters

  • You can use EasingStrength to determine the "strength" of the bounce. The options are Linear, Quadratic, and Cubic, with a progressively pronounced effect. The default is Quadratic.
  • bounceZoneRatio determines what percentage of the image area to use as the "bounce zone" - that is, the zone in which deceleration and acceleration will happen. The default value is 0.06, indicating the extreme 6% edges of the image will be used for the bounce zone. Valid values range from 0.0 (no bounce, just reverse direction at full speed) up to 0.5 (half the image).
  • ScrollSpeed is used to determine the maximum speed of the image scrolling (i.e. when not decelerating or accelerating). Values range from VERY_SLOW (1) up to VERY_FAST (5). The numeric valud represents the number of pixels per frame that the image will move.
  • minSpeedRatio determines the minimum scrolling speed (during a "bounce") as a percentage of the ScrollSpeed. Note that the image will scroll a minimum pixel value of 1 per frame regardless of minSpeedRatio. Fractional pixel values are rounded up to 1 to prevent the animation from freezing.
Since:
swing-extras 2.3
Author:
scorbo2 (with help from Claude!)

  • Field Details

    • isRunning

      protected boolean isRunning

    • scrollSpeed

      protected ImageScroller.ScrollSpeed scrollSpeed

    • easingStrength

      protected ImageScroller.EasingStrength easingStrength

    • image

      protected BufferedImage image

    • displayWidth

      protected final int displayWidth

    • displayHeight

      protected final int displayHeight

    • zoomFactor

      protected float zoomFactor

    • xOffset

      protected int xOffset

    • yOffset

      protected int yOffset

    • xDelta

      protected float xDelta

    • yDelta

      protected float yDelta

    • xDirection

      protected int xDirection

    • yDirection

      protected int yDirection

    • scaleCalculationsDone

      protected boolean scaleCalculationsDone

    • bounceZoneRatio

      protected float bounceZoneRatio

    • minSpeedRatio

      protected float minSpeedRatio

  • Constructor Details

    • ImageScroller

      public ImageScroller(BufferedImage image, int displayWidth, int displayHeight)

  • Method Details

    • getScrollSpeed

      public ImageScroller.ScrollSpeed getScrollSpeed()

    • setScrollSpeed

      public void setScrollSpeed(ImageScroller.ScrollSpeed scrollSpeed)
      This represents the maximum scrolling speed, in pixels per frame. The actual scrolling speed may be less if the image is approaching or receding away from a "bounce point" (scroll limit).

    • getEasingStrength

      public ImageScroller.EasingStrength getEasingStrength()

    • setEasingStrength

      public void setEasingStrength(ImageScroller.EasingStrength easingStrength)
      Sets the strength of the "bounce" calculations, to exaggerate the acceleration and deceleration effects.

    • getBounceZoneRatio

      public float getBounceZoneRatio()

    • setBounceZoneRatio

      public void setBounceZoneRatio(float bounceZoneRatio)
      Sets the width of the "bounce zones", or edges of the image where we will slow down as we approach a scroll limit and speed up as we scroll away from it. This is expressed as a percentage of the image scroll dimension (width for landscape images and height for portrait images). Valid values are 0.0 for no bounce effect up to 0.5 for a very exaggerated bounce effect. The default value is 0.06.

    • getMinSpeedRatio

      public float getMinSpeedRatio()

    • setMinSpeedRatio

      public void setMinSpeedRatio(float minSpeedRatio)
      Sets the minimum allowable scroll speed during deceleration/acceleration, expressed as a percentage of the maximum speed. Note that the image will always scroll by at least one pixel per frame, to prevent the case where a fractional pixel movement value will be rounded down to 0 and the animation freezes.

    • setImage

      public void setImage(BufferedImage image)
      Sets the image to be scrolled. Can be landscape (wider than tall) or portrait (taller than wide). Large images are better! The whole point is to scroll within an image larger than the display area. Think like 3000x1080 or something. The image will be scaled if needed so that it fills the display. (For example, a 3000x960 image on a 1920x1080 display would be scaled up proportionally to 3375x1080 so that it vertically fills the display).

    • getImage

      public BufferedImage getImage()

    • reset

      protected void reset()

    • stop

      public void stop()
      Stops the scrolling and flushes the current image.

    • renderFrame

      public void renderFrame(Graphics2D g)
      Renders a single frame of animation and handles scrolling the image by an appropriate amount. Your animation loop may target whatever FPS your application requires, and this method will scroll the image by the correct amount of pixels based on our ScrollSpeed.

    • calculateSpeedMultiplier

      protected float calculateSpeedMultiplier(int currentPos, int minPos, int screenSize)
      Calculates speed multiplier based on distance from bounce points
      Parameters:
      currentPos - Current position (xOffset or yOffset)
      minPos - Minimum position (boundary)
      screenSize - Screen dimension (width or height)
      Returns:
      Speed multiplier between minSpeedRatio and 1.0