1 /*

     2  * Copyright (c) 1997, 2014, 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 java.awt.image;

    27 

    28 import java.awt.Transparency;

    29 import java.awt.color.ColorSpace;

    30 

    31 /**

    32  * The <code>PackedColorModel</code> class is an abstract

    33  * {@link ColorModel} class that works with pixel values which represent

    34  * color and alpha information as separate samples and which pack all

    35  * samples for a single pixel into a single int, short, or byte quantity.

    36  * This class can be used with an arbitrary {@link ColorSpace}.  The number of

    37  * color samples in the pixel values must be the same as the number of color

    38  * components in the <code>ColorSpace</code>.  There can be a single alpha

    39  * sample.  The array length is always 1 for those methods that use a

    40  * primitive array pixel representation of type <code>transferType</code>.

    41  * The transfer types supported are DataBuffer.TYPE_BYTE,

    42  * DataBuffer.TYPE_USHORT, and DataBuffer.TYPE_INT.

    43  * Color and alpha samples are stored in the single element of the array

    44  * in bits indicated by bit masks.  Each bit mask must be contiguous and

    45  * masks must not overlap.  The same masks apply to the single int

    46  * pixel representation used by other methods.  The correspondence of

    47  * masks and color/alpha samples is as follows:

    48  * <ul>

    49  * <li> Masks are identified by indices running from 0 through

    50  * {@link ColorModel#getNumComponents() getNumComponents} - 1.

    51  * <li> The first

    52  * {@link ColorModel#getNumColorComponents() getNumColorComponents}

    53  * indices refer to color samples.

    54  * <li> If an alpha sample is present, it corresponds the last index.

    55  * <li> The order of the color indices is specified

    56  * by the <code>ColorSpace</code>.  Typically, this reflects the name of

    57  * the color space type (for example, TYPE_RGB), index 0

    58  * corresponds to red, index 1 to green, and index 2 to blue.

    59  * </ul>

    60  * <p>

    61  * The translation from pixel values to color/alpha components for

    62  * display or processing purposes is a one-to-one correspondence of

    63  * samples to components.

    64  * A <code>PackedColorModel</code> is typically used with image data

    65  * that uses masks to define packed samples.  For example, a

    66  * <code>PackedColorModel</code> can be used in conjunction with a

    67  * {@link SinglePixelPackedSampleModel} to construct a

    68  * {@link BufferedImage}.  Normally the masks used by the

    69  * {@link SampleModel} and the <code>ColorModel</code> would be the same.

    70  * However, if they are different, the color interpretation of pixel data is

    71  * done according to the masks of the <code>ColorModel</code>.

    72  * <p>

    73  * A single <code>int</code> pixel representation is valid for all objects

    74  * of this class since it is always possible to represent pixel values

    75  * used with this class in a single <code>int</code>.  Therefore, methods

    76  * that use this representation do not throw an

    77  * <code>IllegalArgumentException</code> due to an invalid pixel value.

    78  * <p>

    79  * A subclass of <code>PackedColorModel</code> is {@link DirectColorModel},

    80  * which is similar to an X11 TrueColor visual.

    81  *

    82  * @see DirectColorModel

    83  * @see SinglePixelPackedSampleModel

    84  * @see BufferedImage

    85  */

    86 

    87 public abstract class PackedColorModel extends ColorModel {

    88     int[] maskArray;

    89     int[] maskOffsets;

    90     float[] scaleFactors;

    91 

    92     /**

    93      * Constructs a <code>PackedColorModel</code> from a color mask array,

    94      * which specifies which bits in an <code>int</code> pixel representation

    95      * contain each of the color samples, and an alpha mask.  Color

    96      * components are in the specified <code>ColorSpace</code>.  The length of

    97      * <code>colorMaskArray</code> should be the number of components in

    98      * the <code>ColorSpace</code>.  All of the bits in each mask

    99      * must be contiguous and fit in the specified number of least significant

   100      * bits of an <code>int</code> pixel representation.  If the

   101      * <code>alphaMask</code> is 0, there is no alpha.  If there is alpha,

   102      * the <code>boolean</code> <code>isAlphaPremultiplied</code> specifies

   103      * how to interpret color and alpha samples in pixel values.  If the

   104      * <code>boolean</code> is <code>true</code>, color samples are assumed

   105      * to have been multiplied by the alpha sample.  The transparency,

   106      * <code>trans</code>, specifies what alpha values can be represented

   107      * by this color model.  The transfer type is the type of primitive

   108      * array used to represent pixel values.

   109      * @param space the specified <code>ColorSpace</code>

   110      * @param bits the number of bits in the pixel values

   111      * @param colorMaskArray array that specifies the masks representing

   112      *         the bits of the pixel values that represent the color

   113      *         components

   114      * @param alphaMask specifies the mask representing

   115      *         the bits of the pixel values that represent the alpha

   116      *         component

   117      * @param isAlphaPremultiplied <code>true</code> if color samples are

   118      *        premultiplied by the alpha sample; <code>false</code> otherwise

   119      * @param trans specifies the alpha value that can be represented by

   120      *        this color model

   121      * @param transferType the type of array used to represent pixel values

   122      * @throws IllegalArgumentException if <code>bits</code> is less than

   123      *         1 or greater than 32

   124      */

   125     public PackedColorModel (ColorSpace space, int bits,

   126                              int[] colorMaskArray, int alphaMask,

   127                              boolean isAlphaPremultiplied,

   128                              int trans, int transferType) {

   129         super(bits, PackedColorModel.createBitsArray(colorMaskArray,

   130                                                      alphaMask),

   131               space, (alphaMask == 0 ? false : true),

   132               isAlphaPremultiplied, trans, transferType);

   133         if (bits < 1 || bits > 32) {

   134             throw new IllegalArgumentException("Number of bits must be between"

   135                                                +" 1 and 32.");

   136         }

   137         maskArray   = new int[numComponents];

   138         maskOffsets = new int[numComponents];

   139         scaleFactors = new float[numComponents];

   140 

   141         for (int i=0; i < numColorComponents; i++) {

   142             // Get the mask offset and #bits

   143             DecomposeMask(colorMaskArray[i], i, space.getName(i));

   144         }

   145         if (alphaMask != 0) {

   146             DecomposeMask(alphaMask, numColorComponents, "alpha");

   147             if (nBits[numComponents-1] == 1) {

   148                 transparency = Transparency.BITMASK;

   149             }

   150         }

   151     }

   152 

   153     /**

   154      * Constructs a <code>PackedColorModel</code> from the specified

   155      * masks which indicate which bits in an <code>int</code> pixel

   156      * representation contain the alpha, red, green and blue color samples.

   157      * Color components are in the specified <code>ColorSpace</code>, which

   158      * must be of type ColorSpace.TYPE_RGB.  All of the bits in each

   159      * mask must be contiguous and fit in the specified number of

   160      * least significant bits of an <code>int</code> pixel representation.  If

   161      * <code>amask</code> is 0, there is no alpha.  If there is alpha,

   162      * the <code>boolean</code> <code>isAlphaPremultiplied</code>

   163      * specifies how to interpret color and alpha samples

   164      * in pixel values.  If the <code>boolean</code> is <code>true</code>,

   165      * color samples are assumed to have been multiplied by the alpha sample.

   166      * The transparency, <code>trans</code>, specifies what alpha values

   167      * can be represented by this color model.

   168      * The transfer type is the type of primitive array used to represent

   169      * pixel values.

   170      * @param space the specified <code>ColorSpace</code>

   171      * @param bits the number of bits in the pixel values

   172      * @param rmask specifies the mask representing

   173      *         the bits of the pixel values that represent the red

   174      *         color component

   175      * @param gmask specifies the mask representing

   176      *         the bits of the pixel values that represent the green

   177      *         color component

   178      * @param bmask specifies the mask representing

   179      *         the bits of the pixel values that represent

   180      *         the blue color component

   181      * @param amask specifies the mask representing

   182      *         the bits of the pixel values that represent

   183      *         the alpha component

   184      * @param isAlphaPremultiplied <code>true</code> if color samples are

   185      *        premultiplied by the alpha sample; <code>false</code> otherwise

   186      * @param trans specifies the alpha value that can be represented by

   187      *        this color model

   188      * @param transferType the type of array used to represent pixel values

   189      * @throws IllegalArgumentException if <code>space</code> is not a

   190      *         TYPE_RGB space

   191      * @see ColorSpace

   192      */

   193     public PackedColorModel(ColorSpace space, int bits, int rmask, int gmask,

   194                             int bmask, int amask,

   195                             boolean isAlphaPremultiplied,

   196                             int trans, int transferType) {

   197         super (bits, PackedColorModel.createBitsArray(rmask, gmask, bmask,

   198                                                       amask),

   199                space, (amask == 0 ? false : true),

   200                isAlphaPremultiplied, trans, transferType);

   201 

   202         if (space.getType() != ColorSpace.TYPE_RGB) {

   203             throw new IllegalArgumentException("ColorSpace must be TYPE_RGB.");

   204         }

   205         maskArray = new int[numComponents];

   206         maskOffsets = new int[numComponents];

   207         scaleFactors = new float[numComponents];

   208 

   209         DecomposeMask(rmask, 0, "red");

   210 

   211         DecomposeMask(gmask, 1, "green");

   212 

   213         DecomposeMask(bmask, 2, "blue");

   214 

   215         if (amask != 0) {

   216             DecomposeMask(amask, 3, "alpha");

   217             if (nBits[3] == 1) {

   218                 transparency = Transparency.BITMASK;

   219             }

   220         }

   221     }

   222 

   223     /**

   224      * Returns the mask indicating which bits in a pixel

   225      * contain the specified color/alpha sample.  For color

   226      * samples, <code>index</code> corresponds to the placement of color

   227      * sample names in the color space.  Thus, an <code>index</code>

   228      * equal to 0 for a CMYK ColorSpace would correspond to

   229      * Cyan and an <code>index</code> equal to 1 would correspond to

   230      * Magenta.  If there is alpha, the alpha <code>index</code> would be:

   231      * <pre>

   232      *      alphaIndex = numComponents() - 1;

   233      * </pre>

   234      * @param index the specified color or alpha sample

   235      * @return the mask, which indicates which bits of the <code>int</code>

   236      *         pixel representation contain the color or alpha sample specified

   237      *         by <code>index</code>.

   238      * @throws ArrayIndexOutOfBoundsException if <code>index</code> is

   239      *         greater than the number of components minus 1 in this

   240      *         <code>PackedColorModel</code> or if <code>index</code> is

   241      *         less than zero

   242      */

   243     final public int getMask(int index) {

   244         return maskArray[index];

   245     }

   246 

   247     /**

   248      * Returns a mask array indicating which bits in a pixel

   249      * contain the color and alpha samples.

   250      * @return the mask array , which indicates which bits of the

   251      *         <code>int</code> pixel

   252      *         representation contain the color or alpha samples.

   253      */

   254     final public int[] getMasks() {

   255         return maskArray.clone();

   256     }

   257 

   258     /*

   259      * A utility function to compute the mask offset and scalefactor,

   260      * store these and the mask in instance arrays, and verify that

   261      * the mask fits in the specified pixel size.

   262      */

   263     private void DecomposeMask(int mask,  int idx, String componentName) {

   264         int off = 0;

   265         int count = nBits[idx];

   266 

   267         // Store the mask

   268         maskArray[idx]   = mask;

   269 

   270         // Now find the shift

   271         if (mask != 0) {

   272             while ((mask & 1) == 0) {

   273                 mask >>>= 1;

   274                 off++;

   275             }

   276         }

   277 

   278         if (off + count > pixel_bits) {

   279             throw new IllegalArgumentException(componentName + " mask "+

   280                                         Integer.toHexString(maskArray[idx])+

   281                                                " overflows pixel (expecting "+

   282                                                pixel_bits+" bits");

   283         }

   284 

   285         maskOffsets[idx] = off;

   286         if (count == 0) {

   287             // High enough to scale any 0-ff value down to 0.0, but not

   288             // high enough to get Infinity when scaling back to pixel bits

   289             scaleFactors[idx] = 256.0f;

   290         } else {

   291             scaleFactors[idx] = 255.0f / ((1 << count) - 1);

   292         }

   293 

   294     }

   295 

   296     /**

   297      * Creates a <code>SampleModel</code> with the specified width and

   298      * height that has a data layout compatible with this

   299      * <code>ColorModel</code>.

   300      * @param w the width (in pixels) of the region of the image data

   301      *          described

   302      * @param h the height (in pixels) of the region of the image data

   303      *          described

   304      * @return the newly created <code>SampleModel</code>.

   305      * @throws IllegalArgumentException if <code>w</code> or

   306      *         <code>h</code> is not greater than 0

   307      * @see SampleModel

   308      */

   309     public SampleModel createCompatibleSampleModel(int w, int h) {

   310         return new SinglePixelPackedSampleModel(transferType, w, h,

   311                                                 maskArray);

   312     }

   313 

   314     /**

   315      * Checks if the specified <code>SampleModel</code> is compatible

   316      * with this <code>ColorModel</code>.  If <code>sm</code> is

   317      * <code>null</code>, this method returns <code>false</code>.

   318      * @param sm the specified <code>SampleModel</code>,

   319      * or <code>null</code>

   320      * @return <code>true</code> if the specified <code>SampleModel</code>

   321      *         is compatible with this <code>ColorModel</code>;

   322      *         <code>false</code> otherwise.

   323      * @see SampleModel

   324      */

   325     public boolean isCompatibleSampleModel(SampleModel sm) {

   326         if (! (sm instanceof SinglePixelPackedSampleModel)) {

   327             return false;

   328         }

   329 

   330         // Must have the same number of components

   331         if (numComponents != sm.getNumBands()) {

   332             return false;

   333         }

   334 

   335         // Transfer type must be the same

   336         if (sm.getTransferType() != transferType) {

   337             return false;

   338         }

   339 

   340         SinglePixelPackedSampleModel sppsm = (SinglePixelPackedSampleModel) sm;

   341         // Now compare the specific masks

   342         int[] bitMasks = sppsm.getBitMasks();

   343         if (bitMasks.length != maskArray.length) {

   344             return false;

   345         }

   346 

   347         /* compare 'effective' masks only, i.e. only part of the mask

   348          * which fits the capacity of the transfer type.

   349          */

   350         int maxMask = (int)((1L << DataBuffer.getDataTypeSize(transferType)) - 1);

   351         for (int i=0; i < bitMasks.length; i++) {

   352             if ((maxMask & bitMasks[i]) != (maxMask & maskArray[i])) {

   353                 return false;

   354             }

   355         }

   356 

   357         return true;

   358     }

   359 

   360     /**

   361      * Returns a {@link WritableRaster} representing the alpha channel of

   362      * an image, extracted from the input <code>WritableRaster</code>.

   363      * This method assumes that <code>WritableRaster</code> objects

   364      * associated with this <code>ColorModel</code> store the alpha band,

   365      * if present, as the last band of image data.  Returns <code>null</code>

   366      * if there is no separate spatial alpha channel associated with this

   367      * <code>ColorModel</code>.  This method creates a new

   368      * <code>WritableRaster</code>, but shares the data array.

   369      * @param raster a <code>WritableRaster</code> containing an image

   370      * @return a <code>WritableRaster</code> that represents the alpha

   371      *         channel of the image contained in <code>raster</code>.

   372      */

   373     public WritableRaster getAlphaRaster(WritableRaster raster) {

   374         if (hasAlpha() == false) {

   375             return null;

   376         }

   377 

   378         int x = raster.getMinX();

   379         int y = raster.getMinY();

   380         int[] band = new int[1];

   381         band[0] = raster.getNumBands() - 1;

   382         return raster.createWritableChild(x, y, raster.getWidth(),

   383                                           raster.getHeight(), x, y,

   384                                           band);

   385     }

   386 

   387     /**

   388      * Tests if the specified <code>Object</code> is an instance

   389      * of <code>PackedColorModel</code> and equals this

   390      * <code>PackedColorModel</code>.

   391      * @param obj the <code>Object</code> to test for equality

   392      * @return <code>true</code> if the specified <code>Object</code>

   393      * is an instance of <code>PackedColorModel</code> and equals this

   394      * <code>PackedColorModel</code>; <code>false</code> otherwise.

   395      */

   396     public boolean equals(Object obj) {

   397         if (!(obj instanceof PackedColorModel)) {

   398             return false;

   399         }

   400 

   401         if (!super.equals(obj)) {

   402             return false;

   403         }

   404 

   405         PackedColorModel cm = (PackedColorModel) obj;

   406         int numC = cm.getNumComponents();

   407         if (numC != numComponents) {

   408             return false;

   409         }

   410         for(int i=0; i < numC; i++) {

   411             if (maskArray[i] != cm.getMask(i)) {

   412                 return false;

   413             }

   414         }

   415         return true;

   416     }

   417 

   418     private final static int[] createBitsArray(int[]colorMaskArray,

   419                                                int alphaMask) {

   420         int numColors = colorMaskArray.length;

   421         int numAlpha = (alphaMask == 0 ? 0 : 1);

   422         int[] arr = new int[numColors+numAlpha];

   423         for (int i=0; i < numColors; i++) {

   424             arr[i] = countBits(colorMaskArray[i]);

   425             if (arr[i] < 0) {

   426                 throw new IllegalArgumentException("Noncontiguous color mask ("

   427                                      + Integer.toHexString(colorMaskArray[i])+

   428                                      "at index "+i);

   429             }

   430         }

   431         if (alphaMask != 0) {

   432             arr[numColors] = countBits(alphaMask);

   433             if (arr[numColors] < 0) {

   434                 throw new IllegalArgumentException("Noncontiguous alpha mask ("

   435                                      + Integer.toHexString(alphaMask));

   436             }

   437         }

   438         return arr;

   439     }

   440 

   441     private final static int[] createBitsArray(int rmask, int gmask, int bmask,

   442                                          int amask) {

   443         int[] arr = new int[3 + (amask == 0 ? 0 : 1)];

   444         arr[0] = countBits(rmask);

   445         arr[1] = countBits(gmask);

   446         arr[2] = countBits(bmask);

   447         if (arr[0] < 0) {

   448             throw new IllegalArgumentException("Noncontiguous red mask ("

   449                                      + Integer.toHexString(rmask));

   450         }

   451         else if (arr[1] < 0) {

   452             throw new IllegalArgumentException("Noncontiguous green mask ("

   453                                      + Integer.toHexString(gmask));

   454         }

   455         else if (arr[2] < 0) {

   456             throw new IllegalArgumentException("Noncontiguous blue mask ("

   457                                      + Integer.toHexString(bmask));

   458         }

   459         if (amask != 0) {

   460             arr[3] = countBits(amask);

   461             if (arr[3] < 0) {

   462                 throw new IllegalArgumentException("Noncontiguous alpha mask ("

   463                                      + Integer.toHexString(amask));

   464             }

   465         }

   466         return arr;

   467     }

   468 

   469     private final static int countBits(int mask) {

   470         int count = 0;

   471         if (mask != 0) {

   472             while ((mask & 1) == 0) {

   473                 mask >>>= 1;

   474             }

   475             while ((mask & 1) == 1) {

   476                 mask >>>= 1;

   477                 count++;

   478             }

   479         }

   480         if (mask != 0) {

   481             return -1;

   482         }

   483         return count;

   484     }

   485 

   486 }