Package nl.colorize.multimedialib.renderer

Class Canvas

  • public class Canvas
extends java.lang.Object
    Defines the resolution of the application graphics independently from the screen resolution of the device. This allows applications to have a reasonably consistent user interface across devices with different screen sizes, as the canvas can be scaled depending on the difference between preferred canvas size and the actual screen size. This class is then used to convert between the two coordinate systems.

    In some cases no scaling is necessary, and the application will simply use the native resolution of the screen. This is referred to as a "flexible" canvas, which does not have a preferred size or aspect ratio and will simply translate coordinates 1-to-1.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Canvas.ZoomStrategy  

    • Constructor Summary

      Constructors 
      Constructor Description
      Canvas​(int preferredWidth, int preferredHeight, Canvas.ZoomStrategy zoomStrategy)
      Creates a new canvas with the specified zoom strategy.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void changeStrategy​(Canvas.ZoomStrategy zoomStrategy)
      Changes the strategy used by the canvas at runtime.
      static Canvas fixed​(int preferredWidth, int preferredHeight)
      Deprecated.
      This method is not clear enough on how the canvas will behave at different aspect ratios.
      static Canvas flexible​(int initialWidth, int initialHeight)
      Creates a canvas that resizes itself to match the screen size, always keeping a zoom level of 1.0.
      Rect getBounds()  
      Point2D getCenter()  
      int getHeight()  
      int getWidth()  
      float getZoomLevel()  
      void offsetScreen​(int offsetX, int offsetY)
      Offset the canvas position on the screen.
      void resizeScreen​(int screenWidth, int screenHeight)
      Sets the screen dimensions to the specified values.
      float toCanvasX​(int screenX)  
      float toCanvasY​(int screenY)  
      float toScreenX​(float canvasX)  
      float toScreenY​(float canvasY)  
      java.lang.String toString()  
      static Canvas zoomBalanced​(int preferredWidth, int preferredHeight)
      Creates a canvas with the specified dimensions, that will scale in a way that strikes a balance between the preferred aspect ratio and the actual aspect ratio of the screen.
      static Canvas zoomIn​(int preferredWidth, int preferredHeight)
      Creates a canvas with the specified dimensions, that will scale based on the smallest screen dimension.
      static Canvas zoomOut​(int preferredWidth, int preferredHeight)
      Creates a canvas with the specified dimensions, that will scale based on the largest screen dimension.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • Canvas

        public Canvas​(int preferredWidth,
              int preferredHeight,
              Canvas.ZoomStrategy zoomStrategy)
        Creates a new canvas with the specified zoom strategy. Zooming will only occur if the canvas cannot be displayed at its preferred size.

    • Method Detail

      • changeStrategy

        public void changeStrategy​(Canvas.ZoomStrategy zoomStrategy)
        Changes the strategy used by the canvas at runtime.

      • resizeScreen

        public void resizeScreen​(int screenWidth,
                         int screenHeight)
        Sets the screen dimensions to the specified values. This method should be called by the renderer when the application window is first created, and whenever the window is resized.

      • offsetScreen

        public void offsetScreen​(int offsetX,
                         int offsetY)
        Offset the canvas position on the screen. This is mainly needed for when the screen contains system UI such as a status bar or window title where no application graphics can be displayed.

      • getWidth

        public int getWidth()

      • getHeight

        public int getHeight()

      • getBounds

        public Rect getBounds()

      • getCenter

        public Point2D getCenter()

      • getZoomLevel

        public float getZoomLevel()

      • toCanvasX

        public float toCanvasX​(int screenX)

      • toCanvasY

        public float toCanvasY​(int screenY)

      • toScreenX

        public float toScreenX​(float canvasX)

      • toScreenY

        public float toScreenY​(float canvasY)

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • flexible

        public static Canvas flexible​(int initialWidth,
                              int initialHeight)
        Creates a canvas that resizes itself to match the screen size, always keeping a zoom level of 1.0. The provided width and height are only used to initialize the canvas but will not be used afterwards.

      • fixed

        @Deprecated
public static Canvas fixed​(int preferredWidth,
                           int preferredHeight)
        Deprecated.
        This method is not clear enough on how the canvas will behave at different aspect ratios. Use zoomIn(int, int) or zoomOut(int, int) instead to define an explicit zoom strategy.
        Creates a canvas with fixed dimensions. The canvas will be scaled to match the current screen size. Note that it might not be possible to retain the preferred canvas dimensions in all cases, as the screen might have a different aspect ratio than the canvas.

      • zoomIn

        public static Canvas zoomIn​(int preferredWidth,
                            int preferredHeight)
        Creates a canvas with the specified dimensions, that will scale based on the smallest screen dimension. This means that the canvas will seem zoomed in when the screen and the canvas have very different aspect ratios.

      • zoomOut

        public static Canvas zoomOut​(int preferredWidth,
                             int preferredHeight)
        Creates a canvas with the specified dimensions, that will scale based on the largest screen dimension. This means that the canvas will seem zoomed out when the screen and the canvas have very different aspect ratios.

      • zoomBalanced

        public static Canvas zoomBalanced​(int preferredWidth,
                                  int preferredHeight)
        Creates a canvas with the specified dimensions, that will scale in a way that strikes a balance between the preferred aspect ratio and the actual aspect ratio of the screen.