/*
 * 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 java.io.Closeable;
import java.io.InputStream;
import ej.annotation.Nullable;
import ej.microui.MicroUIException;

/**
 * A <code>ResourceImage</code> represents an image which may require dynamic allocation in order to be created.
 * <p>
 * A resource image should be closed in order to free the dynamic allocation used to store the image pixels.
 * <p>
 * This class provides statics method in order to load an image from a resource or from a given input stream.
 */
public class ResourceImage extends Image implements Closeable {

    /**
     * Enumerates the different formats in which a resource image can store pixel colors.
     *
     * @see #loadImage(String, OutputFormat)
     * @see #loadImage(InputStream, int, OutputFormat)
     * @since 2.0
     */
    public enum OutputFormat {

        /**
         * Represents pixel colors on 32 bits: 8 bits for alpha, 8 bits for red, 8 bits for green and 8 bits for blue.
         */
        ARGB8888,
        /**
         * Represents pixel colors on 24 bits: 0 bit for alpha, 8 bits for red, 8 bits for green and 8 bits for blue.
         */
        RGB888,
        /**
         * Represents pixel colors on 16 bits: 0 bit for alpha, 5 bits for red, 6 bits for green and 5 bits for blue.
         */
        RGB565,
        /**
         * Represents pixel colors on 16 bits: 1 bit for alpha, 5 bits for red, 5 bits for green and 5 bits for blue.
         */
        ARGB1555,
        /**
         * Represents pixel colors on 16 bits: 4 bit for alpha, 4 bits for red, 4 bits for green and 4 bits for blue.
         */
        ARGB4444,
        /**
         * Represents pixel colors on 8 bits: 8 bit for alpha, 0 bits for red, 0 bits for green and 0 bits for blue.
         */
        A8;

        /**
         * Returns the SNI context data of this format.
         * <p>
         * The SNI context can be used to call a native method with SNI. This allows to identify the format in the
         * native world.
         * <p>
         * The data format is implementation specific.
         *
         * @return the SNI context of this format.
         */
        public byte getSNIContext() {
            throw new RuntimeException();
        }
    }

    /**
     * Returns whether an image can be loaded from a resource.
     * <p>
     * This method may be used to know whether calling {@link ResourceImage#loadImage(String)} with the given path would
     * be successful or not.
     *
     * @param path
     *            the resource path.
     * @return <code>true</code> if the image can be loaded, <code>false</code> otherwise.
     * @throws MicroUIException
     *             if the resource path doesn't start with "/".
     * @throws MicroUIException
     *             if MicroUI is not started.
     * @throws SecurityException
     *             if a security manager exists and does not allow the caller to load an image.
     * @see #loadImage(String)
     * @since 3.0
     */
    public static boolean canLoadImage(String path) {
        throw new RuntimeException();
    }

    /**
     * Loads an immutable image from a resource.
     * <p>
     * This method can load images which are in the internal image format defined by the MicroUI implementation, and
     * images which are in standard image formats (such as PNG), depending on the capabilities of the MicroUI
     * implementation (such as having a PNG decoder).
     * <p>
     * The MicroUI implementation is responsible for retrieving the correct image load/decoder in order to load the
     * image.
     * <p>
     * The output format of the returned image is the best format for the input format. For example, the output format
     * for PNG images is {@link OutputFormat#ARGB8888}. The output format for images in internal MicroUI image format is
     * the output format specified in the <code>images.list</code> file.
     * <p>
     * Calling this method is equivalent to calling <code>loadImage(name, null)</code>.
     *
     * @param path
     *            the resource path.
     * @return the loaded image.
     * @throws MicroUIException
     *             if the image could not be loaded for any reason (see {@link MicroUIException#getErrorCode()}).
     * @throws MicroUIException
     *             if the resource path doesn't start with "/".
     * @throws MicroUIException
     *             if MicroUI is not started.
     * @throws SecurityException
     *             if a security manager exists and does not allow the caller to load an image.
     * @since 2.0
     */
    public static ResourceImage loadImage(String path) {
        throw new RuntimeException();
    }

    /**
     * Loads an immutable image from a resource.
     * <p>
     * This method can load images which are in the internal image format defined by the MicroUI implementation, and
     * images which are in standard image formats (such as PNG), depending on the capabilities of the MicroUI
     * implementation (such as having a PNG decoder).
     * <p>
     * The MicroUI implementation is responsible for retrieving the correct image load/decoder in order to load the
     * image.
     * <p>
     * The output format of the image is the output format given as parameter. This format may be different from the
     * default output format (@see {@link #loadImage(String)}).
     *
     * @param path
     *            the resource path.
     * @param format
     *            the desired output format, or <code>null</code> to use the default output format.
     * @return the loaded image.
     * @throws MicroUIException
     *             if the image could not be loaded for any reason (see {@link MicroUIException#getErrorCode()}).
     * @throws MicroUIException
     *             if the resource path doesn't start with "/".
     * @throws MicroUIException
     *             if MicroUI is not started.
     * @throws SecurityException
     *             if a security manager exists and does not allow the caller to load an image.
     * @since 2.0
     */
    public static ResourceImage loadImage(String path, @Nullable OutputFormat format) {
        throw new RuntimeException();
    }

    /**
     * Loads an immutable image from an {@link InputStream}.
     * <p>
     * Refer to {@link #loadImage(String)} for more information.
     * <p>
     * Calling this method is equivalent to calling <code>loadImage(stream, size, null)</code>.
     *
     * @param stream
     *            the input stream providing the image data.
     * @param size
     *            the number of bytes to read from the input stream.
     * @return the loaded image.
     * @throws MicroUIException
     *             if the image could not be loaded for any reason (see {@link MicroUIException#getErrorCode()}).
     * @throws MicroUIException
     *             if MicroUI is not started.
     * @throws SecurityException
     *             if a security manager exists and does not allow the caller to load an image.
     * @since 2.0
     */
    public static ResourceImage loadImage(InputStream stream, int size) {
        throw new RuntimeException();
    }

    /**
     * Loads an immutable image from an {@link InputStream}.
     * <p>
     * Refer to {@link #loadImage(String, OutputFormat)} for more information.
     *
     * @param stream
     *            the input stream providing the image data.
     * @param size
     *            the number of bytes to read from the input stream.
     * @param format
     *            the desired output format, or <code>null</code> to use the default output format.
     * @return the loaded image.
     * @throws MicroUIException
     *             if the image could not be loaded for any reason (see {@link MicroUIException#getErrorCode()}).
     * @throws MicroUIException
     *             if MicroUI is not started.
     * @throws SecurityException
     *             if a security manager exists and does not allow the caller to load an image.
     * @since 2.0
     */
    public static ResourceImage loadImage(InputStream stream, int size, @Nullable OutputFormat format) {
        throw new RuntimeException();
    }

    /**
     * Returns whether this image has been closed.
     *
     * @return <code>true</code> if the image has been closed, <code>false</code> otherwise.
     */
    public boolean isClosed() {
        throw new RuntimeException();
    }

    /**
     * Closes this image and its associated resources.
     * <p>
     * Calling this method on an image which has already been closed has no effect.
     */
    @Override
    public void close() {
        throw new RuntimeException();
    }
    /**
     * Forbidden constructor: call one of the <code>loadImage</code> methods to get an instance of
     * {@link ResourceImage}.
     */
}