Home | History | Annotate | Download | only in heightmap 
      1 /*
      2  * Copyright (c) 2009-2010 jMonkeyEngine
      3  * All rights reserved.
      4  *
      5  * Redistribution and use in source and binary forms, with or without
      6  * modification, are permitted provided that the following conditions are
      7  * met:
      8  *
      9  * * Redistributions of source code must retain the above copyright
     10  *   notice, this list of conditions and the following disclaimer.
     11  *
     12  * * Redistributions in binary form must reproduce the above copyright
     13  *   notice, this list of conditions and the following disclaimer in the
     14  *   documentation and/or other materials provided with the distribution.
     15  *
     16  * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
     17  *   may be used to endorse or promote products derived from this software
     18  *   without specific prior written permission.
     19  *
     20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
     22  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
     23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
     24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     27  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
     28  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
     29  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     30  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     31  */
     32 
     33 package com.jme3.terrain.heightmap;
     34 
     35 /**
     36  *
     37  * @author cghislai
     38  */
     39 public interface HeightMap {
     40 
     41     /**
     42      * <code>getHeightMap</code> returns the entire grid of height data.
     43      *
     44      * @return the grid of height data.
     45      */
     46     float[] getHeightMap();
     47 
     48     float[] getScaledHeightMap();
     49 
     50     /**
     51      * <code>getInterpolatedHeight</code> returns the height of a point that
     52      * does not fall directly on the height posts.
     53      *
     54      * @param x
     55      * the x coordinate of the point.
     56      * @param z
     57      * the y coordinate of the point.
     58      * @return the interpolated height at this point.
     59      */
     60     float getInterpolatedHeight(float x, float z);
     61 
     62     /**
     63      * <code>getScaledHeightAtPoint</code> returns the scaled value at the
     64      * point provided.
     65      *
     66      * @param x
     67      * the x (east/west) coordinate.
     68      * @param z
     69      * the z (north/south) coordinate.
     70      * @return the scaled value at (x, z).
     71      */
     72     float getScaledHeightAtPoint(int x, int z);
     73 
     74     /**
     75      * <code>getSize</code> returns the size of one side the height map. Where
     76      * the area of the height map is size x size.
     77      *
     78      * @return the size of a single side.
     79      */
     80     int getSize();
     81 
     82     /**
     83      * <code>getTrueHeightAtPoint</code> returns the non-scaled value at the
     84      * point provided.
     85      *
     86      * @param x
     87      * the x (east/west) coordinate.
     88      * @param z
     89      * the z (north/south) coordinate.
     90      * @return the value at (x,z).
     91      */
     92     float getTrueHeightAtPoint(int x, int z);
     93 
     94     /**
     95      * <code>load</code> populates the height map data. This is dependent on
     96      * the subclass's implementation.
     97      *
     98      * @return true if the load was successful, false otherwise.
     99      */
    100     boolean load();
    101 
    102     /**
    103      * <code>setHeightAtPoint</code> sets the height value for a given
    104      * coordinate. It is recommended that the height value be within the 0 - 255
    105      * range.
    106      *
    107      * @param height
    108      * the new height for the coordinate.
    109      * @param x
    110      * the x (east/west) coordinate.
    111      * @param z
    112      * the z (north/south) coordinate.
    113      */
    114     void setHeightAtPoint(float height, int x, int z);
    115 
    116     /**
    117      * <code>setHeightScale</code> sets the scale of the height values.
    118      * Typically, the height is a little too extreme and should be scaled to a
    119      * smaller value (i.e. 0.25), to produce cleaner slopes.
    120      *
    121      * @param scale
    122      * the scale to multiply height values by.
    123      */
    124     void setHeightScale(float scale);
    125 
    126     /**
    127      * <code>setFilter</code> sets the erosion value for the filter. This
    128      * value must be between 0 and 1, where 0.2 - 0.4 produces arguably the best
    129      * results.
    130      *
    131      * @param filter
    132      * the erosion value.
    133      * @throws Exception
    134      * @throws JmeException
    135      * if filter is less than 0 or greater than 1.
    136      */
    137     void setMagnificationFilter(float filter) throws Exception;
    138 
    139     /**
    140      * <code>setSize</code> sets the size of the terrain where the area is
    141      * size x size.
    142      *
    143      * @param size
    144      * the new size of the terrain.
    145      * @throws Exception
    146      *
    147      * @throws JmeException
    148      * if the size is less than or equal to zero.
    149      */
    150     void setSize(int size) throws Exception;
    151 
    152     /**
    153      * <code>unloadHeightMap</code> clears the data of the height map. This
    154      * insures it is ready for reloading.
    155      */
    156     void unloadHeightMap();
    157 
    158 }
    159