/*

 * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code 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 General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.awt;

import java.util.Map;

import java.util.Set;

import java.util.Collection;

import java.util.Collections;

import java.util.HashMap;

import java.util.Iterator;

import sun.awt.SunHints;

import java.lang.ref.WeakReference;

/**

 * The {@code RenderingHints} class defines and manages collections of

 * keys and associated values which allow an application to provide input

 * into the choice of algorithms used by other classes which perform

 * rendering and image manipulation services.

 * The {@link java.awt.Graphics2D} class, and classes that implement

 * {@link java.awt.image.BufferedImageOp} and

 * {@link java.awt.image.RasterOp} all provide methods to get and

 * possibly to set individual or groups of {@code RenderingHints}

 * keys and their associated values.

 * When those implementations perform any rendering or image manipulation

 * operations they should examine the values of any {@code RenderingHints}

 * that were requested by the caller and tailor the algorithms used

 * accordingly and to the best of their ability.

 * <p>

 * Note that since these keys and values are <i>hints</i>, there is

 * no requirement that a given implementation supports all possible

 * choices indicated below or that it can respond to requests to

 * modify its choice of algorithm.

 * The values of the various hint keys may also interact such that

 * while all variants of a given key are supported in one situation,

 * the implementation may be more restricted when the values associated

 * with other keys are modified.

 * For example, some implementations may be able to provide several

 * types of dithering when the antialiasing hint is turned off, but

 * have little control over dithering when antialiasing is on.

 * The full set of supported keys and hints may also vary by destination

 * since runtimes may use different underlying modules to render to

 * the screen, or to {@link java.awt.image.BufferedImage} objects,

 * or while printing.

 * <p>

 * Implementations are free to ignore the hints completely, but should

 * try to use an implementation algorithm that is as close as possible

 * to the request.

 * If an implementation supports a given algorithm when any value is used

 * for an associated hint key, then minimally it must do so when the

 * value for that key is the exact value that specifies the algorithm.

 * <p>

 * The keys used to control the hints are all special values that

 * subclass the associated {@link RenderingHints.Key} class.

 * Many common hints are expressed below as static constants in this

 * class, but the list is not meant to be exhaustive.

 * Other hints may be created by other packages by defining new objects

 * which subclass the {@code Key} class and defining the associated values.

 */

public class RenderingHints

    implements Map<Object,Object>, Cloneable

{

    /**

     * Defines the base type of all keys used along with the

     * {@link RenderingHints} class to control various

     * algorithm choices in the rendering and imaging pipelines.

     * Instances of this class are immutable and unique which

     * means that tests for matches can be made using the

     * {@code ==} operator instead of the more expensive

     * {@code equals()} method.

     */

    public abstract static class Key {

        private static HashMap<Object,Object> identitymap = new HashMap<>(17);

        private String getIdentity() {

            // Note that the identity string is dependent on 3 variables:

            //     - the name of the subclass of Key

            //     - the identityHashCode of the subclass of Key

            //     - the integer key of the Key

            // It is theoretically possible for 2 distinct keys to collide

            // along all 3 of those attributes in the context of multiple

            // we account for that possibility below in the recordIdentity

            // method by slightly relaxing our uniqueness guarantees if we

            // end up in that situation.

            return getClass().getName()+"@"+

                Integer.toHexString(System.identityHashCode(getClass()))+":"+

                Integer.toHexString(privatekey);

        }

        private synchronized static void recordIdentity(Key k) {

            Object identity = k.getIdentity();

            Object otherref = identitymap.get(identity);

            if (otherref != null) {

                Key otherkey = (Key) ((WeakReference) otherref).get();

                if (otherkey != null && otherkey.getClass() == k.getClass()) {

                    throw new IllegalArgumentException(identity+

                                                       " already registered");

                }

                // Note that this system can fail in a mostly harmless

                // way.  If we end up generating the same identity

                // String for 2 different classes (a very rare case)

                // then we correctly avoid throwing the exception above,

                // but we are about to drop through to a statement that

                // will replace the entry for the old Key subclass with

                // an entry for the new Key subclass.  At that time the

                // old subclass will be vulnerable to someone generating

                // a duplicate Key instance for it.  We could bail out

                // of the method here and let the old identity keep its

                // record in the map, but we are more likely to see a

                // duplicate key go by for the new class than the old

                // one since the new one is probably still in the

                // initialization stage.  In either case, the probability

                // of loading 2 classes in the same VM with the same name

                // and identityHashCode should be nearly impossible.

            }

            // Note: Use a weak reference to avoid holding on to extra

            // objects and classes after they should be unloaded.

            identitymap.put(identity, new WeakReference<Key>(k));

        }

        private int privatekey;

        /**

         * Construct a key using the indicated private key.  Each

         * subclass of Key maintains its own unique domain of integer

         * keys.  No two objects with the same integer key and of the

         * same specific subclass can be constructed.  An exception

         * will be thrown if an attempt is made to construct another

         * object of a given class with the same integer key as a

         * pre-existing instance of that subclass of Key.

         * @param privatekey the specified key

         */

        protected Key(int privatekey) {

            this.privatekey = privatekey;

            recordIdentity(this);

        }

        /**

         * Returns true if the specified object is a valid value

         * for this Key.

         * @param val the <code>Object</code> to test for validity

         * @return <code>true</code> if <code>val</code> is valid;

         *         <code>false</code> otherwise.

         */

        public abstract boolean isCompatibleValue(Object val);

        /**

         * Returns the private integer key that the subclass

         * instantiated this Key with.

         * @return the private integer key that the subclass

         * instantiated this Key with.

         */

        protected final int intKey() {

            return privatekey;

        }

        /**

         * The hash code for all Key objects will be the same as the

         * system identity code of the object as defined by the

         * System.identityHashCode() method.

         */

        public final int hashCode() {

            return super.hashCode();

        }

        /**

         * The equals method for all Key objects will return the same

         * result as the equality operator '=='.

         */

        public final boolean equals(Object o) {

            return this == o;

        }

    }

    HashMap<Object,Object> hintmap = new HashMap<>(7);

    /**

     * Antialiasing hint key.

     * The {@code ANTIALIASING} hint controls whether or not the

     * geometry rendering methods of a {@link Graphics2D} object

     * will attempt to reduce aliasing artifacts along the edges

     * of shapes.

     * <p>

     * A typical antialiasing algorithm works by blending the existing

     * colors of the pixels along the boundary of a shape with the

     * requested fill paint according to the estimated partial pixel

     * coverage of the shape.

     * <p>

     * The allowable values for this hint are

     * <ul>

     * <li>{@link #VALUE_ANTIALIAS_ON}

     * <li>{@link #VALUE_ANTIALIAS_OFF}

     * <li>{@link #VALUE_ANTIALIAS_DEFAULT}

     * </ul>

     */

    public static final Key KEY_ANTIALIASING =

        SunHints.KEY_ANTIALIASING;

    /**

     * Antialiasing hint value -- rendering is done with antialiasing.

     * @see #KEY_ANTIALIASING

     */

    public static final Object VALUE_ANTIALIAS_ON =

        SunHints.VALUE_ANTIALIAS_ON;

    /**

     * Antialiasing hint value -- rendering is done without antialiasing.

     * @see #KEY_ANTIALIASING

     */

    public static final Object VALUE_ANTIALIAS_OFF =

        SunHints.VALUE_ANTIALIAS_OFF;

    /**

     * Antialiasing hint value -- rendering is done with a default

     * antialiasing mode chosen by the implementation.

     * @see #KEY_ANTIALIASING

     */

    public static final Object VALUE_ANTIALIAS_DEFAULT =

         SunHints.VALUE_ANTIALIAS_DEFAULT;

    /**

     * Rendering hint key.

     * The {@code RENDERING} hint is a general hint that provides

     * a high level recommendation as to whether to bias algorithm

     * choices more for speed or quality when evaluating tradeoffs.

     * This hint could be consulted for any rendering or image

     * manipulation operation, but decisions will usually honor

     * other, more specific hints in preference to this hint.

     * <p>

     * The allowable values for this hint are

     * <ul>

     * <li>{@link #VALUE_RENDER_SPEED}

     * <li>{@link #VALUE_RENDER_QUALITY}

     * <li>{@link #VALUE_RENDER_DEFAULT}

     * </ul>

     */

    public static final Key KEY_RENDERING =

         SunHints.KEY_RENDERING;

    /**

     * Rendering hint value -- rendering algorithms are chosen

     * with a preference for output speed.

     * @see #KEY_RENDERING

     */

    public static final Object VALUE_RENDER_SPEED =

         SunHints.VALUE_RENDER_SPEED;

    /**

     * Rendering hint value -- rendering algorithms are chosen

     * with a preference for output quality.

     * @see #KEY_RENDERING

     */

    public static final Object VALUE_RENDER_QUALITY =

         SunHints.VALUE_RENDER_QUALITY;

    /**

     * Rendering hint value -- rendering algorithms are chosen

     * by the implementation for a good tradeoff of performance

     * vs. quality.

     * @see #KEY_RENDERING

     */

    public static final Object VALUE_RENDER_DEFAULT =

         SunHints.VALUE_RENDER_DEFAULT;

    /**

     * Dithering hint key.

     * The {@code DITHERING} hint controls how closely to approximate

     * a color when storing into a destination with limited color

     * resolution.

     * <p>

     * Some rendering destinations may support a limited number of

     * color choices which may not be able to accurately represent

     * the full spectrum of colors that can result during rendering

     * operations.

     * For such a destination the {@code DITHERING} hint controls

     * whether rendering is done with a flat solid fill of a single

     * pixel value which is the closest supported color to what was

     * requested, or whether shapes will be filled with a pattern of

     * colors which combine to better approximate that color.

     * <p>

     * The allowable values for this hint are

     * <ul>

     * <li>{@link #VALUE_DITHER_DISABLE}

     * <li>{@link #VALUE_DITHER_ENABLE}

     * <li>{@link #VALUE_DITHER_DEFAULT}

     * </ul>

     */

    public static final Key KEY_DITHERING =

         SunHints.KEY_DITHERING;

    /**

     * Dithering hint value -- do not dither when rendering geometry.

     * @see #KEY_DITHERING

     */

    public static final Object VALUE_DITHER_DISABLE =

         SunHints.VALUE_DITHER_DISABLE;

    /**

     * Dithering hint value -- dither when rendering geometry, if needed.

     * @see #KEY_DITHERING

     */

    public static final Object VALUE_DITHER_ENABLE =

         SunHints.VALUE_DITHER_ENABLE;

    /**

     * Dithering hint value -- use a default for dithering chosen by

     * the implementation.

     * @see #KEY_DITHERING

     */

    public static final Object VALUE_DITHER_DEFAULT =

         SunHints.VALUE_DITHER_DEFAULT;

    /**

     * Text antialiasing hint key.

     * The {@code TEXT_ANTIALIASING} hint can control the use of

     * antialiasing algorithms for text independently of the

     * choice used for shape rendering.

     * Often an application may want to use antialiasing for text

     * only and not for other shapes.

     * Additionally, the algorithms for reducing the aliasing

     * artifacts for text are often more sophisticated than those

     * that have been developed for general rendering so this

     * hint key provides additional values which can control

     * the choices of some of those text-specific algorithms.

     * If left in the {@code DEFAULT} state, this hint will

     * generally defer to the value of the regular

     * {@link #KEY_ANTIALIASING} hint key.

     * <p>

     * The allowable values for this hint are

     * <ul>

     * <li>{@link #VALUE_TEXT_ANTIALIAS_ON}

     * <li>{@link #VALUE_TEXT_ANTIALIAS_OFF}

     * <li>{@link #VALUE_TEXT_ANTIALIAS_DEFAULT}

     * <li>{@link #VALUE_TEXT_ANTIALIAS_GASP}

     * <li>{@link #VALUE_TEXT_ANTIALIAS_LCD_HRGB}

     * <li>{@link #VALUE_TEXT_ANTIALIAS_LCD_HBGR}

     * <li>{@link #VALUE_TEXT_ANTIALIAS_LCD_VRGB}

     * <li>{@link #VALUE_TEXT_ANTIALIAS_LCD_VBGR}

     * </ul>

     */

    public static final Key KEY_TEXT_ANTIALIASING =

         SunHints.KEY_TEXT_ANTIALIASING;

    /**

     * Text antialiasing hint value -- text rendering is done with

     * some form of antialiasing.

     * @see #KEY_TEXT_ANTIALIASING

     */

    public static final Object VALUE_TEXT_ANTIALIAS_ON =

         SunHints.VALUE_TEXT_ANTIALIAS_ON;

    /**

     * Text antialiasing hint value -- text rendering is done without

     * any form of antialiasing.

     * @see #KEY_TEXT_ANTIALIASING

     */

    public static final Object VALUE_TEXT_ANTIALIAS_OFF =

         SunHints.VALUE_TEXT_ANTIALIAS_OFF;

    /**

     * Text antialiasing hint value -- text rendering is done according

     * to the {@link #KEY_ANTIALIASING} hint or a default chosen by the

     * implementation.

     * @see #KEY_TEXT_ANTIALIASING

     */

    public static final Object VALUE_TEXT_ANTIALIAS_DEFAULT =

         SunHints.VALUE_TEXT_ANTIALIAS_DEFAULT;

    /**

     * Text antialiasing hint value -- text rendering is requested to

     * use information in the font resource which specifies for each point

     * size whether to apply {@link #VALUE_TEXT_ANTIALIAS_ON} or

     * {@link #VALUE_TEXT_ANTIALIAS_OFF}.

     * <p>

     * TrueType fonts typically provide this information in the 'gasp' table.

     * In the absence of this information, the behaviour for a particular

     * font and size is determined by implementation defaults.

     * <p>

     * <i>Note:</i>A font designer will typically carefully hint a font for

     * the most common user interface point sizes. Consequently the 'gasp'

     * table will likely specify to use only hinting at those sizes and not

     * "smoothing". So in many cases the resulting text display is

     * equivalent to {@code VALUE_TEXT_ANTIALIAS_OFF}.

     * This may be unexpected but is correct.

     * <p>

     * Logical fonts which are composed of multiple physical fonts will for

     * consistency will use the setting most appropriate for the overall

     * composite font.

     *

     * @see #KEY_TEXT_ANTIALIASING

     * @since 1.6

     */

    public static final Object VALUE_TEXT_ANTIALIAS_GASP =

         SunHints.VALUE_TEXT_ANTIALIAS_GASP;

    /**

     * Text antialiasing hint value -- request that text be displayed

     * optimised for an LCD display with subpixels in order from display

     * left to right of R,G,B such that the horizontal subpixel resolution

     * is three times that of the full pixel horizontal resolution (HRGB).

     * This is the most common configuration.

     * Selecting this hint for displays with one of the other LCD subpixel

     * configurations will likely result in unfocused text.

     * <p>

     * <i>Notes:</i><br>

     * An implementation when choosing whether to apply any of the

     * LCD text hint values may take into account factors including requiring

     * color depth of the destination to be at least 15 bits per pixel

     * (ie 5 bits per color component),

     * characteristics of a font such as whether embedded bitmaps may

     * produce better results, or when displaying to a non-local networked

     * display device enabling it only if suitable protocols are available,

     * or ignoring the hint if performing very high resolution rendering

     * or the target device is not appropriate: eg when printing.

     * <p>

     * These hints can equally be applied when rendering to software images,

     * but these images may not then be suitable for general export, as the

     * text will have been rendered appropriately for a specific subpixel

     * organisation. Also lossy images are not a good choice, nor image

     * formats such as GIF which have limited colors.

     * So unless the image is destined solely for rendering on a

     * display device with the same configuration, some other text

     * anti-aliasing hint such as

     * {@link #VALUE_TEXT_ANTIALIAS_ON}

     * may be a better choice.

     * <p>Selecting a value which does not match the LCD display in use

     * will likely lead to a degradation in text quality.

     * On display devices (ie CRTs) which do not have the same characteristics

     * as LCD displays, the overall effect may appear similar to standard text

     * anti-aliasing, but the quality may be degraded by color distortion.

     * Analog connected LCD displays may also show little advantage over

     * standard text-antialiasing and be similar to CRTs.

     * <p>

     * In other words for the best results use an LCD display with a digital

     * display connector and specify the appropriate sub-pixel configuration.

     *

     * @see #KEY_TEXT_ANTIALIASING

     * @since 1.6

     */

    public static final Object VALUE_TEXT_ANTIALIAS_LCD_HRGB =

         SunHints.VALUE_TEXT_ANTIALIAS_LCD_HRGB;

    /**

     * Text antialiasing hint value -- request that text be displayed

     * optimised for an LCD display with subpixels in order from display

     * left to right of B,G,R such that the horizontal subpixel resolution

     * is three times that of the full pixel horizontal resolution (HBGR).

     * This is a much less common configuration than HRGB.

     * Selecting this hint for displays with one of the other LCD subpixel

     * configurations will likely result in unfocused text.

     * See {@link #VALUE_TEXT_ANTIALIAS_LCD_HRGB},

     * for more information on when this hint is applied.

     *

     * @see #KEY_TEXT_ANTIALIASING

     * @since 1.6

     */

    public static final Object VALUE_TEXT_ANTIALIAS_LCD_HBGR =

         SunHints.VALUE_TEXT_ANTIALIAS_LCD_HBGR;

    /**

     * Text antialiasing hint value -- request that text be displayed

     * optimised for an LCD display with subpixel organisation from display

     * top to bottom of R,G,B such that the vertical subpixel resolution is

     * three times that of the full pixel vertical resolution (VRGB).

     * Vertical orientation is very uncommon and probably mainly useful

     * for a physically rotated display.

     * Selecting this hint for displays with one of the other LCD subpixel

     * configurations will likely result in unfocused text.

     * See {@link #VALUE_TEXT_ANTIALIAS_LCD_HRGB},

     * for more information on when this hint is applied.

     *

     * @see #KEY_TEXT_ANTIALIASING

     * @since 1.6

     */

    public static final Object VALUE_TEXT_ANTIALIAS_LCD_VRGB =

         SunHints.VALUE_TEXT_ANTIALIAS_LCD_VRGB;

    /**

     * Text antialiasing hint value -- request that text be displayed

     * optimised for an LCD display with subpixel organisation from display

     * top to bottom of B,G,R such that the vertical subpixel resolution is

     * three times that of the full pixel vertical resolution (VBGR).

     * Vertical orientation is very uncommon and probably mainly useful

     * for a physically rotated display.

     * Selecting this hint for displays with one of the other LCD subpixel

     * configurations will likely result in unfocused text.

     * See {@link #VALUE_TEXT_ANTIALIAS_LCD_HRGB},

     * for more information on when this hint is applied.

     *

     * @see #KEY_TEXT_ANTIALIASING

     * @since 1.6

     */

    public static final Object VALUE_TEXT_ANTIALIAS_LCD_VBGR =

         SunHints.VALUE_TEXT_ANTIALIAS_LCD_VBGR;

    /**

     * LCD text contrast rendering hint key.

     * The value is an <code>Integer</code> object which is used as a text

     * contrast adjustment when used in conjunction with an LCD text

     * anti-aliasing hint such as

     * {@link #VALUE_TEXT_ANTIALIAS_LCD_HRGB}.

     * <ul>

     * <li>Values should be a positive integer in the range 100 to 250.