1 /*
   2  * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package sun.awt;
  27 
  28 import java.awt.RenderingHints;
  29 import java.lang.annotation.Native;
  30 
  31 /**
  32  * This class contains rendering hints that can be used by the
  33  * {@link java.awt.Graphics2D} class, and classes that implement
  34  * {@link java.awt.image.BufferedImageOp} and
  35  * {@link java.awt.image.Raster}.
  36  */
  37 public class SunHints {
  38     /**
  39      * Defines the type of all keys used to control various
  40      * aspects of the rendering and imaging pipelines.  Instances
  41      * of this class are immutable and unique which means that
  42      * tests for matches can be made using the == operator instead
  43      * of the more expensive equals() method.
  44      */
  45     public static class Key extends RenderingHints.Key {
  46         String description;
  47 
  48         /**
  49          * Construct a key using the indicated private key.  Each
  50          * subclass of Key maintains its own unique domain of integer
  51          * keys.  No two objects with the same integer key and of the
  52          * same specific subclass can be constructed.  An exception
  53          * will be thrown if an attempt is made to construct another
  54          * object of a given class with the same integer key as a
  55          * pre-existing instance of that subclass of Key.
  56          */
  57         public Key(int privatekey, String description) {
  58             super(privatekey);
  59             this.description = description;
  60         }
  61 
  62         /**
  63          * Returns the numeric index associated with this Key.  This
  64          * is useful for use in switch statements and quick lookups
  65          * of the setting of a particular key.
  66          */
  67         public final int getIndex() {
  68             return intKey();
  69         }
  70 
  71         /**
  72          * Returns a string representation of the Key.
  73          */
  74         public final String toString() {
  75             return description;
  76         }
  77 
  78         /**
  79          * Returns true if the specified object is a valid value
  80          * for this Key.
  81          */
  82         public boolean isCompatibleValue(Object val) {
  83             if (val instanceof Value) {
  84                 return ((Value)val).isCompatibleKey(this);
  85             }
  86             return false;
  87         }
  88     }
  89 
  90     /**
  91      * Defines the type of all "enumerative" values used to control
  92      * various aspects of the rendering and imaging pipelines.  Instances
  93      * of this class are immutable and unique which means that
  94      * tests for matches can be made using the == operator instead
  95      * of the more expensive equals() method.
  96      */
  97     public static class Value {
  98         private SunHints.Key myKey;
  99         private int index;
 100         private String description;
 101 
 102         private static Value[][] ValueObjects =
 103             new Value[NUM_KEYS][VALS_PER_KEY];
 104 
 105         private synchronized static void register(SunHints.Key key,
 106                                                   Value value) {
 107             int kindex = key.getIndex();
 108             int vindex = value.getIndex();
 109             if (ValueObjects[kindex][vindex] != null) {
 110                 throw new InternalError("duplicate index: "+vindex);
 111             }
 112             ValueObjects[kindex][vindex] = value;
 113         }
 114 
 115         public static Value get(int keyindex, int valueindex) {
 116             return ValueObjects[keyindex][valueindex];
 117         }
 118 
 119         /**
 120          * Construct a value using the indicated private index.  Each
 121          * subclass of Value maintains its own unique domain of integer
 122          * indices.  Enforcing the uniqueness of the integer indices
 123          * is left to the subclass.
 124          */
 125         public Value(SunHints.Key key, int index, String description) {
 126             this.myKey = key;
 127             this.index = index;
 128             this.description = description;
 129 
 130             register(key, this);
 131         }
 132 
 133         /**
 134          * Returns the numeric index associated with this Key.  This
 135          * is useful for use in switch statements and quick lookups
 136          * of the setting of a particular key.
 137          */
 138         public final int getIndex() {
 139             return index;
 140         }
 141 
 142         /**
 143          * Returns a string representation of this Value.
 144          */
 145         public final String toString() {
 146             return description;
 147         }
 148 
 149         /**
 150          * Returns true if the specified object is a valid Key
 151          * for this Value.
 152          */
 153         public final boolean isCompatibleKey(Key k) {
 154             return myKey == k;
 155         }
 156 
 157         /**
 158          * The hash code for all SunHints.Value objects will be the same
 159          * as the system identity code of the object as defined by the
 160          * System.identityHashCode() method.
 161          */
 162         public final int hashCode() {
 163             return System.identityHashCode(this);
 164         }
 165 
 166         /**
 167          * The equals method for all SunHints.Value objects will return
 168          * the same result as the equality operator '=='.
 169          */
 170         public final boolean equals(Object o) {
 171             return this == o;
 172         }
 173     }
 174 
 175     private static final int NUM_KEYS = 10;
 176     private static final int VALS_PER_KEY = 8;
 177 
 178     /**
 179      * Rendering hint key and values
 180      */
 181     @Native public static final int INTKEY_RENDERING = 0;
 182     @Native public static final int INTVAL_RENDER_DEFAULT = 0;
 183     @Native public static final int INTVAL_RENDER_SPEED = 1;
 184     @Native public static final int INTVAL_RENDER_QUALITY = 2;
 185 
 186     /**
 187      * Antialiasing hint key and values
 188      */
 189     @Native public static final int INTKEY_ANTIALIASING = 1;
 190     @Native public static final int INTVAL_ANTIALIAS_DEFAULT = 0;
 191     @Native public static final int INTVAL_ANTIALIAS_OFF = 1;
 192     @Native public static final int INTVAL_ANTIALIAS_ON = 2;
 193 
 194     /**
 195      * Text antialiasing hint key and values
 196      */
 197     @Native public static final int INTKEY_TEXT_ANTIALIASING = 2;
 198     @Native public static final int INTVAL_TEXT_ANTIALIAS_DEFAULT = 0;
 199     @Native public static final int INTVAL_TEXT_ANTIALIAS_OFF = 1;
 200     @Native public static final int INTVAL_TEXT_ANTIALIAS_ON = 2;
 201     @Native public static final int INTVAL_TEXT_ANTIALIAS_GASP = 3;
 202     @Native public static final int INTVAL_TEXT_ANTIALIAS_LCD_HRGB = 4;
 203     @Native public static final int INTVAL_TEXT_ANTIALIAS_LCD_HBGR = 5;
 204     @Native public static final int INTVAL_TEXT_ANTIALIAS_LCD_VRGB = 6;
 205     @Native public static final int INTVAL_TEXT_ANTIALIAS_LCD_VBGR = 7;
 206 
 207     /**
 208      * Font fractional metrics hint key and values
 209      */
 210     @Native public static final int INTKEY_FRACTIONALMETRICS = 3;
 211     @Native public static final int INTVAL_FRACTIONALMETRICS_DEFAULT = 0;
 212     @Native public static final int INTVAL_FRACTIONALMETRICS_OFF = 1;
 213     @Native public static final int INTVAL_FRACTIONALMETRICS_ON = 2;
 214 
 215     /**
 216      * Dithering hint key and values
 217      */
 218     @Native public static final int INTKEY_DITHERING = 4;
 219     @Native public static final int INTVAL_DITHER_DEFAULT = 0;
 220     @Native public static final int INTVAL_DITHER_DISABLE = 1;
 221     @Native public static final int INTVAL_DITHER_ENABLE = 2;
 222 
 223     /**
 224      * Interpolation hint key and values
 225      */
 226     @Native public static final int INTKEY_INTERPOLATION = 5;
 227     @Native public static final int INTVAL_INTERPOLATION_NEAREST_NEIGHBOR = 0;
 228     @Native public static final int INTVAL_INTERPOLATION_BILINEAR = 1;
 229     @Native public static final int INTVAL_INTERPOLATION_BICUBIC = 2;
 230 
 231     /**
 232      * Alpha interpolation hint key and values
 233      */
 234     @Native public static final int INTKEY_ALPHA_INTERPOLATION = 6;
 235     @Native public static final int INTVAL_ALPHA_INTERPOLATION_DEFAULT = 0;
 236     @Native public static final int INTVAL_ALPHA_INTERPOLATION_SPEED = 1;
 237     @Native public static final int INTVAL_ALPHA_INTERPOLATION_QUALITY = 2;
 238 
 239     /**
 240      * Color rendering hint key and values
 241      */
 242     @Native public static final int INTKEY_COLOR_RENDERING = 7;
 243     @Native public static final int INTVAL_COLOR_RENDER_DEFAULT = 0;
 244     @Native public static final int INTVAL_COLOR_RENDER_SPEED = 1;
 245     @Native public static final int INTVAL_COLOR_RENDER_QUALITY = 2;
 246 
 247     /**
 248      * Stroke normalization control hint key and values
 249      */
 250     @Native public static final int INTKEY_STROKE_CONTROL = 8;
 251     @Native public static final int INTVAL_STROKE_DEFAULT = 0;
 252     @Native public static final int INTVAL_STROKE_NORMALIZE = 1;
 253     @Native public static final int INTVAL_STROKE_PURE = 2;
 254 
 255     /**
 256      * Image scaling hint key and values
 257      */
 258     @Native public static final int INTKEY_RESOLUTION_VARIANT = 9;
 259     @Native public static final int INTVAL_RESOLUTION_VARIANT_DEFAULT = 0;
 260     @Native public static final int INTVAL_RESOLUTION_VARIANT_OFF = 1;
 261     @Native public static final int INTVAL_RESOLUTION_VARIANT_ON = 2;
 262     /**
 263      * LCD text contrast control hint key.
 264      * Value is "100" to make discontiguous with the others which
 265      * are all enumerative and are of a different class.
 266      */
 267     @Native public static final int INTKEY_AATEXT_LCD_CONTRAST = 100;
 268 
 269     /**
 270      * Rendering hint key and value objects
 271      */
 272     public static final Key KEY_RENDERING =
 273         new SunHints.Key(SunHints.INTKEY_RENDERING,
 274                          "Global rendering quality key");
 275     public static final Object VALUE_RENDER_SPEED =
 276         new SunHints.Value(KEY_RENDERING,
 277                            SunHints.INTVAL_RENDER_SPEED,
 278                            "Fastest rendering methods");
 279     public static final Object VALUE_RENDER_QUALITY =
 280         new SunHints.Value(KEY_RENDERING,
 281                            SunHints.INTVAL_RENDER_QUALITY,
 282                            "Highest quality rendering methods");
 283     public static final Object VALUE_RENDER_DEFAULT =
 284         new SunHints.Value(KEY_RENDERING,
 285                            SunHints.INTVAL_RENDER_DEFAULT,
 286                            "Default rendering methods");
 287 
 288     /**
 289      * Antialiasing hint key and value objects
 290      */
 291     public static final Key KEY_ANTIALIASING =
 292         new SunHints.Key(SunHints.INTKEY_ANTIALIASING,
 293                          "Global antialiasing enable key");
 294     public static final Object VALUE_ANTIALIAS_ON =
 295         new SunHints.Value(KEY_ANTIALIASING,
 296                            SunHints.INTVAL_ANTIALIAS_ON,
 297                            "Antialiased rendering mode");
 298     public static final Object VALUE_ANTIALIAS_OFF =
 299         new SunHints.Value(KEY_ANTIALIASING,
 300                            SunHints.INTVAL_ANTIALIAS_OFF,
 301                            "Nonantialiased rendering mode");
 302     public static final Object VALUE_ANTIALIAS_DEFAULT =
 303         new SunHints.Value(KEY_ANTIALIASING,
 304                            SunHints.INTVAL_ANTIALIAS_DEFAULT,
 305                            "Default antialiasing rendering mode");
 306 
 307     /**
 308      * Text antialiasing hint key and value objects
 309      */
 310     public static final Key KEY_TEXT_ANTIALIASING =
 311         new SunHints.Key(SunHints.INTKEY_TEXT_ANTIALIASING,
 312                          "Text-specific antialiasing enable key");
 313     public static final Object VALUE_TEXT_ANTIALIAS_ON =
 314         new SunHints.Value(KEY_TEXT_ANTIALIASING,
 315                            SunHints.INTVAL_TEXT_ANTIALIAS_ON,
 316                            "Antialiased text mode");
 317     public static final Object VALUE_TEXT_ANTIALIAS_OFF =
 318         new SunHints.Value(KEY_TEXT_ANTIALIASING,
 319                            SunHints.INTVAL_TEXT_ANTIALIAS_OFF,
 320                            "Nonantialiased text mode");
 321     public static final Object VALUE_TEXT_ANTIALIAS_DEFAULT =
 322         new SunHints.Value(KEY_TEXT_ANTIALIASING,
 323                            SunHints.INTVAL_TEXT_ANTIALIAS_DEFAULT,
 324                            "Default antialiasing text mode");
 325     public static final Object VALUE_TEXT_ANTIALIAS_GASP =
 326         new SunHints.Value(KEY_TEXT_ANTIALIASING,
 327                            SunHints.INTVAL_TEXT_ANTIALIAS_GASP,
 328                            "gasp antialiasing text mode");
 329     public static final Object VALUE_TEXT_ANTIALIAS_LCD_HRGB =
 330         new SunHints.Value(KEY_TEXT_ANTIALIASING,
 331                            SunHints.INTVAL_TEXT_ANTIALIAS_LCD_HRGB,
 332                            "LCD HRGB antialiasing text mode");
 333     public static final Object VALUE_TEXT_ANTIALIAS_LCD_HBGR =
 334         new SunHints.Value(KEY_TEXT_ANTIALIASING,
 335                            SunHints.INTVAL_TEXT_ANTIALIAS_LCD_HBGR,
 336                            "LCD HBGR antialiasing text mode");
 337     public static final Object VALUE_TEXT_ANTIALIAS_LCD_VRGB =
 338         new SunHints.Value(KEY_TEXT_ANTIALIASING,
 339                            SunHints.INTVAL_TEXT_ANTIALIAS_LCD_VRGB,
 340                            "LCD VRGB antialiasing text mode");
 341     public static final Object VALUE_TEXT_ANTIALIAS_LCD_VBGR =
 342         new SunHints.Value(KEY_TEXT_ANTIALIASING,
 343                            SunHints.INTVAL_TEXT_ANTIALIAS_LCD_VBGR,
 344                            "LCD VBGR antialiasing text mode");
 345 
 346     /**
 347      * Font fractional metrics hint key and value objects
 348      */
 349     public static final Key KEY_FRACTIONALMETRICS =
 350         new SunHints.Key(SunHints.INTKEY_FRACTIONALMETRICS,
 351                          "Fractional metrics enable key");
 352     public static final Object VALUE_FRACTIONALMETRICS_ON =
 353         new SunHints.Value(KEY_FRACTIONALMETRICS,
 354                            SunHints.INTVAL_FRACTIONALMETRICS_ON,
 355                            "Fractional text metrics mode");
 356     public static final Object VALUE_FRACTIONALMETRICS_OFF =
 357         new SunHints.Value(KEY_FRACTIONALMETRICS,
 358                            SunHints.INTVAL_FRACTIONALMETRICS_OFF,
 359                            "Integer text metrics mode");
 360     public static final Object VALUE_FRACTIONALMETRICS_DEFAULT =
 361         new SunHints.Value(KEY_FRACTIONALMETRICS,
 362                            SunHints.INTVAL_FRACTIONALMETRICS_DEFAULT,
 363                            "Default fractional text metrics mode");
 364 
 365     /**
 366      * Dithering hint key and value objects
 367      */
 368     public static final Key KEY_DITHERING =
 369         new SunHints.Key(SunHints.INTKEY_DITHERING,
 370                          "Dithering quality key");
 371     public static final Object VALUE_DITHER_ENABLE =
 372         new SunHints.Value(KEY_DITHERING,
 373                            SunHints.INTVAL_DITHER_ENABLE,
 374                            "Dithered rendering mode");
 375     public static final Object VALUE_DITHER_DISABLE =
 376         new SunHints.Value(KEY_DITHERING,
 377                            SunHints.INTVAL_DITHER_DISABLE,
 378                            "Nondithered rendering mode");
 379     public static final Object VALUE_DITHER_DEFAULT =
 380         new SunHints.Value(KEY_DITHERING,
 381                            SunHints.INTVAL_DITHER_DEFAULT,
 382                            "Default dithering mode");
 383 
 384     /**
 385      * Interpolation hint key and value objects
 386      */
 387     public static final Key KEY_INTERPOLATION =
 388         new SunHints.Key(SunHints.INTKEY_INTERPOLATION,
 389                          "Image interpolation method key");
 390     public static final Object VALUE_INTERPOLATION_NEAREST_NEIGHBOR =
 391         new SunHints.Value(KEY_INTERPOLATION,
 392                            SunHints.INTVAL_INTERPOLATION_NEAREST_NEIGHBOR,
 393                            "Nearest Neighbor image interpolation mode");
 394     public static final Object VALUE_INTERPOLATION_BILINEAR =
 395         new SunHints.Value(KEY_INTERPOLATION,
 396                            SunHints.INTVAL_INTERPOLATION_BILINEAR,
 397                            "Bilinear image interpolation mode");
 398     public static final Object VALUE_INTERPOLATION_BICUBIC =
 399         new SunHints.Value(KEY_INTERPOLATION,
 400                            SunHints.INTVAL_INTERPOLATION_BICUBIC,
 401                            "Bicubic image interpolation mode");
 402 
 403     /**
 404      * Alpha interpolation hint key and value objects
 405      */
 406     public static final Key KEY_ALPHA_INTERPOLATION =
 407         new SunHints.Key(SunHints.INTKEY_ALPHA_INTERPOLATION,
 408                          "Alpha blending interpolation method key");
 409     public static final Object VALUE_ALPHA_INTERPOLATION_SPEED =
 410         new SunHints.Value(KEY_ALPHA_INTERPOLATION,
 411                            SunHints.INTVAL_ALPHA_INTERPOLATION_SPEED,
 412                            "Fastest alpha blending methods");
 413     public static final Object VALUE_ALPHA_INTERPOLATION_QUALITY =
 414         new SunHints.Value(KEY_ALPHA_INTERPOLATION,
 415                            SunHints.INTVAL_ALPHA_INTERPOLATION_QUALITY,
 416                            "Highest quality alpha blending methods");
 417     public static final Object VALUE_ALPHA_INTERPOLATION_DEFAULT =
 418         new SunHints.Value(KEY_ALPHA_INTERPOLATION,
 419                            SunHints.INTVAL_ALPHA_INTERPOLATION_DEFAULT,
 420                            "Default alpha blending methods");
 421 
 422     /**
 423      * Color rendering hint key and value objects
 424      */
 425     public static final Key KEY_COLOR_RENDERING =
 426         new SunHints.Key(SunHints.INTKEY_COLOR_RENDERING,
 427                          "Color rendering quality key");
 428     public static final Object VALUE_COLOR_RENDER_SPEED =
 429         new SunHints.Value(KEY_COLOR_RENDERING,
 430                            SunHints.INTVAL_COLOR_RENDER_SPEED,
 431                            "Fastest color rendering mode");
 432     public static final Object VALUE_COLOR_RENDER_QUALITY =
 433         new SunHints.Value(KEY_COLOR_RENDERING,
 434                            SunHints.INTVAL_COLOR_RENDER_QUALITY,
 435                            "Highest quality color rendering mode");
 436     public static final Object VALUE_COLOR_RENDER_DEFAULT =
 437         new SunHints.Value(KEY_COLOR_RENDERING,
 438                            SunHints.INTVAL_COLOR_RENDER_DEFAULT,
 439                            "Default color rendering mode");
 440 
 441     /**
 442      * Stroke normalization control hint key and value objects
 443      */
 444     public static final Key KEY_STROKE_CONTROL =
 445         new SunHints.Key(SunHints.INTKEY_STROKE_CONTROL,
 446                          "Stroke normalization control key");
 447     public static final Object VALUE_STROKE_DEFAULT =
 448         new SunHints.Value(KEY_STROKE_CONTROL,
 449                            SunHints.INTVAL_STROKE_DEFAULT,
 450                            "Default stroke normalization");
 451     public static final Object VALUE_STROKE_NORMALIZE =
 452         new SunHints.Value(KEY_STROKE_CONTROL,
 453                            SunHints.INTVAL_STROKE_NORMALIZE,
 454                            "Normalize strokes for consistent rendering");
 455     public static final Object VALUE_STROKE_PURE =
 456         new SunHints.Value(KEY_STROKE_CONTROL,
 457                            SunHints.INTVAL_STROKE_PURE,
 458                            "Pure stroke conversion for accurate paths");
 459 
 460     /**
 461      * Image resolution variant hint key and value objects
 462      */
 463     public static final Key KEY_RESOLUTION_VARIANT =
 464         new SunHints.Key(SunHints.INTKEY_RESOLUTION_VARIANT,
 465                          "Global image resolution variant key");
 466     public static final Object VALUE_RESOLUTION_VARIANT_DEFAULT =
 467         new SunHints.Value(KEY_RESOLUTION_VARIANT,
 468                            SunHints.INTVAL_RESOLUTION_VARIANT_DEFAULT,
 469                            "Default resolution variant usage");
 470     public static final Object VALUE_RESOLUTION_VARIANT_OFF =
 471         new SunHints.Value(KEY_RESOLUTION_VARIANT,
 472                            SunHints.INTVAL_RESOLUTION_VARIANT_OFF,
 473                            "Use only default resolution variants of images");
 474     public static final Object VALUE_RESOLUTION_VARIANT_ON =
 475         new SunHints.Value(KEY_RESOLUTION_VARIANT,
 476                            SunHints.INTVAL_RESOLUTION_VARIANT_ON,
 477                            "Use resolution variants of images");
 478 
 479     public static class LCDContrastKey extends Key {
 480 
 481         public LCDContrastKey(int privatekey, String description) {
 482             super(privatekey, description);
 483         }
 484 
 485         /**
 486          * Returns true if the specified object is a valid value
 487          * for this Key. The allowable range is 100 to 250.
 488          */
 489         public final boolean isCompatibleValue(Object val) {
 490             if (val instanceof Integer) {
 491                 int ival = ((Integer)val).intValue();
 492                 return ival >= 100 && ival <= 250;
 493             }
 494             return false;
 495         }
 496 
 497     }
 498 
 499     /**
 500      * LCD text contrast hint key
 501      */
 502     public static final RenderingHints.Key
 503         KEY_TEXT_ANTIALIAS_LCD_CONTRAST =
 504         new LCDContrastKey(SunHints.INTKEY_AATEXT_LCD_CONTRAST,
 505                            "Text-specific LCD contrast key");
 506 }