001/**
002 * GeomSSScene -- The public interface for the the GeomSS 3D scene.
003 *
004 * Copyright (C) 2009-2015, by Joseph A. Huwaldt. All rights reserved.
005 *
006 * This library is free software; you can redistribute it and/or modify it under the terms
007 * of the GNU Lesser General Public License as published by the Free Software Foundation;
008 * either version 2.1 of the License, or (at your option) any later version.
009 *
010 * This library is distributed in the hope that it will be useful, but WITHOUT ANY
011 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
012 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
013 *
014 * You should have received a copy of the GNU Lesser General Public License along with
015 * this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place -
016 * Suite 330, Boston, MA 02111-1307, USA. Or visit: http://www.gnu.org/licenses/lgpl.html
017 */
018package geomss;
019
020import geomss.geom.GeomElement;
021import geomss.geom.GeomList;
022import geomss.j3d.ProjectionPolicy;
023import geomss.j3d.RenderType;
024import geomss.j3d.SurfaceColorType;
025import jahuwaldt.js.param.Parameter;
026import java.awt.Color;
027import javax.measure.quantity.Length;
028
029/**
030 * The public interface for the GeomSS 3D scene that is intended to be accessed from the
031 * BeanShell scripting environment.
032 * 
033 * <p> Modified by: Joseph A. Huwaldt </p>
034 * 
035 * @author Joseph A. Huwaldt, Date: May 3, 2009
036 * @version September 4, 2015
037 */
038public interface GeomSSScene {
039
040    /**
041     * Draws the specified geometry element into the 3D scene without erasing the existing
042     * geometry. This is identical to <code>draw(newGeom, false);</code>.
043     *
044     * @param newGeom The new geometry to be displayed on the 3D canvas.
045     */
046    public void draw(GeomElement newGeom);
047
048    /**
049     * Draws the specified geometry element in the 3D scene.
050     *
051     * @param newGeom The new geometry to be displayed on the 3D canvas.
052     * @param erase   Set to <code>true</code> to erase the geometry currently displayed.
053     *                Set to <code>false</code> to add the new geometry to the existing
054     *                display.
055     */
056    public void draw(GeomElement newGeom, boolean erase);
057
058    /**
059     * Erases all the geometry from the 3D scene.
060     */
061    public void erase();
062
063    /**
064     * Erases the specified geometry from the 3D scene (if possible).
065     *
066     * @param geometry The specific geometry to be erased from the 3D scene.
067     */
068    public void erase(GeomElement geometry);
069
070    /**
071     * Centers the geometry in the display.
072     */
073    public void center();
074
075    /**
076     * Centers the geometry in the display and zooms until the geometry fills the display.
077     */
078    public void centerAndZoom();
079
080    /**
081     * Pick items from the scene by control-clicking with the mouse. Returns a list of
082     * selected items.
083     *
084     * @return A list of picked items.
085     */
086    public GeomList pick();
087
088    /**
089     * Sets a flag indicating that the geometry is mirrored about the XZ plane of
090     * symmetry.
091     *
092     * @param mirrored Set to <code>true</code> to turn on mirroring.
093     */
094    public void setMirrored(boolean mirrored);
095
096    /**
097     * @return a flag indicating if the geometry display is currently mirrored about the
098     *         XZ plane of symmetry or not.
099     */
100    public boolean isMirrored();
101
102    /**
103     * Sets {@link geomss.j3d.RenderType rendering type} for all the objects currently
104     * displayed in the entire scene.
105     *
106     * @param type The render type to set.
107     */
108    public void setRenderType(RenderType type);
109
110    /**
111     * @return the {@link geomss.j3d.RenderType rendering type} for the 1st item in the
112     *         scene.
113     */
114    public RenderType getRenderType();
115
116    /**
117     * Sets the color used when rendering points.
118     *
119     * @param color The color to use for points drawn in the future.
120     */
121    public void setPointColor(Color color);
122
123    /**
124     * Returns the color used when rendering points.
125     *
126     * @return the color used when rendering points.
127     */
128    public Color getPointColor();
129
130    /**
131     * Set the size that Point objects are rendered in pixels.
132     *
133     * @param pixels The number of pixels to use when displaying points.
134     */
135    public void setPointSize(int pixels);
136
137    /**
138     * @return the size that Point objects are rendered in pixels.
139     */
140    public int getPointSize();
141
142    /**
143     * Sets the color used when rendering curves and lines.
144     *
145     * @param color The color to use when rendering lines in the future.
146     */
147    public void setLineColor(Color color);
148
149    /**
150     * @return the color used when rendering curves and lines.
151     */
152    public Color getLineColor();
153
154    /**
155     * Set the width that line/curve objects are rendered in pixels.
156     *
157     * @param pixels The number of pixels line-width to use when rendering lines.
158     */
159    public void setLineWidth(int pixels);
160
161    /**
162     * @return the width that line/curve objects are rendered in pixels.
163     */
164    public int getLineWidth();
165
166    /**
167     * Set the tolerance used when drawing parametric objects such as curves and surfaces.
168     * This tolerance is used when determining how to subdivide parametric objects for
169     * rendering. If the input value is <code>null</code> or equal to <code>0</code>, it
170     * will be silently ignored.
171     *
172     * @param tol The tolerance used when drawing parametric objects such as curves and
173     *            surfaces.
174     */
175    public void setDrawTolerance(Parameter<Length> tol);
176
177    /**
178     * Return the tolerance used when drawing parametric objects such as curves and
179     * surfaces. This tolerance is used when determining how to subdivide parametric
180     * objects for rendering.
181     *
182     * @return The tolerance used when drawing parametric objects such as curves and
183     *         surfaces.
184     */
185    public Parameter<Length> getDrawTolerance();
186
187    /**
188     * @return the current projection policy for this scene.
189     */
190    public ProjectionPolicy getProjectionPolicy();
191
192    /**
193     * Sets the projection policy for this scene. This specifies the type of projection
194     * transform that will be generated. A value of PARALLEL_PROJECTION specifies that a
195     * parallel projection transform is generated. A value of PERSPECTIVE_PROJECTION
196     * specifies that a perspective projection transform is generated.
197     *
198     * @param policy The new projection policy, one of PARALLEL_PROJECTION or
199     *               PERSPECTIVE_PROJECTION.
200     */
201    public void setProjectionPolicy(ProjectionPolicy policy);
202
203    /**
204     * Set the color (of the specified type) used to render surfaces and point-arrays.
205     *
206     * @param colorType The aspect or type of the surface color that is being set.
207     * @param color     The color to use for the specified type of surface color. The
208     *                  alpha is ignored.
209     * @see #setSurfaceAlpha
210     */
211    public void setSurfaceColor(SurfaceColorType colorType, Color color);
212
213    /**
214     * Get the color (of the specified type) used to render surfaces and point-arrays.
215     *
216     * @param colorType The aspect or type of the surface color that is being set.
217     * @return The color used for the specified type of surface color. Alpha is ignored.
218     * @see #getSurfaceAlpha
219     */
220    public Color getSurfaceColor(SurfaceColorType colorType);
221
222    /**
223     * Set the alpha or transparency used to render surfaces and point-arrays.
224     *
225     * @param alpha The alpha value to use (0.0=completely transparent, 1.0=completely
226     *              opaque).
227     */
228    public void setSurfaceAlpha(float alpha);
229
230    /**
231     * Get the alpha or transparency used when rendering surfaces or point-arrays.
232     *
233     * @return The alpha value used (0.0=completely transparent, 1.0=completely opaque).
234     */
235    public float getSurfaceAlpha();
236
237    /**
238     * Set the shininess used when rendering surfaces and point-arrays.
239     *
240     * @param shininess The shininess to use in the range [0.0, 1.0] where 0.0 is not
241     *                  shiny and 1.0 is very shiny. Values outside this range are
242     *                  clamped.
243     */
244    public void setSurfaceShininess(float shininess);
245
246    /**
247     * Get the shininess used when rendering surfaces and point-arrays.
248     *
249     * @return The shininess to use in the range [0.0, 1.0] where 0.0 is not shiny and 1.0
250     *         is very shiny.
251     */
252    public float getSurfaceShininess();
253}