gscene.java

use Java code to draw on pad canvas

package no.geosoft.cc.graphics;



import java.util.Collection;
import java.awt.Adjustable;

import no.geosoft.cc.geometry.Rect;



/**
 * The GScene is the link between a GWindow and the graphics objects.
 * <p>
 * The GScene defines the viewport and the world extent and holds
 * device-to-world transformation objects. The scene is itself a
 * graphics object (GObject) and as such it may contain geometry.
 * <p>
 * Typical usage:
 *
 * <pre>
 *    // Creating a window
 *    GWindow window = new GWindow (Color.WHITE);
 *
 *    // Creating a scene within the window
 *    GScene scene = new GScene (window);
 *    scene.setWorldExtent (0.0, 0.0, 1000.0, 1000.0);
 * </pre>
 *
 * Setting world extent is optional. If unset it will have the same
 * extent (in floating point coordinates) as the device.
 * <p>
 * When geometry is specified (in GSegments), coordinates are specified
 * in either device coordinates or in world coordinates. Integer coordinates
 * are assumed to be device relative, while floating point coordinates are
 * taken to be world extent relative.
 * 
 * @author <a href="mailto:[e-mail]">Jacob Dreyer</a>
 */   
public class GScene extends GObject
{
  private final GWindow      window_;
  private final GTransformer transformer_;
  private final GAnnotator   annotator_;

  private GViewport       viewport_;
  private GWorldExtent    initialWorldExtent_;
  private GWorldExtent    currentWorldExtent_;
  private boolean         shouldZoomOnResize_;  // "see more" or "see bigger"
  private boolean         shouldWorldExtentFitViewport_;  // ie. squeeze world
  private boolean         isAnnotationValid_;
  private GScrollHandler  scrollHandler_;
  private boolean         isViewportFixed_;
  

  
  /**
   * Create a scene within the specified window. For most practical
   * purposes a window will contain one scene only.
   * <p>
   * A default viewport will be established covering the entire window.
   * This is appropriate in most cases.
   * <p>
   * A default world-extent will be established with coordinates equal
   * to the window device extent. This may be sufficient in many cases
   * if object geometry is specified in device coordinates.
   * 
   * @param window  Window to attach this scene to.
   * @param name    Name of this scene.
   */
  public GScene (GWindow window, String name)
  {
    super (name);

    shouldWorldExtentFitViewport_ = true;
    shouldZoomOnResize_           = true;  // "see bigger"

    // Attach to window
    window_ = window;
    window_.addScene (this);

    // Default viewport equals window
    int  viewportWidth  = window_.getWidth();
    int  viewportHeight = window_.getHeight();
    viewport_ = new GViewport (0, 0, viewportWidth, viewportHeight);
    isViewportFixed_ = false;

    // Default world extent equals window
    double w0[] = {0.0,                    (double) viewportHeight, 0.0};
    double w1[] = {(double) viewportWidth, (double) viewportHeight, 0.0};
    double w2[] = {0.0,                    0.0,                     0.0};
    initialWorldExtent_ = new GWorldExtent (w0, w1, w2);
    currentWorldExtent_ = new GWorldExtent (w0, w1, w2);
    
    // Create transformer instance
    transformer_ = new GTransformer (viewport_, currentWorldExtent_);

    // Instantiate the annotator object
    annotator_ = new GAnnotator (this);

    scrollHandler_ = null;

    // Initiate region
    updateRegion();
  }


  
  /**
   * Create a nameless scene within the specified window.
   * 
   * @param window  Window to acttach this scene to.
   */
  public GScene (GWindow window)
  {
    this (window, null);
  }
  

  
  /**
   * Return the scene of this GObject. At this level the scene is
   * this object.
   * 
   * @return  The scene of this GObject.
   */
  public GScene getScene()
  {
    return this;
  }


  
  /**
   * Return the window of this scene. A scene is always attached to
   * a window, a GObject is not necesserily.
   * 
   * @return  Window of this scene. 
   */
  public GWindow getWindow()
  {
    return window_;
  }
  

  
  /**
   * Return the transformation object of this scene. The transformer
   * object can be used for client-side world-to-device and device-to-world
   * coordinate transformations.
   * 
   * @return  Current transformation object of this scene.
   */
  public GTransformer getTransformer()
  {
    return transformer_;
  }
  


  /**
   * Specified if one should zoom on resize. Set to true, the current
   * image will change size (i.e. zoomed). Set to false the current image
   * will be the same size and one will possibley see more or less
   * instead. Default is true.
   * 
   * @param shouldZoomOnResize  True if world extent should be unchanged
   *                            on resize, false otherwise.
   */
  public void shouldZoomOnResize (boolean shouldZoomOnResize)
  {
    shouldZoomOnResize_ = shouldZoomOnResize;
  }
  


  /**
   * Specify wether world extent should always fit the viewport (i.e. have
   * same aspect ratio) during resize. Default is true.
   * 
   * @param shouldWorldExtentFitViewport  True if the world extent should
   *                                      fit the viewport, false otherwise.
   */
  public void shouldWorldExtentFitViewport (boolean 
                                            shouldWorldExtentFitViewport)
  {
    shouldWorldExtentFitViewport_ = shouldWorldExtentFitViewport;
  }
                                         


  /**
   * Set viewport for this scene. The viewport is specified in device
   * coordinates. The layout is as follows:
   *
   * <pre>
   *
   *     x0,y0 o-------o  x1,y1
   *           |
   *           |
   *           |
   *     x2,y2 o
   *
   * </pre>
   *
   * It is thus possible to create a skewed viewport, which may be handy
   * in some situations.
   * <p>
   * If the viewport is not set by a client, it will fit the canvas and
   * adjust to it during resize. If it is set by client, it will stay
   * fixed and not adjusted on resize.
   */
  public void setViewport (int x0, int y0, int x1, int y1, int x2, int y2)
  {
    isViewportFixed_ = true;

    // Flag old viewport as damaged
    // TODO: If the viewport is moved around in the canvas during
    // execution (rare), old content outside the new viewport will
    // remain as redraw is clipped against the new viewport.
    window_.updateDamageArea (getRegion());

    // Update viewport
    viewport_.set (x0, y0, x1, y1, x2, y2);

    // Set the new region for this scene
    updateRegion();

    // Flag new viewport as damaged
    window_.updateDamageArea (getRegion());
    
    adjustCurrentWorldExtent();
    transformer_.update (viewport_, currentWorldExtent_);

    // Redraw
    annotator_.reset();
    redraw (getVisibility());

    // Update scrollbars
    if (scrollHandler_ != null)
      scrollHandler_.updateScrollBars();
  }



  /**
   * Set viewport to a rectangular area of the screen. The viewport
   * layout is as follows:
   *
   * <pre>
   *
   *             width
   *     x0,y0 o-------o
   *           |
   *    height |
   *           |
   *           o
   *
   * </pre>
   * 
   * @param x0      X coordinate of upper left corner of viewport.
   * @param y0      Y coordinate of upper left corner of viewport.   
   * @param width   Width of viewport.
   * @param height  Height of viewport.
   */
  public void setViewport (int x0, int y0, int width, int height)
  {
    setViewport (x0, y0, x0+width-1, y0, x0, y0+height-1);
  }
  

  
  /**
   * Return current viewport.
   * 
   * @return  Current viewport of this scene.
   */
  public GViewport getViewport()
  {
    return viewport_;
  }



  /**
   * Set world extent of this scene. The layout is as follows:
   *
   * <pre>
   *        w2 o 
   *           |
   *           |
   *           |
   *        w0 o-------o w1
   * </pre>
   *
   * Thus w2 is mapped to viewport (x0,y0), w0 is mapped to (x2,y2) and
   * w1 is mapped to lower right corner of viewport.
   * <p>
   * w0,w1 and w2 are three dimensions, and the world extent can thus be
   * any plane in a 3D space, and the plane may be skewed.
   * 
   * @param w0  Point 0 of the new world extent [x,y,z].
   * @param w1  Point 1 of the new world extent [x,y,z].
   * @param w2  Point 2 of the new world extent [x,y,z].
   */
  public void setWorldExtent (double w0[], double w1[], double w2[])
  {
    initialWorldExtent_.set (w0, w1, w2);
    currentWorldExtent_.set (w0, w1, w2);
    
    adjustCurrentWorldExtent();
    transformer_.update (viewport_, currentWorldExtent_);

    // Flag new viewport as damaged
    window_.updateDamageArea (getRegion());

    redraw (getVisibility());
    
    // Update scrollbars
    if (scrollHandler_ != null)
      scrollHandler_.updateScrollBars();
  }



  /**
   * A convenience method for specifying a orthogonal world extent in
   * the Z=0 plane. The layout is as follows:
   *
   * <pre>
   *           o 
   *           |
   *    height |
   *           |
   *     x0,y0 o-------o
   *             width
   *
   * </pre>
   * 
   * @param x0      X coordinate of world extent origin.
   * @param y0      Y coordinate of world extent origin.
   * @param width   Width of world extent.
   * @param height  Height of world extent.
   */
  public void setWorldExtent (double x0, double y0, double width, double height)
  {
    double w0[] = {x0,         y0,          0.0};
    double w1[] = {x0 + width, y0,          0.0};
    double w2[] = {x0,         y0 + height, 0.0};

    setWorldExtent (w0, w1, w2);
  }
  
  

  /**
   * Return the world extent as specified by the application.
   * 
   * @return  The world extent as it was specified through setWorldExtent().
   */
  GWorldExtent getInitialWorldExtent()
  {
    return initialWorldExtent_;
  }


  
  /**
   * Return current world extent. The current world extent may differ the
   * initial world extent due to zooming and window resizing.
   * 
   * @return  Current world extent.
   */
  public GWorldExtent getWorldExtent()
  {
    return currentWorldExtent_;