home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / awt / AlphaComposite.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  9.8 KB  |  341 lines
  1. /*
  2.  * @(#)AlphaComposite.java    1.25 98/03/18
  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 class implements the basic alpha compositing rules for combining
  21.  * source and destination pixels to achieve blending and transparency
  22.  * 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,
  29.  * an alpha value of 1.0 (completely opaque) is assumed for all pixels.
  30.  *<p>
  31.  * A constant alpha value can also be specified to be
  32.  * multiplied with the alpha value of the source pixels.
  33.  * <p>
  34.  * The following abbreviations are used in the description of the rules:
  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 which contributes to the output.
  40.  * <li>Fd = fraction of the input Destination Pixel which contributes to the output.
  41.  *<p>
  42.  * The color and alpha components produced by the compositing operation are
  43.  * calculated as follows:
  44.  *<pre>
  45.  *     Cd = Cs*Fs + Cd*Fd
  46.  *     Ad = As*Fs + Ad*Fd
  47.  *</pre>
  48.  * where Fs and Fd are specified by each rule.  The above equations assume
  49.  * that both source and destination pixels have the color components
  50.  * premultiplied by the alpha component.  Similarly, the equations expressed
  51.  * in the definitions of compositing rules below assume premultiplied alpha.
  52.  *<p>
  53.  * For performance reasons, it is
  54.  * preferable that Tiles passed to the compose method of a CompositeContext
  55.  * object created by the AlphaComposite class have premultiplied data.
  56.  * However, if either source or destination Tiles are not premultiplied,
  57.  * appropriate conversions will be performed before and after the compositing
  58.  * operation.
  59.  *<p>
  60.  * The resulting alpha of the compositing operation is stored in
  61.  * the destination if the destination has an alpha channel.
  62.  * Otherwise, the resulting color is divided by the resulting
  63.  * alpha before being stored in the destination and the alpha is discarded
  64.  * (if the alpha value is 0.0, the color values are set to 0.0).
  65.  * @see Composite
  66.  * @see CompositeContext
  67.  * @version 10 Feb 1997
  68.  */
  69.  
  70.  
  71. public final class AlphaComposite implements Composite {
  72.     /**
  73.      * Porter-Duff Clear rule.
  74.      * Both the color and the alpha of destination are cleared.
  75.      * Neither the source nor the destination is used as input.
  76.      *<p>
  77.      * Fs = 0 and Fd = 0, thus:
  78.      *<pre>
  79.      *     Cd = 0
  80.      *     Ad = 0
  81.      *</pre>
  82.      * 
  83.      */
  84.     public static final int    CLEAR        = 1;
  85.  
  86.     /**
  87.      * Porter-Duff Source rule.
  88.      * The source is copied to the destination.
  89.      * The destination is not used as input.
  90.      *<p>
  91.      * Fs = 1 and Fd = 0, thus:
  92.      *<pre>
  93.      *     Cd = Cs
  94.      *     Ad = As
  95.      *</pre>
  96.      */
  97.     public static final int    SRC        = 2;
  98.  
  99.     /**
  100.      * Porter-Duff Source Over Destination rule.
  101.      * The source is composited over the destination.
  102.      *<p>
  103.      * Fs = 1 and Fd = (1-As), thus:
  104.      *<pre>
  105.      *     Cd = Cs + Cd*(1-As)
  106.      *     Ad = As + Ad*(1-As)
  107.      *</pre>
  108.      */
  109.     public static final int    SRC_OVER    = 3;
  110.  
  111.     /**
  112.      * Porter-Duff Destination Over Source rule.
  113.      * The destination is composited over the source and
  114.      * the result replaces the destination.
  115.      *<p>
  116.      * Fs = (1-Ad) and Fd = 1, thus:
  117.      *<pre>
  118.      *     Cd = Cs*(1-Ad) + Cd
  119.      *     Ad = As*(1-Ad) + Ad
  120.      *</pre>
  121.      */
  122.     public static final int    DST_OVER    = 4;
  123.  
  124.     /**
  125.      * Porter-Duff Source In Destination rule.
  126.      * The part of the source lying inside of the destination replaces
  127.      * the destination.
  128.      *<p>
  129.      * Fs = Ad and Fd = 0, thus:
  130.      *<pre>
  131.      *     Cd = Cs*Ad
  132.      *     Ad = As*Ad
  133.      *</pre>
  134.      */
  135.     public static final int    SRC_IN        = 5;
  136.  
  137.     /**
  138.      * Porter-Duff Destination In Source rule.
  139.      * The part of the destination lying inside of the source
  140.      * replaces the destination.
  141.      *<p>
  142.      * Fs = 0 and Fd = As, thus:
  143.      *<pre>
  144.      *     Cd = Cd*As
  145.      *     Ad = Ad*As
  146.      *</pre>
  147.      */
  148.     public static final int    DST_IN        = 6;
  149.  
  150.     /**
  151.      * Porter-Duff Source Held Out By Destination rule.
  152.      * The part of the source lying outside of the destination
  153.      * replaces the destination.
  154.      *<p>
  155.      * Fs = (1-Ad) and Fd = 0, thus:
  156.      *<pre>
  157.      *     Cd = Cs*(1-Ad)
  158.      *     Ad = As*(1-Ad)
  159.      *</pre>
  160.      */
  161.     public static final int    SRC_OUT        = 7;
  162.  
  163.     /**
  164.      * Porter-Duff Destination Held Out By Source rule.
  165.      * The part of the destination lying outside of the source
  166.      * replaces the destination.
  167.      *<p>
  168.      * Fs = 0 and Fd = (1-As), thus:
  169.      *<pre>
  170.      *     Cd = Cd*(1-As)
  171.      *     Ad = Ad*(1-As)
  172.      *</pre>
  173.      */
  174.     public static final int    DST_OUT        = 8;
  175.  
  176.     /**
  177.      * AlphaComposite object which implements the opaque CLEAR rule.
  178.      * @see #CLEAR
  179.      */
  180.     public static final AlphaComposite Clear    = new AlphaComposite(CLEAR);
  181.  
  182.     /**
  183.      * AlphaComposite object which implements the opaque SRC rule.
  184.      * @see #SRC
  185.      */
  186.     public static final AlphaComposite Src    = new AlphaComposite(SRC);
  187.  
  188.     /**
  189.      * AlphaComposite object which implements the opaque SRC_OVER rule.
  190.      * @see #SRC_OVER
  191.      */
  192.     public static final AlphaComposite SrcOver    = new AlphaComposite(SRC_OVER);
  193.  
  194.     /**
  195.      * AlphaComposite object which implements the opaque DST_OVER rule.
  196.      * @see #DST_OVER
  197.      */
  198.     public static final AlphaComposite DstOver    = new AlphaComposite(DST_OVER);
  199.  
  200.     /**
  201.      * AlphaComposite object which implements the opaque SRC_IN rule.
  202.      * @see #SRC_IN
  203.      */
  204.     public static final AlphaComposite SrcIn    = new AlphaComposite(SRC_IN);
  205.  
  206.     /**
  207.      * AlphaComposite object which implements the opaque DST_IN rule.
  208.      * @see #DST_IN
  209.      */
  210.     public static final AlphaComposite DstIn    = new AlphaComposite(DST_IN);
  211.  
  212.     /**
  213.      * AlphaComposite object which implements the opaque SRC_OUT rule.
  214.      * @see #SRC_OUT
  215.      */
  216.     public static final AlphaComposite SrcOut    = new AlphaComposite(SRC_OUT);
  217.  
  218.     /**
  219.      * AlphaComposite object which implements the opaque DST_OUT rule.
  220.      * @see #DST_OUT
  221.      */
  222.     public static final AlphaComposite DstOut    = new AlphaComposite(DST_OUT);
  223.  
  224.     private static final int MIN_RULE = CLEAR;
  225.     private static final int MAX_RULE = DST_OUT;
  226.  
  227.     float extraAlpha;
  228.     int rule;
  229.  
  230.     private AlphaComposite(int rule) {
  231.     this(rule, 1.0f);
  232.     }
  233.  
  234.     private AlphaComposite(int rule, float alpha) {
  235.     if (alpha < 0.0f || alpha > 1.0f) {
  236.         throw new IllegalArgumentException("alpha value out of range");
  237.     }
  238.     if (rule < MIN_RULE || rule > MAX_RULE) {
  239.         throw new IllegalArgumentException("unknown composite rule");
  240.     }
  241.     this.rule = rule;
  242.     this.extraAlpha = alpha;
  243.     }
  244.  
  245.     /**
  246.      * Creates an AlphaComposite object with the given rule.
  247.      * @param    rule Rule for the composition.
  248.      */
  249.     public static AlphaComposite getInstance(int rule) {
  250.     switch (rule) {
  251.     case CLEAR:
  252.         return Clear;
  253.     case SRC:
  254.         return Src;
  255.     case SRC_OVER:
  256.         return SrcOver;
  257.     case DST_OVER:
  258.         return DstOver;
  259.     case SRC_IN:
  260.         return SrcIn;
  261.     case DST_IN:
  262.         return DstIn;
  263.     case SRC_OUT:
  264.         return SrcOut;
  265.     case DST_OUT:
  266.         return DstOut;
  267.     default:
  268.         throw new IllegalArgumentException("unknown composite rule");
  269.     }
  270.     }
  271.  
  272.     /**
  273.      * Creates an AlphaComposite object with the given rule and
  274.      * the constant alpha to multiply with the alpha of the source.
  275.      * The source is multiplied with the given alpha before being composited
  276.      * with the destination.
  277.      * @param rule  Rule for the composition.
  278.      * @param alpha The constant alpha to be multiplied with the alpha of
  279.      * the source. Alpha must be a floating point number in the inclusive
  280.      * range [0.0, 1.0]. 
  281.      */
  282.     public static AlphaComposite getInstance(int rule, float alpha) {
  283.     if (alpha == 1.0f) {
  284.         return getInstance(rule);
  285.     }
  286.     return new AlphaComposite(rule, alpha);
  287.     }
  288.  
  289.     /**
  290.      * Creates a context for the compositing operation.
  291.      * The context contains state that is used in performing
  292.      * the compositing operation.
  293.      * @param srcColorModel  The ColorModel of the source.
  294.      * @param dstColorModel  The ColorModel of the destination.
  295.      * @return The CompositeContext object to be used to perform
  296.      * compositing operations.
  297.      */
  298.     public CompositeContext createContext(ColorModel srcColorModel,
  299.                       ColorModel dstColorModel) {
  300.         return new AlphaCompositeContext(srcColorModel, dstColorModel,
  301.                                          rule, extraAlpha);
  302.     }
  303.  
  304.     /**
  305.      * Returns the additional alpha value that was given when this
  306.      * AlphaComposiste instance was created. If this instance was
  307.      * created without the addtional alpha value, the value
  308.      * 1.0 is returned.
  309.      */
  310.     public float getAlpha() {
  311.     return extraAlpha;
  312.     }
  313.  
  314.     /**
  315.      * Returns the compositing rule that was specified when this
  316.      * AlphaComposiste instance was created.
  317.      */
  318.     public int getRule() {
  319.         return rule;
  320.     }
  321.  
  322.     public boolean equals(Object obj) {
  323.         if (!(obj instanceof AlphaComposite)) {
  324.             return false;
  325.         }
  326.  
  327.         AlphaComposite ac = (AlphaComposite) obj;
  328.  
  329.         if (rule != ac.rule) {
  330.             return false;
  331.         }
  332.  
  333.         if (extraAlpha != ac.extraAlpha) {
  334.             return false;
  335.         }
  336.  
  337.         return true;
  338.     }
  339.             
  340. }
  341.