home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / awt / AlphaComposite.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  10.9 KB  |  366 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)AlphaComposite.java    1.27 98/05/04
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.awt;
  16.  
  17. import java.awt.image.ColorModel;
  18.  
  19. /**
  20.  * This <code>AlphaComposite</code> class implements the basic alpha 
  21.  * compositing rules for combining source and destination pixels to achieve
  22.  * blending and transparency effects with graphics and images.
  23.  * The rules implemented by this class are a subset of the Porter-Duff
  24.  * rules described in
  25.  * T. Porter and T. Duff, "Compositing Digital Images", SIGGRAPH 84,
  26.  * 253-259.
  27.  *<p>
  28.  * If any input does not have an alpha channel, an alpha value of 1.0, 
  29.  * which is completely opaque, is assumed for all pixels.  A constant 
  30.  * alpha value can also be specified to be multiplied with the alpha 
  31.  * value of the source pixels.
  32.  * <p>
  33.  * The following abbreviations are used in the description of the rules:
  34.  * <ul>
  35.  * <li>Cs = one of the color components of the source pixel.
  36.  * <li>Cd = one of the color components of the destination pixel.
  37.  * <li>As = alpha component of the source pixel.
  38.  * <li>Ad = alpha component of the destination pixel.
  39.  * <li>Fs = fraction of the source pixel that contributes to the output.
  40.  * <li>Fd = fraction of the input destination pixel that contributes to the
  41.  * output.
  42.  * </ul>
  43.  *<p>
  44.  * The color and alpha components produced by the compositing operation are
  45.  * calculated as follows:
  46.  *<pre>
  47.  *     Cd = Cs*Fs + Cd*Fd
  48.  *     Ad = As*Fs + Ad*Fd
  49.  *</pre>
  50.  * where Fs and Fd are specified by each rule.  The above equations assume
  51.  * that both source and destination pixels have the color components
  52.  * premultiplied by the alpha component.  Similarly, the equations expressed
  53.  * in the definitions of compositing rules below assume premultiplied alpha.
  54.  *<p>
  55.  * For performance reasons, it is preferrable that Rasters passed to the compose
  56.  * method of a {@link CompositeContext} object created by the 
  57.  * <code>AlphaComposite</code> class have premultiplied data.
  58.  * If either source or destination Rasters are not premultiplied, however,
  59.  * appropriate conversions are performed before and after the compositing
  60.  * operation.
  61.  *<p>
  62.  * The alpha resulting from the compositing operation is stored
  63.  * in the destination if the destination has an alpha channel.
  64.  * Otherwise, the resulting color is divided by the resulting
  65.  * alpha before being stored in the destination and the alpha is discarded.
  66.  * If the alpha value is 0.0, the color values are set to 0.0.
  67.  * @see Composite
  68.  * @see CompositeContext
  69.  * @version 10 Feb 1997
  70.  */
  71.  
  72.  
  73. public final class AlphaComposite implements Composite {
  74.     /**
  75.      * Porter-Duff Clear rule.
  76.      * Both the color and the alpha of the destination are cleared.
  77.      * Neither the source nor the destination is used as input.
  78.      *<p>
  79.      * Fs = 0 and Fd = 0, thus:
  80.      *<pre>
  81.      *     Cd = 0
  82.      *     Ad = 0
  83.      *</pre>
  84.      * 
  85.      */
  86.     public static final int    CLEAR        = 1;
  87.  
  88.     /**
  89.      * Porter-Duff Source rule.
  90.      * The source is copied to the destination.
  91.      * The destination is not used as input.
  92.      *<p>
  93.      * Fs = 1 and Fd = 0, thus:
  94.      *<pre>
  95.      *     Cd = Cs
  96.      *     Ad = As
  97.      *</pre>
  98.      */
  99.     public static final int    SRC        = 2;
  100.  
  101.     /**
  102.      * Porter-Duff Source Over Destination rule.
  103.      * The source is composited over the destination.
  104.      *<p>
  105.      * Fs = 1 and Fd = (1-As), thus:
  106.      *<pre>
  107.      *     Cd = Cs + Cd*(1-As)
  108.      *     Ad = As + Ad*(1-As)
  109.      *</pre>
  110.      */
  111.     public static final int    SRC_OVER    = 3;
  112.  
  113.     /**
  114.      * Porter-Duff Destination Over Source rule.
  115.      * The destination is composited over the source and
  116.      * the result replaces the destination.
  117.      *<p>
  118.      * Fs = (1-Ad) and Fd = 1, thus:
  119.      *<pre>
  120.      *     Cd = Cs*(1-Ad) + Cd
  121.      *     Ad = As*(1-Ad) + Ad
  122.      *</pre>
  123.      */
  124.     public static final int    DST_OVER    = 4;
  125.  
  126.     /**
  127.      * Porter-Duff Source In Destination rule.
  128.      * The part of the source lying inside of the destination replaces
  129.      * the destination.
  130.      *<p>
  131.      * Fs = Ad and Fd = 0, thus:
  132.      *<pre>
  133.      *     Cd = Cs*Ad
  134.      *     Ad = As*Ad
  135.      *</pre>
  136.      */
  137.     public static final int    SRC_IN        = 5;
  138.  
  139.     /**
  140.      * Porter-Duff Destination In Source rule.
  141.      * The part of the destination lying inside of the source
  142.      * replaces the destination.
  143.      *<p>
  144.      * Fs = 0 and Fd = As, thus:
  145.      *<pre>
  146.      *     Cd = Cd*As
  147.      *     Ad = Ad*As
  148.      *</pre>
  149.      */
  150.     public static final int    DST_IN        = 6;
  151.  
  152.     /**
  153.      * Porter-Duff Source Held Out By Destination rule.
  154.      * The part of the source lying outside of the destination
  155.      * replaces the destination.
  156.      *<p>
  157.      * Fs = (1-Ad) and Fd = 0, thus:
  158.      *<pre>
  159.      *     Cd = Cs*(1-Ad)
  160.      *     Ad = As*(1-Ad)
  161.      *</pre>
  162.      */
  163.     public static final int    SRC_OUT        = 7;
  164.  
  165.     /**
  166.      * Porter-Duff Destination Held Out By Source rule.
  167.      * The part of the destination lying outside of the source
  168.      * replaces the destination.
  169.      *<p>
  170.      * Fs = 0 and Fd = (1-As), thus:
  171.      *<pre>
  172.      *     Cd = Cd*(1-As)
  173.      *     Ad = Ad*(1-As)
  174.      *</pre>
  175.      */
  176.     public static final int    DST_OUT        = 8;
  177.  
  178.     /**
  179.      * <code>AlphaComposite</code> object that implements the opaque CLEAR rule
  180.      * with an alpha of 1.0f.
  181.      * @see #CLEAR
  182.      */
  183.     public static final AlphaComposite Clear    = new AlphaComposite(CLEAR);
  184.  
  185.     /**
  186.      * <code>AlphaComposite</code> object that implements the opaque SRC rule
  187.      * with an alpha of 1.0f.
  188.      * @see #SRC
  189.      */
  190.     public static final AlphaComposite Src    = new AlphaComposite(SRC);
  191.  
  192.     /**
  193.      * <code>AlphaComposite</code> object that implements the opaque SRC_OVER rule
  194.      * with an alpha of 1.0f.
  195.      * @see #SRC_OVER
  196.      */
  197.     public static final AlphaComposite SrcOver    = new AlphaComposite(SRC_OVER);
  198.  
  199.     /**
  200.      * <code>AlphaComposite</code> object that implements the opaque DST_OVER rule
  201.      * with an alpha of 1.0f.
  202.      * @see #DST_OVER
  203.      */
  204.     public static final AlphaComposite DstOver    = new AlphaComposite(DST_OVER);
  205.  
  206.     /**
  207.      * <code>AlphaComposite</code> object that implements the opaque SRC_IN rule
  208.      * with an alpha of 1.0f.
  209.      * @see #SRC_IN
  210.      */
  211.     public static final AlphaComposite SrcIn    = new AlphaComposite(SRC_IN);
  212.  
  213.     /**
  214.      * <code>AlphaComposite</code> object that implements the opaque DST_IN rule
  215.      * with an alpha of 1.0f.
  216.      * @see #DST_IN
  217.      */
  218.     public static final AlphaComposite DstIn    = new AlphaComposite(DST_IN);
  219.  
  220.     /**
  221.      * <code>AlphaComposite</code> object that implements the opaque SRC_OUT rule
  222.      * with an alpha of 1.0f.
  223.      * @see #SRC_OUT
  224.      */
  225.     public static final AlphaComposite SrcOut    = new AlphaComposite(SRC_OUT);
  226.  
  227.     /**
  228.      * <code>AlphaComposite</code> object that implements the opaque DST_OUT rule
  229.      * with an alpha of 1.0f.
  230.      * @see #DST_OUT
  231.      */
  232.     public static final AlphaComposite DstOut    = new AlphaComposite(DST_OUT);
  233.  
  234.     private static final int MIN_RULE = CLEAR;
  235.     private static final int MAX_RULE = DST_OUT;
  236.  
  237.     float extraAlpha;
  238.     int rule;
  239.  
  240.     private AlphaComposite(int rule) {
  241.     this(rule, 1.0f);
  242.     }
  243.  
  244.     private AlphaComposite(int rule, float alpha) {
  245.     if (alpha < 0.0f || alpha > 1.0f) {
  246.         throw new IllegalArgumentException("alpha value out of range");
  247.     }
  248.     if (rule < MIN_RULE || rule > MAX_RULE) {
  249.         throw new IllegalArgumentException("unknown composite rule");
  250.     }
  251.     this.rule = rule;
  252.     this.extraAlpha = alpha;
  253.     }
  254.  
  255.     /**
  256.      * Creates an <code>AlphaComposite</code> object with the specified rule.
  257.      * @param rule the compositing rule
  258.      */
  259.     public static AlphaComposite getInstance(int rule) {
  260.     switch (rule) {
  261.     case CLEAR:
  262.         return Clear;
  263.     case SRC:
  264.         return Src;
  265.     case SRC_OVER:
  266.         return SrcOver;
  267.     case DST_OVER:
  268.         return DstOver;
  269.     case SRC_IN:
  270.         return SrcIn;
  271.     case DST_IN:
  272.         return DstIn;
  273.     case SRC_OUT:
  274.         return SrcOut;
  275.     case DST_OUT:
  276.         return DstOut;
  277.     default:
  278.         throw new IllegalArgumentException("unknown composite rule");
  279.     }
  280.     }
  281.  
  282.     /**
  283.      * Creates an <code>AlphaComposite</code> object with the specified rule and
  284.      * the constant alpha to multiply with the alpha of the source.
  285.      * The source is multiplied with the specified alpha before being composited
  286.      * with the destination.
  287.      * @param rule the compositing rule
  288.      * @param alpha the constant alpha to be multiplied with the alpha of
  289.      * the source. <code>alpha</code> must be a floating point number in the
  290.      * inclusive range [0.0, 1.0]. 
  291.      */
  292.     public static AlphaComposite getInstance(int rule, float alpha) {
  293.     if (alpha == 1.0f) {
  294.         return getInstance(rule);
  295.     }
  296.     return new AlphaComposite(rule, alpha);
  297.     }
  298.  
  299.     /**
  300.      * Creates a context for the compositing operation.
  301.      * The context contains state that is used in performing
  302.      * the compositing operation.
  303.      * @param srcColorModel  the {@link ColorModel} of the source
  304.      * @param dstColorModel  the <code>ColorModel</code> of the destination
  305.      * @return the <code>CompositeContext</code> object to be used to perform
  306.      * compositing operations.
  307.      */
  308.     public CompositeContext createContext(ColorModel srcColorModel,
  309.                       ColorModel dstColorModel,
  310.                                           RenderingHints hints) {
  311.         return new AlphaCompositeContext(srcColorModel, dstColorModel,
  312.                                          rule, extraAlpha);
  313.     }
  314.  
  315.     /**
  316.      * Returns the alpha value of this<code>AlphaComposite</code>.  If this
  317.      * <code>AlphaComposite</code> does not have an alpha value, 1.0 is returned.
  318.      * @return the alpha value of this <code>AlphaComposite</code>.
  319.      */
  320.     public float getAlpha() {
  321.     return extraAlpha;
  322.     }
  323.  
  324.     /**
  325.      * Returns the compositing rule of this <code>AlphaComposite</code>.
  326.      * @return the compositing rule of this <code>AlphaComposite</code>.
  327.      */
  328.     public int getRule() {
  329.         return rule;
  330.     }
  331.  
  332.     /**
  333.      * Returns the hashcode for this composite.
  334.      * @return      a hash code for this composite.
  335.      */
  336.     public int hashCode() {
  337.     return (Float.floatToIntBits(extraAlpha) * 31 + rule);
  338.     }
  339.  
  340.     /**
  341.      * Tests if the specified {@link Object} is equal to this 
  342.      * <code>AlphaComposite</code> object.
  343.      * @param obj the <code>Object</code> to test for equality
  344.      * @return <code>true</code> if <code>obj</code> equals this
  345.      * <code>AlphaComposite</code>; <code>false</code> otherwise.
  346.      */
  347.     public boolean equals(Object obj) {
  348.         if (!(obj instanceof AlphaComposite)) {
  349.             return false;
  350.         }
  351.  
  352.         AlphaComposite ac = (AlphaComposite) obj;
  353.  
  354.         if (rule != ac.rule) {
  355.             return false;
  356.         }
  357.  
  358.         if (extraAlpha != ac.extraAlpha) {
  359.             return false;
  360.         }
  361.  
  362.         return true;
  363.     }
  364.             
  365. }
  366.