/*
 * Java
 *
 * Copyright 2020-2024 MicroEJ Corp. All rights reserved.
 * This library is provided in source code for use, modification and test, subject to license terms.
 * Any modification of the source code will break MicroEJ Corp. warranties on the whole library.
 * This document has been released and published by E-S-R consortium, a non-profit entity.
 * To learn more about E-S-R consortium, please visit http://www.e-s-r.net/.
 * The matter contained in this document is not subject to copyright; you are free to use it for any purpose, for more information see E-S-R consortium policies.
 */
package ej.microui.display;

import ej.microui.MicroUIException;

/**
 * A <code>BufferedImage</code> represents a mutable image backed by a pixel buffer.
 * <p>
 * The constructor of this class allows to create an image with given dimensions and format.
 */
public class BufferedImage extends ResourceImage {

	/**
	 * Creates a buffered image with the same format as the display.
	 * <p>
	 * Equivalent to calling {@link #BufferedImage(int, int, Format)} with {@link Format#DISPLAY} as parameter.
	 * <p>
	 * The output format of the new image matches the pixel organization (layout, depth, etc.) of the default display.
	 *
	 * @param width
	 *            the width of the new image, in pixels.
	 * @param height
	 *            the height of the new image, in pixels.
	 * @throws IllegalArgumentException
	 *             if either <code>width</code> or <code>height</code> is negative or zero.
	 * @throws MicroUIException
	 *             if the image could not be created.
	 * @throws MicroUIException
	 *             if MicroUI is not started.
	 * @throws SecurityException
	 *             if a security manager exists and does not allow the caller to create an image.
	 */
	public BufferedImage(int width, int height) {
		throw new RuntimeException();
	}

	/**
	 * Creates a buffered image specifying its format.
	 * <p>
	 * The new image is initialized with unspecified data.
	 * <p>
	 * Creating images is not supported by every MicroUI implementation. If the MicroUI implementation does not support
	 * the allocation of memory in order to store the image buffer or if the format is not supported, a
	 * {@link MicroUIException} is thrown.
	 * <p>
	 * An image with a custom format can be based on pixels (as the standard formats) but can also be based on anything
	 * else. For instance, it can save the list of drawings and replay them when the image is drawn.
	 *
	 * @param width
	 *            the width of the new image, in pixels.
	 * @param height
	 *            the height of the new image, in pixels.
	 * @param format
	 *            the format of the new image.
	 * @throws IllegalArgumentException
	 *             if either <code>width</code> or <code>height</code> is negative or zero or is greater than
	 *             implementation limit.
	 * @throws MicroUIException
	 *             if there is not enough room to allocate the buffer.
	 * @throws MicroUIException
	 *             if the format is not supported.
	 * @throws MicroUIException
	 *             if MicroUI is not started.
	 * @throws SecurityException
	 *             if a security manager exists and does not allow the caller to create an image.
	 */
	public BufferedImage(int width, int height, Format format) {
		throw new RuntimeException();
	}

	/**
	 * Gets the {@link GraphicsContext} associated with this image, which may be used in order to draw on the image.
	 * <p>
	 * This method always returns the same {@link GraphicsContext} instance for a specific image. The graphics context
	 * has the same dimensions as the image, which allows to modify every pixel of the image.
	 *
	 * @throws MicroUIException
	 *             if this image has been closed (see {@link ResourceImage#close()}).
	 * @return the image's graphics context.
	 */
	public GraphicsContext getGraphicsContext() {
		throw new RuntimeException();
	}

	/**
	 * Gets the format of this image.
	 *
	 * @return the format of this image.
	 */
	public Format getFormat() {
		throw new RuntimeException();
	}

}