view.java

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

    /**
     * Sets the near clipping plane distance, in eye coordinates.
     * Implementations may restrict the range of valid distances.
     * When the caller specifies an invalid distance, implementations may interpret
     * this as an indicator to auto-configure the near clipping distance.
     * Otherwise, specifying an invalid distance will cause an IllegalArgumentException to be thrown.
     *
     * @param distance the near clipping plane distance.
     * @throws IllegalArgumentException if <code>distance</code> is not valid, and the implementation does not
     *                                  specially treat invalid values.
     */
    void setNearClipDistance(double distance);

    /**
     * Returns the far clipping plane distance, in eye coordinates.
     * If the far 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 #getAutoFarClipDistance}
     *
     * @return far clipping plane distance, in eye coordinates.
     */
    double getFarClipDistance();

    /**
     * Sets the far clipping plane distance, in eye coordinates.
     * Implementations may restrict the range of valid distances.
     * When the caller specifies an invalid distance, implementations may interpret
     * this as an indicator to auto-configure the far clipping distance.
     * Otherwise, specifying an invalid distance will cause an IllegalArgumentException to be thrown.
     *
     * @param distance the far clipping plane distance.
     * @throws IllegalArgumentException if <code>distance</code> is not valid, and the implementation does not
     *                                  specially treat invalid values.
     */
    void setFarClipDistance(double distance);

    /**
     * Returns the auto-configured near clipping plane distance, in eye coordinates.
     * The distance is implementation dependent, and should be based on the View's current position and orientation.
     *
     * @return auto-configured near clipping plane distance.
     */
    double getAutoNearClipDistance();

    /**
     * Returns the auto-configured far clipping plane distance, in eye coordinates.
     * The distance is implementation dependent, and should be based on the View's current position and orientation.
     *
     * @return auto-configured far clipping plane distance.
     */
    double getAutoFarClipDistance();

    /**
     * Returns the viewing <code>Frustum</code> in eye coordinates. The <code>Frustum</code> is the portion
     * of viewable space defined by three sets of parallel 'clipping' planes.
     * This value is computed in the most recent call to <code>apply</code>.
     *
     * @return viewing Frustum in eye coordinates.
     */
    Frustum getFrustum();

    /**
     * Returns the viewing <code>Frustum</code> in model coordinates. Model coordinate frustums are useful for
     * performing visibility tests against world geometry. This frustum has the same shape as the frustum returned
     * in <code>getFrustum</code>, but it has been transformed into model space.
     * This value is computed in the most recent call to <code>apply</code>.
     *
     * @return viewing Frustum in model coordinates.
     */
    Frustum getFrustumInModelCoordinates();

    /**
     * Gets the projection matrix. The projection matrix transforms eye coordinates to screen
     * coordinates. This matrix is constructed using the projection parameters specific to each implementation of
     * <code>View</code>. The method {@link #getFrustum} returns the geometry corresponding to this matrix.
     * This value is computed in the most recent call to <code>apply</code>.
     *
     * @return the current projection matrix.
     */
    Matrix getProjectionMatrix();

    /**
     * Calculates and applies this <code>View's</code> internal state to the graphics context in
     * the specified <code>dc</code>.
     * All subsequently rendered objects use this new state. Upon return, the OpenGL graphics context reflects the
     * values of this view, as do any computed values of the view, such as the modelview matrix, projection matrix and
     * viewing frustum.
     *
     * @param dc the current World Wind DrawContext on which <code>View</code> will apply its state.
     * @throws IllegalArgumentException If <code>dc</code> is null, or if the <code>Globe</code> or <code>GL</code>
     *                                  instances in <code>dc</code> are null.
     */
    void apply(DrawContext dc);

    /**
     * Maps a <code>Point</code> in model (cartesian) coordinates to a <code>Point</code> in screen coordinates. The
     * returned x and y are relative to the lower left hand screen corner, while z is the screen depth-coordinate. If
     * the model point cannot be sucessfully mapped, this will return null.
     *
     * @param modelPoint the model coordinate <code>Point</code> to project.
     * @return the mapped screen coordinate <code>Point</code>.
     * @throws IllegalArgumentException if <code>modelPoint</code> is null.
     */
    Vec4 project(Vec4 modelPoint);

    /**
     * Maps a <code>Point</code> in screen coordinates to a <code>Point</code> in model coordinates. The input x and y
     * are  relative to the lower left hand screen corner, while z is the screen depth-coordinate.  If the screen point
     * cannot be sucessfully mapped, this will return null.
     *
     * @param windowPoint the window coordinate <code>Point</code> to project.
     * @return the mapped screen coordinate <code>Point</code>.
     * @throws IllegalArgumentException if <code>windowPoint</code> is null.
     */
    Vec4 unProject(Vec4 windowPoint);

    /**
     * Defines and applies a new model-view matrix in which the world origin is located at <code>referenceCenter</code>.
     * Geometry rendered after a call to <code>pushReferenceCenter</code> should be transformed with respect to
     * <code>referenceCenter</code>, rather than the canonical origin (0, 0, 0). Calls to
     * <code>pushReferenceCenter</code> must be followed by {@link #popReferenceCenter} after rendering is complete.
     * Note that calls to {@link #getModelviewMatrix} will not return reference-center model-view matrix, but the
     * original matrix.
     *
     * @param dc              the current World Wind drawing context on which new model-view state will be applied.
     * @param referenceCenter the location to become the new world origin.
     * @return a new model-view matrix with origin is at <code>referenceCenter</code>, or null if this method failed.
     * @throws IllegalArgumentException if <code>referenceCenter</code> is null, if <code>dc</code> is null, or if the
     *                                  <code>Globe</code> or <code>GL</code> instances in <code>dc</code> are null.
     */
    Matrix pushReferenceCenter(DrawContext dc, Vec4 referenceCenter);

    /**
     * Removes the model-view matrix on top of the matrix stack, and restores the original matrix.
     *
     * @param dc the current World Wind drawing context on which the original matrix will be restored.
     * @throws IllegalArgumentException if <code>dc</code> is null, or if the <code>Globe</code> or <code>GL</code>
     *                                  instances in <code>dc</code> are null.
     */
    void popReferenceCenter(DrawContext dc);

    /**
     * Iterates over <code>View</code> state changes in <code>ViewStateIterator</code> and applies them to the
     * <code>View</code>. The <code>View</code> will automatically refresh and request state from
     * <code>viewStateIterator</code> until the iteration is complete, or <code>View</code> has been stopped by invoking
     * {@link #stopStateIterators}.
     *
     * @param viewStateIterator the <code>ViewStateIterator</code> to iterate over.
     */
    void applyStateIterator(ViewStateIterator viewStateIterator);

    /**
     * Returns true when <code>View</code> is actively iterating over an instance of <code>ViewStateIterator</code>.
     *
     * @return true when iterating over <code>ViewStateIterator</code>; false otherwise.
     */
    boolean hasStateIterator();

    /**
     * Immediately stops all active iteration over <code>ViewStateIterator</code>.
     */
    void stopStateIterators();

    /**
     * Computes a line, in model coordinates, originating from the eye point, and passing throught the point contained
     * by (x, y) on the <code>View's</code> projection plane (or after projection into model space).
     *
     * @param x the horizontal coordinate originating from the left side of <code>View's</code> projection plane.
     * @param y the vertical coordinate originating from the top of <code>View's</code> projection plane.
     * @return a line beginning at the <code>View's</code> eye point and passing throught (x, y) transformed into model
     *         space.
     */
    Line computeRayFromScreenPoint(double x, double y);

    /**
     * Computes the intersection of a line originating from the eye point (passing throught (x, y)) with the last
     * rendered <code>SectorGeometry</code>, or the last analytical <code>Globe</code> if no rendered geometry exists.
     *
     * @param x the horizontal coordinate originating from the left side of <code>View's</code> projection plane.
     * @param y the vertical coordinate originating from the top of <code>View's</code> projection plane.
     * @return the point on the surface in polar coordiantes.
     */
    Position computePositionFromScreenPoint(double x, double y);

    /**
     * Computes the dimension (in meters) that a screen pixel would cover at a given distance from the eye point
     * (also in meters). The distance is interpreted as the linear distance between the eye point and the world point
     * in question. This computation assumes that pixels dimensions are square, and therefore returns a single
     * dimension.
     *
     * @param distance the distance in meters from the eye point. This value must be positive but is otherwise
     *                 unbounded.
     *
     * @return the dimension of a pixel in meters at the given distance.
     * @throws IllegalArgumentException if <code>distance</code> is negative.
     */
    double computePixelSizeAtDistance(double distance);

    /**
     * Gets the distance from the <code>View's</code> eye point to the horizon point on the last rendered
     * <code>Globe</code>.
     *
     * @return the distance from the eye point to the horizon.
     */
    double computeHorizonDistance();
}