camera.java

java 3d game jme 工程开发源代码

/*
 * Copyright (c) 2003-2009 jMonkeyEngine
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 * * Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 *
 * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
 *   may be used to endorse or promote products derived from this software
 *   without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package com.jme.renderer;

import java.io.Serializable;

import com.jme.bounding.BoundingVolume;
import com.jme.math.Quaternion;
import com.jme.math.Vector2f;
import com.jme.math.Vector3f;
import com.jme.util.export.Savable;

/**
 * <code>Camera</code> defines an interface that encapsulates viewport
 * management. Provided are convenience methods for setting up the view port and
 * the camera model. The frustum is also maintained here to allow for easy
 * frustum culling.
 *
 * @author Mark Powell
 * @author Gregg Patton
 */
public interface Camera extends Serializable, Savable {

    public enum FrustumIntersect {
        /**
         * defines a constant assigned to spatials that are completely outside
         * of this camera's view frustum.
         */
        Outside,
        /**
         * defines a constant assigned to spatials that are completely inside
         * the camera's view frustum.
         */
        Inside,
        /**
         * defines a constant assigned to spatials that are intersecting one of
         * the six planes that define the view frustum.
         */
        Intersects;
    }

    /**
     * <code>getLocation</code> returns the position of the camera.
     *
     * @return the position of the camera.
     */
    Vector3f getLocation();

    /**
     * <code>getDirection</code> returns the direction the camera is facing.
     *
     * @return the direction this camera object is facing.
     */
    Vector3f getDirection();

    /**
     * <code>getLeft</code> returns the left axis of the camera.
     *
     * @return the left axis of this camera object.
     */
    Vector3f getLeft();

    /**
     * <code>getUp</code> returns the up axis of the camera.
     *
     * @return the up axis of this camera object.
     */
    Vector3f getUp();

    /**
     * <code>setLocation</code> the position of the camera.
     *
     * @param location the position of the camera.
     */
    void setLocation( Vector3f location );

    /**
     * <code>setDirection</code> sets the direction the camera is facing.
     *
     * @param direction the new direction of the camera.
     */
    void setDirection( Vector3f direction );

    /**
     * <code>setLeft</code> sets the left axis of the camera.
     *
     * @param left the new left axis of the camera.
     */
    void setLeft( Vector3f left );

    /**
     * <code>setUp</code> sets the up axis of the camera.
     *
     * @param up the new up axis of the camera.
     */
    void setUp( Vector3f up );

    /**
     * <code>setAxes</code> sets the axes that define the camera's
     * orientation.
     *
     * @param left      the new left axis of the camera.
     * @param up        the new up axis of the camera.
     * @param direction the new direction of the camera.
     */
    void setAxes( Vector3f left, Vector3f up, Vector3f direction );

    /**
     * <code>setAxes</code> sets the camera's orientation via a rotational
     * matrix.
     *
     * @param axes the matrix that defines the camera orientation.
     */
    void setAxes( Quaternion axes );

    /**
     * <code>setFrustum</code> defines the frustum planes of the camera. This
     * frustum is defined by a six-sided box.
     *
     * @param near   the frustum plane closest to the eye point.
     * @param far    the frustum plane furthest from the eye point.
     * @param left   the frustum plane left of the eye point.
     * @param right  the frustum plane right of the eye point.
     * @param top    the frustum plane above the eye point.
     * @param bottom the frustum plane below the eye point.
     */
    void setFrustum( float near, float far, float left, float right,
                            float top, float bottom );

    /**
     * <code>setFrustumPerspective</code> defines the frustum for the camera.  This
     * frustum is defined by a viewing angle, aspect ratio, and near/far planes
     *
     * @param fovY   Frame of view angle along the Y.
     * @param aspect Width:Height ratio
     * @param near   Near view plane distance
     * @param far    Far view plane distance
     */
    void setFrustumPerspective( float fovY, float aspect, float near, float far );

    /**
     * <code>getFrustumBottom</code> returns the value of the bottom frustum
     * plane.
     *
     * @return the value of the bottom frustum plane.
     */
    float getFrustumBottom();

    /**
     * <code>setFrustumBottom</code> sets the value of the bottom frustum
     * plane.
     *
     * @param frustumBottom the value of the bottom frustum plane.
     */
    void setFrustumBottom( float frustumBottom );

    /**
     * <code>getFrustumFar</code> gets the value of the far frustum plane.
     *
     * @return the value of the far frustum plane.
     */
    float getFrustumFar();

    /**
     * <code>setFrustumFar</code> sets the value of the far frustum plane.
     *
     * @param frustumFar the value of the far frustum plane.
     */
    void setFrustumFar( float frustumFar );

    /**
     * <code>getFrustumLeft</code> gets the value of the left frustum plane.
     *
     * @return the value of the left frustum plane.
     */
    float getFrustumLeft();

    /**
     * <code>setFrustumLeft</code> sets the value of the left frustum plane.
     *
     * @param frustumLeft the value of the left frustum plane.
     */
    void setFrustumLeft( float frustumLeft );

    /**
     * <code>getFrustumNear</code> gets the value of the near frustum plane.
     *
     * @return the value of the near frustum plane.
     */
    float getFrustumNear();

    /**
     * <code>setFrustumNear</code> sets the value of the near frustum plane.
     *
     * @param frustumNear the value of the near frustum plane.
     */
    void setFrustumNear( float frustumNear );

    /**
     * <code>getFrustumRight</code> gets the value of the right frustum plane.
     *
     * @return frustumRight the value of the right frustum plane.
     */
    float getFrustumRight();

    /**
     * <code>setFrustumRight</code> sets the value of the right frustum plane.
     *
     * @param frustumRight the value of the right frustum plane.
     */
    void setFrustumRight( float frustumRight );

    /**