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
33package com.jme3.terrain.heightmap;
34
35/**
36 *
37 * @author cghislai
38 */
39public 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