/*
* Geotoolkit - An Open Source Java GIS Toolkit
* http://www.geotoolkit.org
*
* (C) 2008 - 2013, Geomatys
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation;
* version 2.1 of the License.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*/
package org.geotoolkit.display.canvas;
import java.awt.Graphics2D;
import java.awt.geom.AffineTransform;
import java.util.Date;
import org.geotoolkit.display.canvas.control.CanvasMonitor;
import org.geotoolkit.factory.Hints;
import org.opengis.referencing.crs.CoordinateReferenceSystem;
import org.opengis.referencing.operation.CoordinateOperationFactory;
import org.opengis.referencing.operation.MathTransform;
import org.opengis.referencing.operation.TransformException;
import org.opengis.util.FactoryException;
/**
* Informations relative to a rendering in progress. A {@code RenderingContext} instance is
* created by {@link AWTDirectRenderer2D#paint} at rendering time, which iterates over all graphic
* objects and invokes {@link GraphicPrimitive2D#paint} for each of them. The rendering context
* is disposed once the rendering is completed. {@code RenderingContext} instances contain the
* following informations:
* <p>
* <ul>
* <li>The {@link Graphics2D} handler to use for rendering.</li>
* <li>The coordinate reference systems in use and the transformations between them.</li>
* <li>The area rendered up to date. This information shall be updated by each
* {@link GraphicPrimitive2D} while they are painting.</li>
* <li>The map scale.</li>
* </ul>
* <p>
* A rendering usually implies the following transformations (names are
* {@linkplain CoordinateReferenceSystem coordinate reference systems} and arrows
* are {@linkplain MathTransform transforms}):
*
* <p align="center">
* {@code graphicCRS} <img src="doc-files/right.png">
* {@link #objectiveCRS} <img src="doc-files/right.png">
* {@link #displayCRS} <img src="doc-files/right.png">
* {@code deviceCRS}
* </p>
*
* @module
* @since 2.3
* @version $Id$
* @author Martin Desruisseaux (IRD)
* @author Johann Sorel (Geomatys)
*
*/
public interface RenderingContext {
/**
* Returns the canvas who created this renderingContext.
*
* @return current rendering canvas
*/
Canvas getCanvas();
/**
* Returns the rendering objective CRS. this may not be at all time
* the same crs as the canvas, because the canvas might be update while rendering.
* @return Objective CRS
*/
CoordinateReferenceSystem getObjectiveCRS();
/**
* Returns only the 2D component of the objective CRS.
* @return Objective CRS 2D
*/
CoordinateReferenceSystem getObjectiveCRS2D();
/**
* Returns the rendering display CRS. this may not be at all time
* the same CRS as the canvas, because the canvas might be update while rendering.
* @return Display CRS
*/
CoordinateReferenceSystem getDisplayCRS();
/**
* Sets the coordinate reference system in use for rendering in {@link Graphics2D}. Invoking
* this method do not alter the current state of any canvas or GO-2 graphic objects. It is
* only a convenient way to {@linkplain Graphics2D#setTransform set the affine transform} in
* the current <cite>Java2D</cite> {@link Graphics2D} handle, for example in order to alternate
* rendering mode between geographic features and labels. The specified coordinate reference
* system (the {@code crs} argument) is usually (but not limited to) one of
* {@link #objectiveCRS} or {@link #displayCRS} values.
*
* @param crs The CRS for the {@link #getGraphics() Java2D graphics handle}.
* @throws TransformException if this method failed to find an affine transform from the
* specified CRS to the device CRS.
*
* @see #getGraphics
* @see #getAffineTransform
* @see Graphics2D#setTransform
*/
void setGraphicsCRS(CoordinateReferenceSystem crs) throws TransformException;
/**
* Returns an affine transform between two coordinate reference systems. This method is
* equivalents to the following pseudo-code, except for the exception to be thrown if the
* transform is not an instance of {@link AffineTransform}.
*
* <blockquote><pre>
* return (AffineTransform) {@link #getMathTransform getMathTransform}(sourceCRS, targetCRS);
* </pre></blockquote>
*
* @param sourceCRS The source coordinate reference system.
* @param targetCRS The target coordinate reference system.
* @return An affine transform from {@code sourceCRS} to {@code targetCRS}.
* @throws FactoryException if the transform can't be created or is not affine.
*
* @see #getMathTransform
* @see BufferedCanvas2D#getImplHint
* @see Hints#COORDINATE_OPERATION_FACTORY
*/
AffineTransform getAffineTransform(final CoordinateReferenceSystem sourceCRS,
final CoordinateReferenceSystem targetCRS)
throws FactoryException;
/**
* Returns a transform between two coordinate systems. If a {@link
* Hints#COORDINATE_OPERATION_FACTORY} has been provided to the {@link BufferedCanvas2D},
* then the specified {@linkplain CoordinateOperationFactory coordinate operation factory}
* will be used. The arguments are usually (but not necessarily) one of the following pairs:
*
* <ul>
* <li><p><b>({@code graphicCRS}, {@linkplain #objectiveCRS}):</b><br>
* Arbitrary transform from the data CRS (used internally in a {@link GraphicPrimitive2D})
* to the objective CRS (set in {@link BufferedCanvas2D}).</p></li>
*
* <li><p><b>({@link #objectiveCRS}, {@link #displayCRS}):</b><br>
* {@linkplain AffineTransform Affine transform} from the objective CRS in "real world"
* units (usually metres or degrees) to the display CRS in dots (usually 1/72 of inch).
* This transform changes every time the zoom (or map scale) changes.</p></li>
* </ul>
*
* @param sourceCRS The source coordinate reference system.
* @param targetCRS The target coordinate reference system.
* @return A transform from {@code sourceCRS} to {@code targetCRS}.
* @throws FactoryException if the transformation can't be created.
*
* @see #getAffineTransform
* @see BufferedCanvas2D#getImplHint
* @see Hints#COORDINATE_OPERATION_FACTORY
*/
MathTransform getMathTransform(final CoordinateReferenceSystem sourceCRS,
final CoordinateReferenceSystem targetCRS)
throws FactoryException;
/**
* Get the canvas monitor.
*
* @return CanvasMonitor, can not be null.
*/
CanvasMonitor getMonitor();
/**
* Extract the date range from the canvas objective envelope (first temporal CRS).
* This array is never null but it's values can be null.
*
* @return array of two dates for the temporal range, never null.
*/
Date[] getTemporalRange();
/**
* Extract the elevation range from the canvas objective envelope (first vertical CRS).
* This array is never null but it's values can be null.
*
* @return array of two dates for the vertical range, never null.
*/
Double[] getElevationRange();
}