texture.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.image;

import java.io.IOException;

import com.jme.math.FastMath;
import com.jme.math.Matrix4f;
import com.jme.math.Quaternion;
import com.jme.math.Vector3f;
import com.jme.renderer.ColorRGBA;
import com.jme.util.TextureKey;
import com.jme.util.TextureManager;
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;

/**
 * <code>Texture</code> defines a texture object to be used to display an
 * image on a piece of geometry. The image to be displayed is defined by the
 * <code>Image</code> class. All attributes required for texture mapping are
 * contained within this class. This includes mipmapping if desired,
 * magnificationFilter options, apply options and correction options. Default
 * values are as follows: minificationFilter - NearestNeighborNoMipMaps,
 * magnificationFilter - NearestNeighbor, wrap - EdgeClamp on S,T and R, apply -
 * Modulate, enivoronment - None.
 * 
 * @see com.jme.image.Image
 * @author Mark Powell
 * @author Joshua Slack
 * @version $Id: Texture.java,v 1.44 2007/10/19 13:21:41 nca Exp $
 */
public abstract class Texture implements Savable {
    private static final long serialVersionUID = -3642148179543729674L;

    public static boolean DEFAULT_STORE_TEXTURE = false;

    public enum Type {
        /**
         * One dimensional texture. (basically a line)
         */
        OneDimensional,
        /**
         * Two dimensional texture (default). A rectangle.
         */
        TwoDimensional,
        /**
         * Three dimensional texture. (A cube)
         */
        ThreeDimensional,
        /**
         * A set of 6 TwoDimensional textures arranged as faces of a cube facing
         * inwards.
         */
        CubeMap;
    }
    
    public enum MinificationFilter {

        /**
         * Nearest neighbor interpolation is the fastest and crudest filtering
         * method - it simply uses the color of the texel closest to the pixel
         * center for the pixel color. While fast, this results in aliasing and
         * shimmering during minification. (GL equivalent: GL_NEAREST)
         */
        NearestNeighborNoMipMaps(false),

        /**
         * In this method the four nearest texels to the pixel center are
         * sampled (at texture level 0), and their colors are combined by
         * weighted averages. Though smoother, without mipmaps it suffers the
         * same aliasing and shimmering problems as nearest
         * NearestNeighborNoMipMaps. (GL equivalent: GL_LINEAR)
         */
        BilinearNoMipMaps(false),

        /**
         * Same as NearestNeighborNoMipMaps except that instead of using samples
         * from texture level 0, the closest mipmap level is chosen based on
         * distance. This reduces the aliasing and shimmering significantly, but
         * does not help with blockiness. (GL equivalent:
         * GL_NEAREST_MIPMAP_NEAREST)
         */
        NearestNeighborNearestMipMap(true),

        /**
         * Same as BilinearNoMipMaps except that instead of using samples from
         * texture level 0, the closest mipmap level is chosen based on
         * distance. By using mipmapping we avoid the aliasing and shimmering
         * problems of BilinearNoMipMaps. (GL equivalent:
         * GL_LINEAR_MIPMAP_NEAREST)
         */
        BilinearNearestMipMap(true),

        /**
         * Similar to NearestNeighborNoMipMaps except that instead of using
         * samples from texture level 0, a sample is chosen from each of the
         * closest (by distance) two mipmap levels. A weighted average of these
         * two samples is returned. (GL equivalent: GL_NEAREST_MIPMAP_LINEAR)
         */
        NearestNeighborLinearMipMap(true),

        /**
         * Trilinear filtering is a remedy to a common artifact seen in
         * mipmapped bilinearly filtered images: an abrupt and very noticeable
         * change in quality at boundaries where the renderer switches from one
         * mipmap level to the next. Trilinear filtering solves this by doing a
         * texture lookup and bilinear filtering on the two closest mipmap
         * levels (one higher and one lower quality), and then linearly
         * interpolating the results. This results in a smooth degradation of
         * texture quality as distance from the viewer increases, rather than a
         * series of sudden drops. Of course, closer than Level 0 there is only
         * one mipmap level available, and the algorithm reverts to bilinear
         * filtering (GL equivalent: GL_LINEAR_MIPMAP_LINEAR)
         */
        Trilinear(true);

        private boolean usesMipMapLevels;

        private MinificationFilter(boolean usesMipMapLevels) {
            this.usesMipMapLevels = usesMipMapLevels;
        }

        public boolean usesMipMapLevels() {
            return usesMipMapLevels;
        }
    }

    public enum MagnificationFilter {

        /**
         * Nearest neighbor interpolation is the fastest and crudest filtering
         * mode - it simply uses the color of the texel closest to the pixel
         * center for the pixel color. While fast, this results in texture
         * 'blockiness' during magnification. (GL equivalent: GL_NEAREST)
         */
        NearestNeighbor,

        /**
         * In this mode the four nearest texels to the pixel center are sampled
         * (at the closest mipmap level), and their colors are combined by
         * weighted average according to distance. This removes the 'blockiness'
         * seen during magnification, as there is now a smooth gradient of color
         * change from one texel to the next, instead of an abrupt jump as the
         * pixel center crosses the texel boundary. (GL equivalent: GL_LINEAR)
         */
        Bilinear;

    }

    public enum WrapMode {
        /**
         * Only the fractional portion of the coordinate is considered.
         */
        Repeat,
        /**
         * Only the fractional portion of the coordinate is considered, but if
         * the integer portion is odd, we'll use 1 - the fractional portion.
         * (Introduced around OpenGL1.4) Falls back on Repeat if not supported.
         */
        MirroredRepeat,
        /**
         * coordinate will be clamped to [0,1]
         */
        Clamp,
        /**
         * mirrors and clamps the texture coordinate, where mirroring and
         * clamping a value f computes:
         * <code>mirrorClamp(f) = min(1, max(1/(2*N),
         * abs(f)))</code> where N
         * is the size of the one-, two-, or three-dimensional texture image in
         * the direction of wrapping. (Introduced after OpenGL1.4) Falls back on
         * Clamp if not supported.
         */
        MirrorClamp,
        /**
         * coordinate will be clamped to the range [-1/(2N), 1 + 1/(2N)] where N
         * is the size of the texture in the direction of clamping. Falls back
         * on Clamp if not supported.
         */
        BorderClamp,
        /**
         * Wrap mode MIRROR_CLAMP_TO_BORDER_EXT mirrors and clamps to border the
         * texture coordinate, where mirroring and clamping to border a value f
         * computes:
         * <code>mirrorClampToBorder(f) = min(1+1/(2*N), max(1/(2*N), abs(f)))</code>
         * where N is the size of the one-, two-, or three-dimensional texture
         * image in the direction of wrapping." (Introduced after OpenGL1.4)
         * Falls back on BorderClamp if not supported.
         */
        MirrorBorderClamp,
        /**
         * coordinate will be clamped to the range [1/(2N), 1 - 1/(2N)] where N
         * is the size of the texture in the direction of clamping. Falls back
         * on Clamp if not supported.
         */
        EdgeClamp,
        /**
         * mirrors and clamps to edge the texture coordinate, where mirroring
         * and clamping to edge a value f computes:
         * <code>mirrorClampToEdge(f) = min(1-1/(2*N), max(1/(2*N), abs(f)))</code>
         * where N is the size of the one-, two-, or three-dimensional texture
         * image in the direction of wrapping. (Introduced after OpenGL1.4)
         * Falls back on EdgeClamp if not supported.
         */
        MirrorEdgeClamp;
    }

    public enum WrapAxis {
        /**
         * S wrapping (u or "horizontal" wrap)
         */
        S,
        /**
         * T wrapping (v or "vertical" wrap)
         */
        T,
        /**
         * R wrapping (w or "depth" wrap)
         */
        R;
    }

    public enum ApplyMode {
        /**
         * Apply modifier that replaces the previous pixel color with the
         * texture color.
         */
        Replace,
        /**
         * Apply modifier that replaces the color values of the pixel but makes
         * use of the alpha values.
         */
        Decal,
        /**
         * Apply modifier multiples the color of the pixel with the texture
         * color.
         */
        Modulate,
        /**
         * Apply modifier that interpolates the color of the pixel with a blend
         * color using the texture color, such that the final color value is Cv =
         * (1 - Ct) * Cf + BlendColor * Ct Where Ct is the color of the texture
         * and Cf is the initial pixel color.
         */
        Blend,
        /**
         * Apply modifier combines two textures based on the combine parameters
         * set on this texture.
         */
        Combine,
        /**
         * Apply modifier adds two textures.
         */
        Add;
    }

    public enum EnvironmentalMapMode {
        /**
         * Use texture coordinates as they are. (Do not do texture coordinate
         * generation.)
         */
        None,
        /**
         * TODO: add documentation
         */
        EyeLinear,
        /**
         * TODO: add documentation
         */
        ObjectLinear,
        /**
         * TODO: add documentation
         */
        SphereMap,
        /**
         * TODO: add documentation
         */
        NormalMap,
        /**
         * TODO: add documentation
         */
        ReflectionMap;
    }

    public enum CombinerFunctionRGB {
        /** Arg0 */
        Replace,
        /** Arg0 * Arg1 */
        Modulate,
        /** Arg0 + Arg1 */
        Add,
        /** Arg0 + Arg1 - 0.5 */
        AddSigned,
        /** Arg0 * Arg2 + Arg1 * (1 - Arg2) */
        Interpolate,
        /** Arg0 - Arg1 */
        Subtract,
        /**
         * 4 * ((Arg0r - 0.5) * (Arg1r - 0.5) + (Arg0g - 0.5) * (Arg1g - 0.5) +
         * (Arg0b - 0.5) * (Arg1b - 0.5)) [ result placed in R,G,B ]
         */
        Dot3RGB,
        /**
         * 4 * ((Arg0r - 0.5) * (Arg1r - 0.5) + (Arg0g - 0.5) * (Arg1g - 0.5) +
         * (Arg0b - 0.5) * (Arg1b - 0.5)) [ result placed in R,G,B,A ]
         */
        Dot3RGBA;
    }

    public enum CombinerFunctionAlpha {
        /** Arg0 */
        Replace,
        /** Arg0 * Arg1 */
        Modulate,
        /** Arg0 + Arg1 */
        Add,
        /** Arg0 + Arg1 - 0.5 */
        AddSigned,
        /** Arg0 * Arg2 + Arg1 * (1 - Arg2) */
        Interpolate,
        /** Arg0 - Arg1 */
        Subtract;
    }

    public enum CombinerSource {
        /**
         * The incoming fragment color from the previous texture unit. When used
         * on texture unit 0, this is the same as using PrimaryColor.
         */
        Previous,
        /** The blend color set on this texture. */
        Constant,
        /** The incoming fragment color before any texturing is applied. */
        PrimaryColor,
        /** The current texture unit's bound texture. */
        CurrentTexture,
        /** The texture bound on texture unit 0. */
        TextureUnit0,
        /** The texture bound on texture unit 1. */
        TextureUnit1,
        /** The texture bound on texture unit 2. */
        TextureUnit2,
        /** The texture bound on texture unit 3. */
        TextureUnit3,
        /** The texture bound on texture unit 4. */
        TextureUnit4,
        /** The texture bound on texture unit 5. */
        TextureUnit5,
        /** The texture bound on texture unit 6. */
        TextureUnit6,
        /** The texture bound on texture unit 7. */
        TextureUnit7,
        /** The texture bound on texture unit 8. */
        TextureUnit8,
        /** The texture bound on texture unit 9. */
        TextureUnit9,
        /** The texture bound on texture unit 10. */
        TextureUnit10,
        /** The texture bound on texture unit 11. */
        TextureUnit11,
        /** The texture bound on texture unit 12. */
        TextureUnit12,
        /** The texture bound on texture unit 13. */
        TextureUnit13,
        /** The texture bound on texture unit 14. */
        TextureUnit14,
        /** The texture bound on texture unit 15. */