view.java

来自「world wind java sdk 源码」· Java 代码 · 共 417 行 · 第 1/2 页

/*
Copyright (C) 2001, 2006 United States Government as represented by
the Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
*/
package gov.nasa.worldwind;

import gov.nasa.worldwind.geom.*;
import gov.nasa.worldwind.render.DrawContext;

/**
 * The <code>View</code> interface provides a coordinate transformation from model coordinates to eye
 * coordinates. This follows the OpenGL convention of a left-handed coordinate system with the origin at the eye point
 * and looking down the negative Z axis. <code>View</code> also provides a transformation from eye coordinates to
 * screen coordinates, following the OpenGL convention of an origin in the lower left hand screen corner.
 * <p>
 * Most of the accessor and computation methods on <code>View</code> will use viewing state computed
 * in the last call to {@link #apply}.
 * <p>
 * The following methods return state values <i>updated in the most recent call to apply</i>.
 * <code>
 * <ul>
 * <li>getEyePosition</li>
 * <li>getEyePoint</li>
 * <li>getUpVector</li>
 * <li>getForwardVector</li>
 * <li>getModelviewMatrix</li>
 * <li>getViewport</li>
 * <li>getFrustum</li>
 * <li>getFrustumInModelCoordinates</li>
 * <li>getProjectionMatrix</li>
 * </code>
 * </ul>
 * <p>
 * The following methods return computed values using state that was updated in the most recent call to
 * <code>apply</code>.
 * <code>
 * <ul>
 * <li>project</li>
 * <li>unproject</li>
 * <li>computeRayFromScreenPoint</li>
 * <li>computePositionFromScreenPoint</li>
 * <li>computePixelSizeAtDistance</li>
 * <li>computeHorizonDistance</li> 
 * </ul>
 * </code>
 *
 * @author Paul Collins
 * @version $Id: View.java 8811 2009-02-10 21:43:53Z dcollins $
 * @see ViewStateIterator
 * @see gov.nasa.worldwind.view.OrbitView
 */
public interface View extends WWObject, Restorable
{
    /**
     * Returns whether the this <code>View</code> will detect collisions with other objects,
     * such as the surface geometry. If true, implementations may also automatically
     * resolve any detected collisions.
     *
     * @return <code>true</code> If this <code>View</code> will detect collisions; <code>false</code> otherwise.
     */
    boolean isDetectCollisions();

    /**
     * Sets whether or not this <code>View</code> will detect collisions with other objects,
     * such as the surface geometry. If <code>detectCollisions</code> is true, implementations may also automatically
     * resolve any detected collisions.
     *
     * @param detectCollisions If <code>true</code>, this <code>View</code> will resolve collisions; otherwise this
     *                          <code>View</code> will ignore collisions.
     */
    void setDetectCollisions(boolean detectCollisions);

    /**
     * Returns whether or not a collision has occurred since the last call to <code>hadCollisions</code>.
     * If {@link #isDetectCollisions} is false, collisions will not be detected and
     * <code>hadCollisions</code> will always return false.
     *
     * @return <code>true</code> if a collision has occurred since the last call; <code>false</code> otherwise.
     */
    boolean hadCollisions();

    final String VIEW_STOPPED = "gov.nasa.worldwind.View.ViewStopped";

    /**
     * Stops any movement associated with this <code>View</code>. This will stop any currently active
     * <code>ViewStateIterators</code> on this <code>View</code>.
     */
    void stopMovement();
    
    /**
     * Returns the location of the eye in geographic coordinates.
     * This value is computed in the most recent call to <code>apply</code>.
     *
     * @return Position of the eye.
     */
    Position getEyePosition();

    /**
     * Sets the location of the eye in geographic coordinates.
     * The implementation may interpret this command in whatever way it chooses,
     * so long as the eye is placed at the specified <code>eyePosition</code>.
     *
     * @param eyePosition Position of the eye.
     * @throws IllegalArgumentException If <code>eyePosition</code> is null.
     */
    void setEyePosition(Position eyePosition);

    /**
     * Returns the most up-to-date location of the eye in geographic coordintes.
     * Unlike {@link #getEyePosition} and {@link #getEyePoint},
     * getCurrentEyePosition will return the View's immediate position.
     *
     * @return Position of the eye.
     */
    Position getCurrentEyePosition();

    /**
     * Sets the location of the eye, and the center of the screen in geographic coordinates.
     * The implementation may interpret this command in whatever way it choooses,
     * so long as the eye is placed at the specified <code>eyePosition</code>,
     * and the center of the screen is the specified <code>centerPositoin</code>.
     * Specifically, implementations must determine what the up direction will be given
     * these parameters, and apply these parameters in a meaningful way.
     *
     * @param eyePosition Position of they eye.
     * @param centerPosition Position of the screen center.
     */
    void setOrientation(Position eyePosition, Position centerPosition);

    /**
     * Returns the location of the eye in cartesian coordinates.
     * This value is computed in the most recent call to <code>apply</code>.
     *
     * @return Vec4 of the eye.
     */
    Vec4 getEyePoint();

    /**
     * Returns the most up-to-date location of the eye in cartesian coordinates.
     * Unlike {@link #getEyePosition} and {@link #getEyePoint},
     * getCurrentEyePoint will return the View's immediate position.
     *
     * @return Vec4 of the eye.
     */
    Vec4 getCurrentEyePoint();

    /**
     * Returns the up axis in cartesian coordinates.
     * This value is computed in the most recent call to <code>apply</code>.
     *
     * @return Vec4 of the up axis.
     */
    Vec4 getUpVector();

    /**
     * Returns the forward axis in cartesian coordinates.
     * This value is computed in the most recent call to <code>apply</code>.
     *
     * @return Vec4 of the forward axis.
     */
    Vec4 getForwardVector();

    /**
     * Returns the modelview matrix. The modelview matrix transforms model coordinates to eye
     * coordinates. This matrix is constructed using the model space translation and orientation specific to each
     * the implementation.
     * This value is computed in the most recent call to <code>apply</code>.
     *
     * @return the current model-view matrix.
     */
    Matrix getModelviewMatrix();

    /**
     * Returns the horizontal field-of-view angle (the angle of visibility), or null
     * if the implementation does not support a field-of-view.
     *
     * @return Angle of the horizontal field-of-view, or null if none exists.
     */
    Angle getFieldOfView();

    /**
     * Sets the horiziontal field-of-view angle (the angle of visibillity) to the specified <code>fieldOfView</code>.
     * This may be ignored if the implementation that do not support a field-of-view.
     *
     * @param fieldOfView the horizontal field-of-view angle.
     * @throws IllegalArgumentException If the implementation supports field-of-view, and
     *                                  <code>fieldOfView</code> is null.
     */
    void setFieldOfView(Angle fieldOfView);

    /**
     * Returns the bounds (x, y, width, height) of the viewport. The implementation will configure itself
     * to render in this viewport.
     * This value is computed in the most recent call to <code>apply</code>.
     *
     * @return the Rectangle of the viewport.
     */
    java.awt.Rectangle getViewport();

    /**
     * Returns the near clipping plane distance, in eye coordinates.
     * If the near clipping plane is auto-configured by the View, this will still return the value last specified
     * by the caller.
     * To get the auto-configured value, see {@link #getAutoNearClipDistance}.
     *
     * @return near clipping plane distance, in eye coordinates.
     */
    double getNearClipDistance();