001/* ===========================================================
002 * Orson Charts : a 3D chart library for the Java(tm) platform
003 * ===========================================================
004 * 
005 * (C)opyright 2013-2022, by David Gilbert.  All rights reserved.
006 * 
007 * https://github.com/jfree/orson-charts
008 * 
009 * This program is free software: you can redistribute it and/or modify
010 * it under the terms of the GNU General Public License as published by
011 * the Free Software Foundation, either version 3 of the License, or
012 * (at your option) any later version.
013 *
014 * This program is distributed in the hope that it will be useful,
015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
017 * GNU General Public License for more details.
018 *
019 * You should have received a copy of the GNU General Public License
020 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
021 * 
022 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
023 * Other names may be trademarks of their respective owners.]
024 * 
025 * If you do not wish to be bound by the terms of the GPL, an alternative
026 * commercial license can be purchased.  For details, please see visit the
027 * Orson Charts home page:
028 * 
029 * http://www.object-refinery.com/orsoncharts/index.html
030 * 
031 */
032
033package org.jfree.chart3d.renderer.xyz;
034
035import java.awt.Color;
036import org.jfree.chart3d.data.Range;
037import org.jfree.chart3d.data.xyz.XYZDataset;
038import org.jfree.chart3d.graphics3d.Dimension3D;
039import org.jfree.chart3d.graphics3d.World;
040import org.jfree.chart3d.plot.XYZPlot;
041import org.jfree.chart3d.renderer.ComposeType;
042import org.jfree.chart3d.renderer.Renderer3D;
043import org.jfree.chart3d.renderer.Renderer3DChangeEvent;
044
045/**
046 * A renderer that can display data from an {@link XYZDataset} on an
047 * {@link XYZPlot}.
048 */
049public interface XYZRenderer extends Renderer3D {
050
051    /**
052     * Returns the plot that this renderer is assigned to.
053     * 
054     * @return The plot (possibly {@code null}). 
055     */
056    XYZPlot getPlot();
057  
058    /**
059     * Sets the plot that the renderer is assigned to.  Although this method
060     * is part of the public API, client code should not need to call it.
061     * 
062     * @param plot  the plot ({@code null} permitted). 
063     */
064    void setPlot(XYZPlot plot);
065    
066    /**
067     * Returns the color source for the renderer, which is an object that
068     * is responsible for providing the colors used by the renderer to draw
069     * data (and legend) items.
070     * 
071     * @return The paint source (never {@code null}). 
072     */
073    XYZColorSource getColorSource();
074
075    /**
076     * Sets the color source for the renderer and sends a 
077     * {@link Renderer3DChangeEvent} to all registered listeners.
078     * 
079     * @param source  the color source ({@code null} not permitted).
080     * 
081     * @since 1.2
082     */
083    void setColorSource(XYZColorSource source);
084
085    /**
086     * Sets the colors for the renderer.
087     * 
088     * @param colors  the colors. 
089     * 
090     * @since 1.2
091     */
092    void setColors(Color... colors);
093
094    /**
095     * Returns the range that should be set on the x-axis in order for this 
096     * renderer to be able to display all the data in the supplied dataset.
097     * If the dataset contains no data, this method returns {@code null}.
098     * 
099     * @param dataset  the dataset ({@code null} not permitted).
100     * 
101     * @return The range (possibly {@code null}). 
102     */
103    Range findXRange(XYZDataset dataset);
104    
105    /**
106     * Returns the range that should be set on the y-axis in order for this 
107     * renderer to be able to display all the data in the supplied dataset.
108     * If the dataset contains no data, this method returns {@code null}.
109     * 
110     * @param dataset  the dataset ({@code null} not permitted).
111     * 
112     * @return The range. 
113     */
114    Range findYRange(XYZDataset dataset);
115    
116    /**
117     * Returns the range that should be set on the z-axis in order for this 
118     * renderer to be able to display all the data in the supplied dataset.
119     * If the dataset contains no data, this method returns {@code null}.
120     * 
121     * @param dataset  the dataset ({@code null} not permitted).
122     * 
123     * @return The range. 
124     */
125    Range findZRange(XYZDataset dataset);
126
127    /**
128     * Returns the type of composition performed by the renderer.  This
129     * determines whether the plot will call the {@code composeItem()}
130     * method (once for each data item) or just call the 
131     * {@code composeAll()} method once.
132     * 
133     * @return The type of composition (never {@code null}).
134     * 
135     * @since 1.1
136     */
137    ComposeType getComposeType();
138    
139    /**
140     * Constructs and places one item from the specified dataset into the given 
141     * world.  The {@link XYZPlot} class will iterate over its dataset and
142     * and call this method for each item (in other words, you don't need to 
143     * call this method directly).
144     * 
145     * @param dataset the dataset ({@code null} not permitted).
146     * @param series  the series index.
147     * @param item  the item index.
148     * @param world  the world ({@code null} not permitted).
149     * @param dimensions  the dimensions ({@code null} not permitted).
150     * @param xOffset  the x-offset.
151     * @param yOffset  the y-offset.
152     * @param zOffset  the z-offset.
153     */
154    void composeItem(XYZDataset dataset, int series, int item, 
155            World world, Dimension3D dimensions, 
156            double xOffset, double yOffset, double zOffset);
157
158    /**
159     * Composes all the 3D objects that this renderer needs to present.  This
160     * method only needs to be implemented if the {@code getComposeType()}
161     * method returns {@code ALL}, otherwise it can be left empty.
162     * 
163     * @param plot  the plot.
164     * @param world  the world ({@code null} not permitted).
165     * @param dimensions  the dimensions ({@code null} not permitted).
166     * @param xOffset  the x-offset.
167     * @param yOffset  the y-offset.
168     * @param zOffset  the z-offset.
169     * 
170     * @since 1.1
171     */
172    void composeAll(XYZPlot plot, World world, Dimension3D dimensions, 
173            double xOffset, double yOffset, double zOffset);
174
175}