/*
 *    GeoTools - OpenSource mapping toolkit
 *    http://geotools.org
 *    (C) 2004-2006, Geotools Project Managment Committee (PMC)
 *
 *    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; either
 *    version 2.1 of the License, or (at your option) any later version.
 *
 *    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.geotools.renderer.lite;

import java.awt.Graphics2D;
import java.awt.Rectangle;
import java.util.List;

import javax.media.jai.util.Range;

import org.geotools.feature.Feature;
import org.geotools.geometry.jts.LiteShape2;
import org.geotools.styling.TextSymbolizer;

/**
 * An interface for a label cache. 
 * 
 * @author jeichar
 * @since 0.9.0
 * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/render/src/main/java/org/geotools/renderer/lite/LabelCache.java $
 */
public interface LabelCache {
	/**
	 * Called by renderer to indicate that the rendering process is starting.
	 */
	void start();
	/**
	 * Called by renderer to indication the start of rendering a layer.  Will add the layer to the
	 * set of active layers.
	 * 
	 * @param layerId an id for the layer
	 */
	void startLayer(String layerId);
	/**
	 * Puts a Label in the cache.
	 * 
	 * @param layerId  id indicating the layer the feature is part of
	 * @param symbolizer The symbolizer containing the style information
	 * @param feature the feature that has the information required for the symbolizer to 
	 * calculate the required render information. 
	 * @param shape the shape to be labeled.  This is in screen coordinates.
	 * @param scaleRange the scaleRange that the symbolizer is legal
	 */
	void put( String layerId, TextSymbolizer symbolizer, Feature feature, LiteShape2 shape, Range scaleRange) ;
	/**
	 * Called to indicate that a layer is done rendering.  The method may draw labels if appropriate
	 * for the labeling algorithm 
	 * 
	 * @param graphics the graphics to draw on.
	 * @param displayArea The size of the display area
	 * @param layerId an id for the layer
	 */
	void endLayer(String layerId, Graphics2D graphics, Rectangle displayArea);
	/**
	 * Called to indicate that the map is done rendering.  The method may draw labels if appropriate
	 * for the labeling algorithm 
	 * 
	 * @param graphics the graphics to draw on.
	 * @param displayArea The size of the display area.
	 */
	void end(Graphics2D graphics, Rectangle displayArea);
	/**
	 * Tells the cache to stop labelling.  
	 */
	void stop();
	/**
	 * Clears the cache completely 
	 */
	public void clear();
	/**
	 * Clears the cache of all information relating to the layer identified.
	 * @param layerId id of the layer
	 */
	public void clear(String layerId);
	/**
	 * Leaves the label information in the cache but ignores it when calculating what labels are drawn.
	 * 
	 * @param layerId id of the layer to disable.
	 */
	public void disableLayer(String layerId);
	/**
	 * Enable a layer after being disabled.  If startLayer is called this does not need to be called
	 * as start layer implicitely activates the layer.
	 * 
	 * @param layerId layer to activate.
	 */
	public void enableLayer(String layerId);
	/**
	 *   return a list with all the values in priority order.  Both grouped and non-grouped
	 * @param labelCache
	 * @return
	 */
	public List orderedLabels();
}
