jface/resource/CompositeImageDescriptor.java

/*******************************************************************************
 * Copyright (c) 2000, 2014 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *     Stephan Wahlbrink - fix for bug 341702 - incorrect mixing of images with alpha channel
 *******************************************************************************/
package org.eclipse.jface.resource;

import java.util.Objects;
import java.util.function.ToIntFunction;

import org.eclipse.swt.graphics.Image;
import org.eclipse.swt.graphics.ImageData;
import org.eclipse.swt.graphics.ImageDataProvider;
import org.eclipse.swt.graphics.PaletteData;
import org.eclipse.swt.graphics.Point;
import org.eclipse.swt.graphics.RGB;

/**
 * Abstract base class for image descriptors that synthesize an image from other
 * images in order to simulate the effect of custom drawing. For example, this
 * could be used to superimpose a red bar dexter symbol across an image to
 * indicate that something was disallowed.
 * <p>
 * Subclasses must implement {@link #getSize()} and {@link #drawImage(ImageDataProvider, int, int)}.
 * Little or no work happens until the image descriptor's image is
 * actually requested by a call to <code>createImage</code> (or to
 * <code>getImageData</code> directly).
 * </p>
 * @see org.eclipse.jface.viewers.DecorationOverlayIcon
 */
public abstract class CompositeImageDescriptor extends ImageDescriptor {

	/**
	 * An {@link ImageDataProvider} that caches the most recently returned
	 * {@link ImageData} object. I.e. consecutive calls to
	 * {@link #getImageData(int)} with the same zoom level are cheap.
	 *
	 * @see #createCachedImageDataProvider(Image)
	 * @see #createCachedImageDataProvider(ImageDescriptor)
	 *
	 * @since 3.13
	 * @noextend This class is not intended to be subclassed by clients.
	 */
	protected abstract class CachedImageDataProvider implements ImageDataProvider {
		/**
		 * Returns the {@link ImageData#width} in points. This method must only
		 * be called within the dynamic scope of a call to
		 * {@link #drawCompositeImage(int, int)}.
		 *
		 * @return the width in points
		 */
		public int getWidth() {
			return computeInPoints(imageData -> imageData.width);
		}

		/**
		 * Returns the {@link ImageData#height} in points. This method must only
		 * be called within the dynamic scope of a call to
		 * {@link #drawCompositeImage(int, int)}.
		 *
		 * @return the height in points
		 */
		public int getHeight() {
			return computeInPoints(imageData -> imageData.height);
		}

		/**
		 * Returns a computed value in SWT logical points. The given function
		 * computes a value in pixels, based on information from the given
		 * ImageData, which is also in pixels. This method must only
		 * be called within the dynamic scope of a call to
		 * {@link #drawCompositeImage(int, int)}.
		 *
		 * @param function
		 *            a function that takes an {@link ImageData} and computes a
		 *            value in pixels
		 * @return the computed value in points
		 */
		public int computeInPoints(ToIntFunction<ImageData> function) {
			ImageData overlayData = getImageData(getZoomLevel());
			if (overlayData != null) {
				int valueInPixels = function.applyAsInt(overlayData);
				return autoScaleDown(valueInPixels);
			}
			overlayData = getImageData(100);
			return function.applyAsInt(overlayData);
		}
	}

	private final class CachedImageImageDataProvider extends CachedImageDataProvider {
		final Image baseImage;
		ImageData cached;
		int cachedZoom;

		private CachedImageImageDataProvider(Image baseImage) {
			this.baseImage = Objects.requireNonNull(baseImage);
		}

		@Override
		public ImageData getImageData(int zoom) {
			if (zoom == cachedZoom) {
				return cached;
			}
			cached = baseImage.getImageData(zoom);
			cachedZoom = zoom;
			return cached;
		}
	}

	private final class CachedDescriptorImageDataProvider extends CachedImageDataProvider {
		final ImageDescriptor descriptor;
		ImageData cached;
		int cachedZoom;

		private CachedDescriptorImageDataProvider(ImageDescriptor descriptor) {
			this.descriptor = Objects.requireNonNull(descriptor);
		}

		@Override
		public ImageData getImageData(int zoom) {
			if (zoom == cachedZoom) {
				return cached;
			}
			ImageData zoomed = descriptor.getImageData(zoom);
			if (zoomed != null) {
				cached = zoomed;
				cachedZoom = zoom;
				return zoomed;
			}
			if (zoom == 100) {
				return ImageDescriptor.getMissingImageDescriptor().getImageData(100);
			}

			ImageData data100 = descriptor.getImageData(100);
			if (data100 != null) {
				// 100% is available => caller will have to scale this one
				cached = data100;
				cachedZoom = 100;
				return null;
			}
			// 100% is not available, but requested zoom != 100
			//  => caller will have to scale missing image descriptor
			return null;
		}
	}

	/**
	 * The image data for this composite image.
	 */
	private ImageData imageData;

	/**
	 * The zoom level for this composite image. Only valid within the dynamic
	 * scope of a call to {@link #drawCompositeImage(int, int)}.
	 */
	private int compositeZoom;

	/**
	 * Constructs an uninitialized composite image.
	 */
	protected CompositeImageDescriptor() {
	}

	/**
	 * Draw the composite images.
	 * <p>
	 * Subclasses must implement this framework method to paint images within
	 * the given bounds using one or more calls to the
	 * {@link #drawImage(ImageDataProvider, int, int)} framework method.
	 * </p>
	 * <p>
	 * Implementers that need to perform computations based on the size of
	 * another image are advised to use one of the
	 * {@link #createCachedImageDataProvider} methods to create a
	 * {@link CachedImageDataProvider} that can serve as
	 * {@link ImageDataProvider}. The {@link CachedImageDataProvider} offers
	 * other interesting methods like {@link CachedImageDataProvider#getWidth()
	 * getWidth()} or
	 * {@link CachedImageDataProvider#computeInPoints(ToIntFunction)
	 * computeInPoints(...)} that can be useful to compute values in points,
	 * based on the resolution-dependent {@link ImageData} that is applicable
	 * for the current drawing operation.
	 * </p>
	 *
	 * @param width
	 *            the width
	 * @param height
	 *            the height
	 * @see #drawImage(ImageDataProvider, int, int)
	 * @see #createCachedImageDataProvider(Image)
	 * @see #createCachedImageDataProvider(ImageDescriptor)
	 */
	protected abstract void drawCompositeImage(int width, int height);

	/**
	 * Draws the given source image data into this composite image at the given
	 * position.
	 * <p>
	 * Call this internal framework method to superimpose another image atop
	 * this composite image.
	 * </p>
	 *
	 * @param src
	 *            the source image data
	 * @param ox
	 *            the x position
	 * @param oy
	 *            the y position
	 * @deprecated Use {@link #drawImage(ImageDataProvider, int, int)} instead.
	 *             Replace the code that created the ImageData by calls to
	 *             {@link #createCachedImageDataProvider(Image)} or
	 *             {@link #createCachedImageDataProvider(ImageDescriptor)} and
	 *             then pass on that provider instead of ImageData objects.
	 *             Replace references to {@link ImageData#width}/height by calls
	 *             to {@link CachedImageDataProvider#getWidth()}/getHeight().
	 */
	@Deprecated
	final protected void drawImage(ImageData src, int ox, int oy) {
		if (src == null) { // wrong hack for https://bugs.eclipse.org/372956 , kept for compatibility with broken client code
			return;
		}
		drawImage(getUnzoomedImageDataProvider(src), ox, oy);
	}

	private static ImageDataProvider getUnzoomedImageDataProvider(ImageData imageData) {
		return zoom -> zoom == 100 ? imageData : null;
	}

	/**
	 * Draws the given source image data into this composite image at the given
	 * position.
	 * <p>
	 * Subclasses call this framework method to superimpose another image atop
	 * this composite image. This method must only be called within the dynamic
	 * scope of a call to {@link #drawCompositeImage(int, int)}.
	 * </p>
	 * <p>
	 * Hint: Use {@link #createCachedImageDataProvider(Image)} or
	 * {@link #createCachedImageDataProvider(ImageDescriptor)} to create an
	 * {@link ImageDataProvider}. To calculate the width and height of the image
	 * that is about to be drawn, you can use
	 * {@link CachedImageDataProvider#getWidth()}/getHeight(). These methods
	 * already return values in SWT points, so that your code doesn't have to
	 * deal with device-dependent pixel coordinates.
	 * </p>
	 *
	 * @param srcProvider
	 *            the source image data provider
	 * @param ox
	 *            the x position
	 * @param oy
	 *            the y position
	 * @since 3.13
	 */
	final protected void drawImage(ImageDataProvider srcProvider, int ox, int oy) {
		ImageData dst = imageData;
		ImageData src = getZoomedImageData(srcProvider);

		PaletteData srcPalette = src.palette;
		ImageData srcMask = null;
		int alphaMask = 0, alphaShift = 0;
		if (src.maskData != null) {
			srcMask = src.getTransparencyMask ();
			if (src.depth == 32) {
				alphaMask = ~(srcPalette.redMask | srcPalette.greenMask | srcPalette.blueMask);
				while (alphaMask != 0 && ((alphaMask >>> alphaShift) & 1) == 0) alphaShift++;
			}
		}
		for (int srcY = 0, dstY = srcY + autoScaleUp(oy); srcY < src.height; srcY++, dstY++) {
			for (int srcX = 0, dstX = srcX + autoScaleUp(ox); srcX < src.width; srcX++, dstX++) {
				if (!(0 <= dstX && dstX < dst.width && 0 <= dstY && dstY < dst.height)) continue;
				int srcPixel = src.getPixel(srcX, srcY);
				int srcAlpha = 255;
				if (src.maskData != null) {
					if (src.depth == 32) {
						srcAlpha = (srcPixel & alphaMask) >>> alphaShift;
						if (srcAlpha == 0) {
							srcAlpha = srcMask.getPixel(srcX, srcY) != 0 ? 255 : 0;
						}
					} else {
						if (srcMask.getPixel(srcX, srcY) == 0) srcAlpha = 0;
					}
				} else if (src.transparentPixel != -1) {
					if (src.transparentPixel == srcPixel) srcAlpha = 0;
				} else if (src.alpha != -1) {
					srcAlpha = src.alpha;
				} else if (src.alphaData != null) {
					srcAlpha = src.getAlpha(srcX, srcY);
				}
				if (srcAlpha == 0) continue;
				int srcRed, srcGreen, srcBlue;
				if (srcPalette.isDirect) {
					srcRed = srcPixel & srcPalette.redMask;
					srcRed = (srcPalette.redShift < 0) ? srcRed >>> -srcPalette.redShift : srcRed << srcPalette.redShift;
					srcGreen = srcPixel & srcPalette.greenMask;
					srcGreen = (srcPalette.greenShift < 0) ? srcGreen >>> -srcPalette.greenShift : srcGreen << srcPalette.greenShift;
					srcBlue = srcPixel & srcPalette.blueMask;
					srcBlue = (srcPalette.blueShift < 0) ? srcBlue >>> -srcPalette.blueShift : srcBlue << srcPalette.blueShift;
				} else {
					RGB rgb = srcPalette.getRGB(srcPixel);
					srcRed = rgb.red;
					srcGreen = rgb.green;
					srcBlue = rgb.blue;
				}
				int dstRed, dstGreen, dstBlue, dstAlpha;
				if (srcAlpha == 255) {
					dstRed = srcRed;
					dstGreen = srcGreen;
					dstBlue= srcBlue;
					dstAlpha = srcAlpha;
				} else {
					int dstPixel = dst.getPixel(dstX, dstY);
					dstAlpha = dst.getAlpha(dstX, dstY);
					dstRed = (dstPixel & 0xFF) >>> 0;
					dstGreen = (dstPixel & 0xFF00) >>> 8;
					dstBlue = (dstPixel & 0xFF0000) >>> 16;
					if (dstAlpha == 255) { // simplified calculations for performance
						dstRed += (srcRed - dstRed) * srcAlpha / 255;
						dstGreen += (srcGreen - dstGreen) * srcAlpha / 255;
						dstBlue += (srcBlue - dstBlue) * srcAlpha / 255;
					} else {
						// See Porter T., Duff T. 1984. "Compositing Digital Images".
						// Computer Graphics 18 (3): 253-259.
						dstRed = srcRed * srcAlpha * 255 + dstRed * dstAlpha * (255 - srcAlpha);
						dstGreen = srcGreen * srcAlpha * 255 + dstGreen * dstAlpha * (255 - srcAlpha);
						dstBlue = srcBlue * srcAlpha * 255 + dstBlue * dstAlpha * (255 - srcAlpha);
						dstAlpha = srcAlpha * 255 + dstAlpha * (255 - srcAlpha);
						if (dstAlpha != 0) { // if both original alphas == 0, then all colors are 0
							dstRed /= dstAlpha;
							dstGreen /= dstAlpha;
							dstBlue /= dstAlpha;
							dstAlpha /= 255;
						}
					}
				}
				dst.setPixel(dstX, dstY, ((dstRed & 0xFF) << 0) | ((dstGreen & 0xFF) << 8) | ((dstBlue & 0xFF) << 16));
				dst.setAlpha(dstX, dstY, dstAlpha);
			}
		}
	}

	/**
	 * @deprecated Use {@link #getImageData(int)} instead.
	 */
	@Deprecated
	@Override
	public ImageData getImageData() {
		return getImageData(100);
	}

	@Override
	public ImageData getImageData(int zoom) {
		if (!supportsZoomLevel(zoom)) {
			return null;
		}
		/* Assign before calling getSize(), just in case an implementer of
		 * getSize() already uses a CachedImageDataProvider. */
		compositeZoom = zoom;

		Point size = getSize();

		/* Create a 24 bit image data with alpha channel */
		imageData = new ImageData(scaleUp(size.x, zoom), scaleUp(size.y, zoom), 24,
				new PaletteData(0xFF, 0xFF00, 0xFF0000));
		imageData.alphaData = new byte[imageData.width * imageData.height];

		drawCompositeImage(size.x, size.y);

		/* Detect minimum transparency */
		boolean transparency = false;
		byte[] alphaData = imageData.alphaData;
		for (byte element : alphaData) {
			int alpha = element & 0xFF;
			if (!(alpha == 0 || alpha == 255)) {
				/* Full alpha channel transparency */
				return imageData;
			}
			if (!transparency && alpha == 0) transparency = true;
		}
		if (transparency) {
			/* Reduce to 1-bit alpha channel transparency */
			PaletteData palette = new PaletteData(new RGB[]{new RGB(0, 0, 0), new RGB(255, 255, 255)});
			ImageData mask = new ImageData(imageData.width, imageData.height, 1, palette);
			for (int y = 0; y < mask.height; y++) {
				for (int x = 0; x < mask.width; x++) {
					mask.setPixel(x, y, imageData.getAlpha(x, y) == 255 ? 1 : 0);
				}
			}
		} else {
			/* no transparency */
			imageData.alphaData = null;
		}
		return imageData;
	}


	/**
	 * Return the transparent pixel for the receiver.
	 * <strong>NOTE</strong> This value is not currently in use in the
	 * default implementation.
	 * @return int
	 * @since 3.3
	 */
	protected int getTransparentPixel() {
		return 0;
	}

	/**
	 * Return the size of this composite image.
	 * <p>
	 * Subclasses must implement this framework method.
	 * </p>
	 *
	 * @return the x and y size of the image expressed as a point object
	 */
	protected abstract Point getSize();

	/**
	 * Do not call this method! Behavior is unspecified.
	 *
	 * @param imageData unspecified
	 * @since 3.3
	 * @deprecated This method doesn't make sense and should never have been
	 *             made API.
	 */
	@Deprecated
	protected void setImageData(ImageData imageData) {
		this.imageData = imageData;
	}

	/**
	 * Returns whether the given zoom level is supported by this
	 * CompositeImageDescriptor.
	 *
	 * @param zoom
	 *            the zoom level
	 * @return whether the given zoom level is supported. Must return true for
	 *         {@code zoom == 100}.
	 * @since 3.13
	 */
	protected boolean supportsZoomLevel(int zoom) {
		// Currently only support integer zoom levels, because getZoomedImageData(..)
		// suffers from Bug 97506: [HiDPI] ImageData.scaledTo() should use a
		// better interpolation method.
		return zoom > 0 && zoom % 100 == 0;
	}

	private ImageData getZoomedImageData(ImageDataProvider srcProvider) {
		ImageData src = srcProvider.getImageData(compositeZoom);
		if (src == null) {
			ImageData src100 = srcProvider.getImageData(100);
			src = src100.scaledTo(autoScaleUp(src100.width), autoScaleUp(src100.height));
		}
		return src;
	}

	/**
	 * Returns the current zoom level.
	 * <p>
	 * <b>Important:</b> This method must only be called within the dynamic scope of a call to
	 * {@link #drawCompositeImage(int, int)}.
	 * </p>
	 *
	 * @return The zoom level in % of the standard resolution (which is 1
	 *         physical monitor pixel == 1 SWT logical point). Typically 100,
	 *         150, or 200.
	 * @since 3.13
	 */
	protected int getZoomLevel() {
		return compositeZoom;
	}

	/**
	 * Converts a value in high-DPI pixels to the corresponding value in SWT points.
	 * <p>
	 * This method must only be called within the dynamic
	 * scope of a call to {@link #drawCompositeImage(int, int)}.
	 * </p>
	 *
	 * @param pixels a value in high-DPI pixels
	 * @return corresponding value in SWT points
	 * @since 3.13
	 */
	protected int autoScaleDown(int pixels) {
		// @see SWT's internal DPIUtil#autoScaleDown(int)
		if (compositeZoom == 100) {
			return pixels;
		}
		float scaleFactor = compositeZoom / 100f;
		return Math.round(pixels / scaleFactor);
	}

	/**
	 * Converts a value in SWT points to the corresponding value in high-DPI pixels.
	 * <p>
	 * This method must only be called within the dynamic
	 * scope of a call to {@link #drawCompositeImage(int, int)}.
	 * </p>
	 *
	 * @param points a value in SWT points
	 * @return corresponding value in high-DPI pixels
	 * @since 3.13
	 */
	protected int autoScaleUp(int points) {
		// @see SWT's internal DPIUtil#autoScaleUp(int)
		return scaleUp(points, compositeZoom);
	}

	/**
	 * Creates a new {@link CachedImageDataProvider} that is backed by the given
	 * image. This method and the resulting cached image data
	 * provider are only intended to be used within the dynamic scope of a call
	 * to {@link #drawCompositeImage(int, int)}.
	 *
	 * @param image
	 *            the image, must not be null
	 * @return the new cached image provider
	 * @since 3.13
	 */
	protected CachedImageDataProvider createCachedImageDataProvider(Image image) {
		return new CachedImageImageDataProvider(image);
	}

	/**
	 * Creates a new {@link CachedImageDataProvider} that is backed by the given
	 * image descriptor. This method and the resulting cached image data
	 * provider are only intended to be used within the dynamic scope of a call
	 * to {@link #drawCompositeImage(int, int)}.
	 * <p>
	 * The provider returns {@link ImageDescriptor#getMissingImageDescriptor()}
	 * if the image descriptor unexpectedly provides a null image data at zoom
	 * == 100.
	 *
	 * @param imageDescriptor
	 *            the image descriptor, must not be null
	 * @return the new cached image provider
	 * @since 3.13
	 */
	protected CachedImageDataProvider createCachedImageDataProvider(ImageDescriptor imageDescriptor) {
		return new CachedDescriptorImageDataProvider(imageDescriptor);
	}

	private static int scaleUp(int points, int zoom) {
		if (zoom == 100) {
			return points;
		}
		float scaleFactor = zoom / 100f;
		return Math.round(points * scaleFactor);
	}
}