root/dwt/graphics/ImageData.d

/*******************************************************************************
 * Copyright (c) 2000, 2008 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 * Port to the D programming language:
 *     Frank Benoit <benoit@tionex.de>
 *******************************************************************************/
module dwt.graphics.ImageData;


import dwt.graphics.PaletteData;
import dwt.graphics.RGB;
import dwt.graphics.Image;
import dwt.graphics.GC;
import dwt.graphics.Device;
import dwt.graphics.ImageDataLoader;
import dwt.DWT;
import dwt.internal.CloneableCompatibility;

public import dwt.dwthelper.InputStream;
import dwt.dwthelper.System;
import dwt.dwthelper.utils;


/**
 * Instances of this class are device-independent descriptions
 * of images. They are typically used as an intermediate format
 * between loading from or writing to streams and creating an
 * <code>Image</code>.
 * <p>
 * Note that the public fields <code>x</code>, <code>y</code>,
 * <code>disposalMethod</code> and <code>delayTime</code> are
 * typically only used when the image is in a set of images used
 * for animation.
 * </p>
 *
 * @see Image
 * @see ImageLoader
 * @see <a href="http://www.eclipse.org/swt/snippets/#image">ImageData snippets</a>
 * @see <a href="http://www.eclipse.org/swt/examples.php">DWT Example: ImageAnalyzer</a>
 * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
 */

public final class ImageData : CloneableCompatibility {

    /**
     * The width of the image, in pixels.
     */
    public int width;

    /**
     * The height of the image, in pixels.
     */
    public int height;

    /**
     * The color depth of the image, in bits per pixel.
     * <p>
     * Note that a depth of 8 or less does not necessarily
     * mean that the image is palette indexed, or
     * conversely that a depth greater than 8 means that
     * the image is direct color.  Check the associated
     * PaletteData's isDirect field for such determinations.
     */
    public int depth;

    /**
     * The scanline padding.
     * <p>
     * If one scanline of the image is not a multiple of
     * this number, it will be padded with zeros until it is.
     * </p>
     */
    public int scanlinePad;

    /**
     * The number of bytes per scanline.
     * <p>
     * This is a multiple of the scanline padding.
     * </p>
     */
    public int bytesPerLine;

    /**
     * The pixel data of the image.
     * <p>
     * Note that for 16 bit depth images the pixel data is stored
     * in least significant byte order; however, for 24bit and
     * 32bit depth images the pixel data is stored in most
     * significant byte order.
     * </p>
     */
    public byte[] data;

    /**
     * The color table for the image.
     */
    public PaletteData palette;

    /**
     * The transparent pixel.
     * <p>
     * Pixels with this value are transparent.
     * </p><p>
     * The default is -1 which means 'no transparent pixel'.
     * </p>
     */
    public int transparentPixel;

    /**
     * An icon-specific field containing the data from the icon mask.
     * <p>
     * This is a 1 bit bitmap stored with the most significant
     * bit first.  The number of bytes per scanline is
     * '((width + 7) / 8 + (maskPad - 1)) / maskPad * maskPad'.
     * </p><p>
     * The default is null which means 'no transparency mask'.
     * </p>
     */
    public byte[] maskData;

    /**
     * An icon-specific field containing the scanline pad of the mask.
     * <p>
     * If one scanline of the transparency mask is not a
     * multiple of this number, it will be padded with zeros until
     * it is.
     * </p>
     */
    public int maskPad;

    /**
     * The alpha data of the image.
     * <p>
     * Every pixel can have an <em>alpha blending</em> value that
     * varies from 0, meaning fully transparent, to 255 meaning
     * fully opaque.  The number of bytes per scanline is
     * 'width'.
     * </p>
     */
    public byte[] alphaData;

    /**
     * The global alpha value to be used for every pixel.
     * <p>
     * If this value is set, the <code>alphaData</code> field
     * is ignored and when the image is rendered each pixel
     * will be blended with the background an amount
     * proportional to this value.
     * </p><p>
     * The default is -1 which means 'no global alpha value'
     * </p>
     */
    public int alpha;

    /**
     * The type of file from which the image was read.
     *
     * It is expressed as one of the following values:
     * <dl>
     * <dt><code>IMAGE_BMP</code></dt>
     * <dd>Windows BMP file format, no compression</dd>
     * <dt><code>IMAGE_BMP_RLE</code></dt>
     * <dd>Windows BMP file format, RLE compression if appropriate</dd>
     * <dt><code>IMAGE_GIF</code></dt>
     * <dd>GIF file format</dd>
     * <dt><code>IMAGE_ICO</code></dt>
     * <dd>Windows ICO file format</dd>
     * <dt><code>IMAGE_JPEG</code></dt>
     * <dd>JPEG file format</dd>
     * <dt><code>IMAGE_PNG</code></dt>
     * <dd>PNG file format</dd>
     * </dl>
     */
    public int type;

    /**
     * The x coordinate of the top left corner of the image
     * within the logical screen (this field corresponds to
     * the GIF89a Image Left Position value).
     */
    public int x;

    /**
     * The y coordinate of the top left corner of the image
     * within the logical screen (this field corresponds to
     * the GIF89a Image Top Position value).
     */
    public int y;

    /**
     * A description of how to dispose of the current image
     * before displaying the next.
     *
     * It is expressed as one of the following values:
     * <dl>
     * <dt><code>DM_UNSPECIFIED</code></dt>
     * <dd>disposal method not specified</dd>
     * <dt><code>DM_FILL_NONE</code></dt>
     * <dd>do nothing - leave the image in place</dd>
     * <dt><code>DM_FILL_BACKGROUND</code></dt>
     * <dd>fill with the background color</dd>
     * <dt><code>DM_FILL_PREVIOUS</code></dt>
     * <dd>restore the previous picture</dd>
     * </dl>
     * (this field corresponds to the GIF89a Disposal Method value)
     */
    public int disposalMethod;

    /**
     * The time to delay before displaying the next image
     * in an animation (this field corresponds to the GIF89a
     * Delay Time value).
     */
    public int delayTime;

    /**
     * Arbitrary channel width data to 8-bit conversion table.
     */
    private static byte[][] ANY_TO_EIGHT;
    private static byte[] ONE_TO_ONE_MAPPING;

    private static bool static_this_completed = false;
    private static void static_this() {
        if( static_this_completed ) return;
        synchronized {
            if( static_this_completed ) return;
            ANY_TO_EIGHT = new byte[][](9);
            for (int b = 0; b < 9; ++b) {
                byte[] data = ANY_TO_EIGHT[b] = new byte[1 << b];
                if (b is 0) continue;
                int inc = 0;
                for (int bit = 0x10000; (bit >>= b) !is 0;) inc |= bit;
                for (int v = 0, p = 0; v < 0x10000; v+= inc) data[p++] = cast(byte)(v >> 8);
            }
            ONE_TO_ONE_MAPPING = ANY_TO_EIGHT[8];
            static_this_completed = true;
        }
    }

    /**
     * Scaled 8x8 Bayer dither matrix.
     */
    static const int[][] DITHER_MATRIX = [
        [ 0xfc0000, 0x7c0000, 0xdc0000, 0x5c0000, 0xf40000, 0x740000, 0xd40000, 0x540000 ],
        [ 0x3c0000, 0xbc0000, 0x1c0000, 0x9c0000, 0x340000, 0xb40000, 0x140000, 0x940000 ],
        [ 0xcc0000, 0x4c0000, 0xec0000, 0x6c0000, 0xc40000, 0x440000, 0xe40000, 0x640000 ],
        [ 0x0c0000, 0x8c0000, 0x2c0000, 0xac0000, 0x040000, 0x840000, 0x240000, 0xa40000 ],
        [ 0xf00000, 0x700000, 0xd00000, 0x500000, 0xf80000, 0x780000, 0xd80000, 0x580000 ],
        [ 0x300000, 0xb00000, 0x100000, 0x900000, 0x380000, 0xb80000, 0x180000, 0x980000 ],
        [ 0xc00000, 0x400000, 0xe00000, 0x600000, 0xc80000, 0x480000, 0xe80000, 0x680000 ],
        [ 0x000000, 0x800000, 0x200000, 0xa00000, 0x080000, 0x880000, 0x280000, 0xa80000 ]
    ];

/**
 * Constructs a new, empty ImageData with the given width, height,
 * depth and palette. The data will be initialized to an (all zero)
 * array of the appropriate size.
 *
 * @param width the width of the image
 * @param height the height of the image
 * @param depth the depth of the image
 * @param palette the palette of the image (must not be null)
 *
 * @exception IllegalArgumentException <ul>
 *    <li>ERROR_INVALID_ARGUMENT - if the width or height is negative, or if the depth is not
 *          one of 1, 2, 4, 8, 16, 24 or 32</li>
 *    <li>ERROR_NULL_ARGUMENT - if the palette is null</li>
 * </ul>
 */
public this(int width, int height, int depth, PaletteData palette) {
    this(width, height, depth, palette,
        4, null, 0, null,
        null, -1, -1, DWT.IMAGE_UNDEFINED,
        0, 0, 0, 0);
}

/**
 * Constructs a new, empty ImageData with the given width, height,
 * depth, palette, scanlinePad and data.
 *
 * @param width the width of the image
 * @param height the height of the image
 * @param depth the depth of the image
 * @param palette the palette of the image
 * @param scanlinePad the padding of each line, in bytes
 * @param data the data of the image
 *
 * @exception IllegalArgumentException <ul>
 *    <li>ERROR_INVALID_ARGUMENT - if the width or height is negative, or if the depth is not
 *          one of 1, 2, 4, 8, 16, 24 or 32, or the data array is too small to contain the image data</li>
 *    <li>ERROR_NULL_ARGUMENT - if the palette or data is null</li>
 *    <li>ERROR_CANNOT_BE_ZERO - if the scanlinePad is zero</li>
 * </ul>
 */
public this(int width, int height, int depth, PaletteData palette, int scanlinePad, byte[] data) {
    this(width, height, depth, palette,
        scanlinePad, checkData(data), 0, null,
        null, -1, -1, DWT.IMAGE_UNDEFINED,
        0, 0, 0, 0);
}

/**
 * Constructs an <code>ImageData</code> loaded from the specified
 * input stream. Throws an error if an error occurs while loading
 * the image, or if the image has an unsupported type.  Application
 * code is still responsible for closing the input stream.
 * <p>
 * This constructor is provided for convenience when loading a single
 * image only. If the stream contains multiple images, only the first
 * one will be loaded. To load multiple images, use
 * <code>ImageLoader.load()</code>.
 * </p><p>
 * This constructor may be used to load a resource as follows:
 * </p>
 * <pre>
 *     static ImageData loadImageData (Class clazz, String string) {
 *          InputStream stream = clazz.getResourceAsStream (string);
 *          if (stream is null) return null;
 *          ImageData imageData = null;
 *          try {
 *               imageData = new ImageData (stream);
 *          } catch (DWTException ex) {
 *          } finally {
 *               try {
 *                    stream.close ();
 *               } catch (IOException ex) {}
 *          }
 *          return imageData;
 *     }
 * </pre>
 *
 * @param stream the input stream to load the image from (must not be null)
 *
 * @exception IllegalArgumentException <ul>
 *    <li>ERROR_NULL_ARGUMENT - if the stream is null</li>
 * </ul>
 * @exception DWTException <ul>
 *    <li>ERROR_IO - if an IO error occurs while reading from the stream</li>
 *    <li>ERROR_INVALID_IMAGE - if the image stream contains invalid data</li>
 *    <li>ERROR_UNSUPPORTED_FORMAT - if the image stream contains an unrecognized format</li>
 * </ul>
 *
 * @see ImageLoader#load(InputStream)
 */
public this(InputStream stream) {
    ImageData[] data = ImageDataLoader.load(stream);
    if (data.length < 1) DWT.error(DWT.ERROR_INVALID_IMAGE);
    ImageData i = data[0];
    setAllFields(
        i.width,
        i.height,
        i.depth,
        i.scanlinePad,
        i.bytesPerLine,
        i.data,
        i.palette,
        i.transparentPixel,
        i.maskData,
        i.maskPad,
        i.alphaData,
        i.alpha,
        i.type,
        i.x,
        i.y,
        i.disposalMethod,
        i.delayTime);
}

/**
 * Constructs an <code>ImageData</code> loaded from a file with the
 * specified name. Throws an error if an error occurs loading the
 * image, or if the image has an unsupported type.
 * <p>
 * This constructor is provided for convenience when loading a single
 * image only. If the file contains multiple images, only the first
 * one will be loaded. To load multiple images, use
 * <code>ImageLoader.load()</code>.
 * </p>
 *
 * @param filename the name of the file to load the image from (must not be null)
 *
 * @exception IllegalArgumentException <ul>
 *    <li>ERROR_NULL_ARGUMENT - if the file name is null</li>
 * </ul>
 * @exception DWTException <ul>
 *    <li>ERROR_IO - if an IO error occurs while reading from the file</li>
 *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data</li>
 *    <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li>
 * </ul>
 */
public this(String filename) {
    ImageData[] data = ImageDataLoader.load(filename);
    if (data.length < 1) DWT.error(DWT.ERROR_INVALID_IMAGE);
    ImageData i = data[0];
    setAllFields(
        i.width,
        i.height,
        i.depth,
        i.scanlinePad,
        i.bytesPerLine,
        i.data,
        i.palette,
        i.transparentPixel,
        i.maskData,
        i.maskPad,
        i.alphaData,
        i.alpha,
        i.type,
        i.x,
        i.y,
        i.disposalMethod,
        i.delayTime);
}

/**
 * Prevents uninitialized instances from being created outside the package.
 */
private this() {
}

/**
 * Constructs an image data by giving values for all non-computable fields.
 * <p>
 * This method is for internal use, and is not described further.
 * </p>
 */
this(
    int width, int height, int depth, PaletteData palette,
    int scanlinePad, byte[] data, int maskPad, byte[] maskData,
    byte[] alphaData, int alpha, int transparentPixel, int type,
    int x, int y, int disposalMethod, int delayTime)
{
    if (palette is null) DWT.error(DWT.ERROR_NULL_ARGUMENT);
    if (!(depth is 1 || depth is 2 || depth is 4 || depth is 8
        || depth is 16 || depth is 24 || depth is 32)) {
        DWT.error(DWT.ERROR_INVALID_ARGUMENT);
    }
    if (width <= 0 || height <= 0) {
        DWT.error(DWT.ERROR_INVALID_ARGUMENT);
    }
    if (scanlinePad is 0) DWT.error (DWT.ERROR_CANNOT_BE_ZERO);

    int bytesPerLine = (((width * depth + 7) / 8) + (scanlinePad - 1))
        / scanlinePad * scanlinePad;
    
    /*
     * When the image is being loaded from a PNG, we need to use the theoretical minimum
     * number of bytes per line to check whether there is enough data, because the actual
     * number of bytes per line is calculated based on the given depth, which may be larger
     * than the actual depth of the PNG.
     */
    int minBytesPerLine = type is DWT.IMAGE_PNG ? ((((width + 7) / 8) + 3) / 4) * 4 : bytesPerLine;
    if (data !is null && data.length < minBytesPerLine * height) {
        DWT.error(DWT.ERROR_INVALID_ARGUMENT);
    }
    setAllFields(
        width,
        height,
        depth,
        scanlinePad,
        bytesPerLine,
        data !is null ? data : new byte[bytesPerLine * height],
        palette,
        transparentPixel,
        maskData,
        maskPad,
        alphaData,
        alpha,
        type,
        x,
        y,
        disposalMethod,
        delayTime);
}

/**
 * Initializes all fields in the receiver. This method must be called
 * by all public constructors to ensure that all fields are initialized
 * for a new ImageData object. If a new field is added to the class,
 * then it must be added to this method.
 * <p>
 * This method is for internal use, and is not described further.
 * </p>
 */
void setAllFields(int width, int height, int depth, int scanlinePad,
    int bytesPerLine, byte[] data, PaletteData palette, int transparentPixel,
    byte[] maskData, int maskPad, byte[] alphaData, int alpha,
    int type, int x, int y, int disposalMethod, int delayTime) {

    this.width = width;
    this.height = height;
    this.depth = depth;
    this.scanlinePad = scanlinePad;
    this.bytesPerLine = bytesPerLine;
    this.data = data;
    this.palette = palette;
    this.transparentPixel = transparentPixel;
    this.maskData = maskData;
    this.maskPad = maskPad;
    this.alphaData = alphaData;
    this.alpha = alpha;
    this.type = type;
    this.x = x;
    this.y = y;
    this.disposalMethod = disposalMethod;
    this.delayTime = delayTime;
}

/**
 * Invokes internal DWT functionality to create a new instance of
 * this class.
 * <p>
 * <b>IMPORTANT:</b> This method is <em>not</em> part of the public
 * API for <code>ImageData</code>. It is marked public only so that it
 * can be shared within the packages provided by DWT. It is subject
 * to change without notice, and should never be called from
 * application code.
 * </p>
 * <p>
 * This method is for internal use, and is not described further.
 * </p>
 */
public static ImageData internal_new(
    int width, int height, int depth, PaletteData palette,
    int scanlinePad, byte[] data, int maskPad, byte[] maskData,
    byte[] alphaData, int alpha, int transparentPixel, int type,
    int x, int y, int disposalMethod, int delayTime)
{
    return new ImageData(
        width, height, depth, palette, scanlinePad, data, maskPad, maskData,
        alphaData, alpha, transparentPixel, type, x, y, disposalMethod, delayTime);
}

ImageData colorMaskImage(int pixel) {
    ImageData mask = new ImageData(width, height, 1, bwPalette(),
        2, null, 0, null, null, -1, -1, DWT.IMAGE_UNDEFINED,
        0, 0, 0, 0);
    int[] row = new int[width];
    for (int y = 0; y < height; y++) {
        getPixels(0, y, width, row, 0);
        for (int i = 0; i < width; i++) {
            if (pixel !is -1 && row[i] is pixel) {
                row[i] = 0;
            } else {
                row[i] = 1;
            }
        }
        mask.setPixels(0, y, width, row, 0);
    }
    return mask;
}

static byte[] checkData(byte [] data) {
    if (data is null) DWT.error(DWT.ERROR_NULL_ARGUMENT);
    return data;
}

/**
 * Returns a new instance of the same class as the receiver,
 * whose slots have been filled in with <em>copies</em> of
 * the values in the slots of the receiver. That is, the
 * returned object is a <em>deep copy</em> of the receiver.
 *
 * @return a copy of the receiver.
 */
public Object clone() {
    byte[] cloneData = new byte[data.length];
    System.arraycopy(data, 0, cloneData, 0, data.length);
    byte[] cloneMaskData = null;
    if (maskData !is null) {
        cloneMaskData = new byte[maskData.length];
        System.arraycopy(maskData, 0, cloneMaskData, 0, maskData.length);
    }
    byte[] cloneAlphaData = null;
    if (alphaData !is null) {
        cloneAlphaData = new byte[alphaData.length];
        System.arraycopy(alphaData, 0, cloneAlphaData, 0, alphaData.length);
    }
    return new ImageData(
        width,
        height,
        depth,
        palette,
        scanlinePad,
        cloneData,
        maskPad,
        cloneMaskData,
        cloneAlphaData,
        alpha,
        transparentPixel,
        type,
        x,
        y,
        disposalMethod,
        delayTime);
}

/**
 * Returns the alpha value at offset <code>x</code> in
 * scanline <code>y</code> in the receiver's alpha data.
 * The alpha value is between 0 (transparent) and
 * 255 (opaque).
 *
 * @param x the x coordinate of the pixel to get the alpha value of
 * @param y the y coordinate of the pixel to get the alpha value of
 * @return the alpha value at the given coordinates
 *
 * @exception IllegalArgumentException <ul>
 *    <li>ERROR_INVALID_ARGUMENT - if either argument is out of range</li>
 * </ul>
 */
public int getAlpha(int x, int y) {
    if (x >= width || y >= height || x < 0 || y < 0) DWT.error(DWT.ERROR_INVALID_ARGUMENT);

    if (alphaData is null) return 255;
    return alphaData[y * width + x] & 0xFF;
}

/**
 * Returns <code>getWidth</code> alpha values starting at offset
 * <code>x</code> in scanline <code>y</code> in the receiver's alpha
 * data starting at <code>startIndex</code>. The alpha values
 * are unsigned, between <code>(byte)0</code> (transparent) and
 * <code>(byte)255</code> (opaque).
 *
 * @param x the x position of the pixel to begin getting alpha values
 * @param y the y position of the pixel to begin getting alpha values
 * @param getWidth the width of the data to get
 * @param alphas the buffer in which to put the alpha values
 * @param startIndex the offset into the image to begin getting alpha values
 *
 * @exception IndexOutOfBoundsException if getWidth is too large
 * @exception IllegalArgumentException <ul>
 *    <li>ERROR_NULL_ARGUMENT - if pixels is null</li>
 *    <li>ERROR_INVALID_ARGUMENT - if x or y is out of bounds</li>
 *    <li>ERROR_INVALID_ARGUMENT - if getWidth is negative</li>
 * </ul>
 */
public void getAlphas(int x, int y, int getWidth, byte[] alphas, int startIndex) {
    if (alphas is null) DWT.error(DWT.ERROR_NULL_ARGUMENT);
    if (getWidth < 0 || x >= width || y >= height || x < 0 || y < 0) DWT.error(DWT.ERROR_INVALID_ARGUMENT);
    if (getWidth is 0) return;

    if (alphaData is null) {
        int endIndex = startIndex + getWidth;
        for (int i = startIndex; i < endIndex; i++) {
            alphas[i] = cast(byte)255;
        }
        return;
    }
    // may throw an IndexOutOfBoundsException
    System.arraycopy(alphaData, y * width + x, alphas, startIndex, getWidth);
}

/**
 * Returns the pixel value at offset <code>x</code> in
 * scanline <code>y</code> in the receiver's data.
 *
 * @param x the x position of the pixel to get
 * @param y the y position of the pixel to get
 * @return the pixel at the given coordinates
 *
 * @exception IllegalArgumentException <ul>
 *    <li>ERROR_INVALID_ARGUMENT - if either argument is out of bounds</li>
 * </ul>
 * @exception DWTException <ul>
 *    <li>ERROR_UNSUPPORTED_DEPTH if the depth is not one of 1, 2, 4, 8, 16, 24 or 32</li>
 * </ul>
 */
public int getPixel(int x, int y) {
    if (x >= width || y >= height || x < 0 || y < 0) DWT.error(DWT.ERROR_INVALID_ARGUMENT);
    int index;
    int theByte;