    001/* ===========================================================
    002 * Orson Charts : a 3D chart library for the Java(tm) platform
    003 * ===========================================================
    004 *
    005 * (C)opyright 2013-2016, by Object Refinery Limited.  All rights reserved.
    006 *
    007 * http://www.object-refinery.com/orsoncharts/index.html
    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 com.orsoncharts.renderer.xyz;
    034
    035import java.awt.Color;
    036import com.orsoncharts.Range;
    037import com.orsoncharts.data.xyz.XYZDataset;
    038import com.orsoncharts.plot.XYZPlot;
    039import com.orsoncharts.graphics3d.Dimension3D;
    040import com.orsoncharts.graphics3d.World;
    041import com.orsoncharts.renderer.ComposeType;
    042import com.orsoncharts.renderer.Renderer3D;
    043import com.orsoncharts.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}