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}