transformmatrix.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.math;

import java.io.IOException;
import java.io.Serializable;
import java.util.logging.Logger;

import com.jme.scene.Spatial;
import com.jme.system.JmeException;
import com.jme.util.export.InputCapsule;
import com.jme.util.export.JMEExporter;
import com.jme.util.export.JMEImporter;
import com.jme.util.export.OutputCapsule;
import com.jme.util.export.Savable;

/**
 * TransformMatrix holds a rotation (Matrix3f)  and translation (Vector3f) for point manipulation
 *
 * @author Jack Lindamood
 * @author Joshua Slack
 */
public class TransformMatrix  implements Serializable, Savable, Cloneable {
    private static final Logger logger = Logger.getLogger(TransformMatrix.class
            .getName());
    
    // TODO: Clean up and standardize this class's functionality
    private static final long serialVersionUID = 1L;

    private Matrix3f rot=new Matrix3f();
    private Vector3f translation=new Vector3f();
    private Vector3f scale=new Vector3f(1,1,1);

    /**
     * Constructor instantiates a new <code>TransformMatrix</code> that is set to the
     * identity matrix by default.
     *
     */
    public TransformMatrix() {
    }

    /**
     * Constructor instantiates a new <code>TransformMatrix</code> that is set to the
     * provided matrix. This constructor copies a given matrix. If the
     * provided matrix is null, the constructor sets the matrix to the
     * identity.
     * @param mat the matrix to copy.
     */
    public TransformMatrix(TransformMatrix mat) {
        set(mat);
    }

    /**
     * Constructor instantiates a new <code>TransformMatrix</code> that has rotation
     * and translation defined by its parameters
     * @param myRot The given rotation, as a <code>Quaternion</code>
     * @param myPos The given translation, as a <code>Vector3f</code>
     */
    public TransformMatrix(Quaternion myRot, Vector3f myPos) {
        rot.set(myRot);
        translation.set(myPos);
    }

    /**
     * <code>set</code> transfers the contents of a given matrix to this
     * matrix. If a null matrix is supplied, this matrix is set to the
     * identity matrix.
     * @param matrix the matrix to copy.
     */
    public void set(TransformMatrix matrix) {
        if (matrix == null) {
            loadIdentity();
        } else {
            rot.copy(matrix.rot);
            translation.set(matrix.translation);
            scale.set(matrix.scale);
        }
    }


    /**
     *
     * <code>set</code> defines the values of the matrix based on a supplied
     * <code>Quaternion</code>. It should be noted that all previous values
     * will be overridden.
     * @param quaternion the quaternion to create a rotational matrix from.
     */
    public void set(Quaternion quaternion) {
        rot.set(quaternion);
        translation.zero();
        scale.set(1,1,1);
    }

    /**
     * <code>loadIdentity</code> sets this matrix to the identity matrix,
     * namely all zeros with ones along the diagonal.
     *
     */
    public void loadIdentity() {
        rot.loadIdentity();
        translation.zero();
        scale.set(1,1,1);
    }

    /**
     * Multiplies every value in the matrix by a scalar
     * @param scalar
     */
    public void mult(float scalar) {
        rot.multLocal(scalar);
        translation.mult(scalar);
        scale.multLocal(scalar);
    }

    /**
     * <code>multLocal</code> multiplies this matrix with another matrix and stores
     * the result back in this, returning this.  if null is passed, nothing happens
     * This function changes this matrix to what the child would look like if this were applied as it's parent
     * @param child The matrix to multiply by
     * @param tempStore A temporary Vector3f object for this TransformMatrix to use during the calculation.
     * @return this matrix after multiplication
     */
    public TransformMatrix multLocal(TransformMatrix child,Vector3f tempStore){
        this.scale.multLocal(child.scale);
        this.translation.addLocal(rot.mult(child.translation,tempStore).multLocal(child.scale));
        this.rot.multLocal(child.rot);
        return this;
    }

    /**
     * Sets this transform to an interpolation between the start and end transforms.  Note that
     * this function isn't very efficient as it has to create 2 new Quaternions to do the
     * rotation interpolation
     * @param start Begining transform (delta=0)
     * @param end Ending transform (delta=1)
     * @param delta Value between 0.0 and 1.0 to show which side the transform leans towards
     */
    public void interpolateTransforms(TransformMatrix start,TransformMatrix end,float delta){
        this.translation.set(start.translation).interpolate(end.translation,delta);
        this.scale.set(start.scale).interpolate(end.scale,delta);
        Quaternion q1=new Quaternion(),q2=new Quaternion();
        start.getRotation(q1);
        end.getRotation(q2);
        q1.slerp(q2,delta);
        this.setRotationQuaternion(q1);
    }

    /**
     * Sets this transform to an interpolation between the start and end transforms.  Same as above but doesn't
     * create 2 new Quaternions
     * @param start Begining transform (delta=0)
     * @param end Ending transform (delta=1)
     * @param delta Value between 0.0 and 1.0 to show which side the transform leans towards
     * @param q1 A temporary Quaternion
     * @param q2 Another temporary Quaternion
     */
    public void interpolateTransforms(TransformMatrix start,TransformMatrix end,float delta,Quaternion q1,Quaternion q2){
        this.translation.set(start.translation).interpolate(end.translation,delta);
        this.scale.set(start.scale).interpolate(end.scale,delta);
        start.getRotation(q1);
        end.getRotation(q2);
        q1.slerp(q2,delta);
        this.setRotationQuaternion(q1);
    }


    /**
     * <code>mult</code> multiplies a normal about a transform matrix and
     * stores the result back in vec. The resulting vector is returned
     * with translational ignored.
     * @param vec the rotation normal.
     * @return The given Vector3f, after rotation
     */
    public Vector3f multNormal(Vector3f vec) {
        if (null == vec) {
            logger.warning("Source vector is null, null result returned.");
            return null;
        }
        return rot.multLocal(vec);
    }

    /**
     * <code>mult</code> multiplies a vector about a transform matrix. The
     * resulting vector is saved in vec and returned.
     * @param vec The point to rotate.
     * @return The rotated vector.
     */
    public Vector3f multPoint(Vector3f vec) {
        if (null == vec) {
            logger.warning("Source vector is null, null result returned.");
            return null;
        }
        return rot.multLocal(vec).multLocal(scale).addLocal(translation);
    }


    /**
     * Sets the rotation matrix to the given rotation matrix via a copy.  If null is supplied, the identity is set
     * @param rot The new rotation
     */
    public void setRotation(Matrix3f rot){
        this.rot.copy(rot);
    }

    /**
     * <code>setTranslation</code> will set the matrix's translation values.
     * @param transArray the new values for the translation.
     * @throws JmeException if translation is null or not size 3.
     */
    public void setTranslation(float[] transArray) {
        if (transArray == null || transArray.length != 3) {
            throw new JmeException("Translation size must be 3.");
        }
        translation.x = transArray[0];
        translation.y = transArray[1];
        translation.z = transArray[2];
    }

    /** <code>setTranslation</code> will copy the given Vector3f's values
     * into this Matrix's translational component