/******************************************************************************
* Copyright (c) 2018(-2023) STMicroelectronics.
* All rights reserved.
*
* This file is part of the TouchGFX 4.23.0 distribution.
*
* This software is licensed under terms that can be found in the LICENSE file in
* the root directory of this software component.
* If no LICENSE file comes with this software, it is provided AS-IS.
*
*******************************************************************************/

/**
 * @file touchgfx/Bitmap.hpp
 *
 * Declares the touchgfx::Bitmap class.
 */
#ifndef TOUCHGFX_BITMAP_HPP
#define TOUCHGFX_BITMAP_HPP

#include <touchgfx/hal/Types.hpp>

#if defined(__ARMCC_VERSION) && (__ARMCC_VERSION < 6000000)
// Keil5 compiler issues irrelevant warning relating to missing ctor initialization for BitmapData.
#pragma diag_suppress 368
#endif

namespace touchgfx
{
/**
 * This type shall be used by the application to define unique IDs for all bitmaps in the
 * system. The application shall define bitmap IDs in the range [0, number of bitmaps -
 * 1].
 */
typedef uint16_t BitmapId;

const BitmapId BITMAP_ANIMATION_STORAGE = 0xFFFEU; ///< A virtual id representing animation storage.
const BitmapId BITMAP_INVALID = 0xFFFFU;           ///< Define the bitmapId of an invalid bitmap

/**
 * This class provides a proxy object for a bitmap image stored in the application specific
 * bitmap database. The proxy provides access to the raw bitmap data as well as metadata.
 */
class Bitmap
{
public:
    /** Color data of a clut can be stored in the following formats. */
    enum ClutFormat
    {
        CLUT_FORMAT_L8_ARGB8888, ///< 32-bit, 8 bits for each of red, green, blue and alpha
        CLUT_FORMAT_L8_RGB888,   ///< 24-bit, 8 bits for each of red, green and blue. No per pixel alpha channel
        CLUT_FORMAT_L8_RGB565    ///< 16-bit, 5 bits for red, 6 bits for green, 5 bits for blue. No per pixel alpha channel
    };

    /** Data of a bitmap can be stored in the following formats. */
    enum BitmapFormat
    {
        RGB565,   ///< 16-bit, 5 bits for red, 6 bits for green, 5 bits for blue. No alpha channel
        RGB888,   ///< 24-bit, 8 bits for each of red, green and blue. No alpha channel
        ARGB8888, ///< 32-bit, 8 bits for each of red, green, blue and alpha channel
        BW,       ///< 1-bit, black / white. No alpha channel
        BW_RLE,   ///< 1-bit, black / white. No alpha channel. Image is compressed with horizontal RLE
        GRAY2,    ///< 2-bit grayscale
        GRAY4,    ///< 4-bit grayscale
        ARGB2222, ///< 8-bit color
        ABGR2222, ///< 8-bit color
        RGBA2222, ///< 8-bit color
        BGRA2222, ///< 8-bit color
        L8,       ///< 8-bit indexed color
        A4,       ///< 4-bit alpha level
        CUSTOM    ///< Non-standard platform specific format
    };

    /** Algorithms used for L8 images compression can be stored in the following formats. */
    enum Compression
    {
        COMPRESSION_L8_NONE = 0, ///< No compression applied on the L8 image
        COMPRESSION_L8_L4 = 1,   ///< L4 compression applied on the L8 image
        COMPRESSION_L8_RLE = 2,  ///< RLE compression applied on the L8 image
        COMPRESSION_L8_LZW9 = 3  ///< LZW9 compression applied on the L8 image
    };

    /** Data of a bitmap. */
    struct BitmapData
    {
        const uint8_t* const data;            ///< The data of this Bitmap
        const uint8_t* const extraData;       ///< The data of either the alpha channel (if present) or clut data in case of indexed color bitmap. 0 if not used
        const uint16_t width;                 ///< The width of the Bitmap
        const uint16_t height;                ///< The height of the Bitmap
        const uint16_t solidRect_x;           ///< The x coordinate of the maximum solid rectangle of the Bitmap
        const uint16_t solidRect_y;           ///< The y coordinate of the maximum solid rectangle of the Bitmap
        const uint16_t solidRect_width : 13;  ///< The width of the maximum solid rectangle of the Bitmap
        const uint16_t format_hi : 3;         ///< Determine the format of the data (high 3 bits)
        const uint16_t solidRect_height : 13; ///< The height of the maximum solid rectangle of the Bitmap
        const uint16_t format_lo : 3;         ///< Determine the format of the data (low 3 bits)

        /**
         * Gets the Bitmap format by combining the high and low parts (format_hi << 3) | format_lo.
         *
         * @return The BitmapFormat
         */
        BitmapFormat getFormat() const
        {
            return (BitmapFormat)((format_hi << 3) | format_lo);
        }
    };

    /** Data of a dynamic Bitmap. */
    struct DynamicBitmapData
    {
        Rect solid;              ///< The solidRect of this Bitmap
        uint16_t width;          ///< The width of the Bitmap
        uint16_t height;         ///< The height of the Bitmap
        uint8_t format : 5;      ///< Determine the format of the data
        uint8_t inuse : 1;       ///< Zero if not in use
        uint8_t extra : 2;       ///< Extra data field, dependent on format
        uint8_t customSubformat; ///< Custom format specifier (or L8 palette length)
    };

    /** Cache bookkeeping. */
    struct CacheTableEntry
    {
        uint8_t* data; ///< Pointer to location of image data for this Bitmap in the cache. 0 if bitmap not cached.
    };

    /**
     * Creates and binds a Bitmap instance to the corresponding entry in the BitmapData
     * array.
     *
     * @param  id (Optional) The unique bitmap identifier.
     */
    Bitmap(const BitmapId id = BITMAP_INVALID)
        : bitmapId(id)
    {
    }

    /**
     * Gets the id of this Bitmap.
     *
     * @return The id of this Bitmap.
     */
    BitmapId getId() const
    {
        assert(bitmaps != 0 && "Bitmap database has not been initialized.");
        return bitmapId;
    }

    /**
     * Gets the id of this Bitmap.
     *
     * @return The id of this Bitmap.
     */
    operator BitmapId() const
    {
        return getId();
    }

    /**
     * Gets a pointer to the Bitmap data.
     *
     * @return A pointer to the raw Bitmap data.
     *
     * @note If this Bitmap is cached, it will return the cached version of Bitmap data.
     */
    const uint8_t* getData() const;

    /**
     * Gets a pointer to the extra (alpha) data, if present in the Bitmap. For images stored
     * in L8 format, a pointer to the CLUT will be returned. For non-opaque RGB565 images, a
     * pointer to the alpha channel will be returned.
     *
     * @return A pointer to the raw alpha channel data or CLUT. If no alpha channel or CLUT
     *         exist for the given Bitmap, 0 is returned.
     *
     * @note If this Bitmap is cached, it will return the cached version of alpha data for this
     *       Bitmap.
     */
    const uint8_t* getExtraData() const;

    /**
     * Gets the format of how the Bitmap is stored.
     *
     * @return The format of how the Bitmap data is stored.
     */
    BitmapFormat getFormat() const;

    /**
     * Gets the width of the Bitmap in pixels.
     *
     * @return The Bitmap width in pixels.
     */
    int16_t getWidth() const;

    /**
     * Gets the height of the Bitmap in pixels.
     *
     * @return The Bitmap height in pixels.
     */
    int16_t getHeight() const;

    /**
     * Gets the rectangle describing the dimensions of the Bitmap.
     *
     * @return a Rect describing the dimensions of this Bitmap.
     */
    Rect getRect() const
    {
        return Rect(0, 0, getWidth(), getHeight());
    }

    /**
     * Query if this object has an alpha channel.
     *
     * @return True if the bitmap contains an alpha channel (an alpha value for each pixel)
     */
    bool isAlphaPerPixel() const
    {
        assert(bitmaps != 0 && "Bitmap database has not been initialized.");
        if (getFormat() == L8)
        {
            return false; // No Alpha channel for indexed L8 bitmaps
        }
        return ((bitmaps != 0) && (bitmapId < numberOfBitmaps)) ? (bitmaps[bitmapId].extraData != 0) : false;
    }

    /**
     * Gets the largest solid, i.e. not transparent, rectangle in the Bitmap.
     *
     * @return The maximum solid rectangle of the Bitmap.
     */
    Rect getSolidRect() const;

    /**
     * Query if this object has transparent pixels.
     *
     * @return True if this bitmap has transparent pixels.
     */
    bool hasTransparentPixels() const;

    /**
     * Registers an array of bitmaps. All Bitmap instances are bound to this database. This
     * function is called automatically from HAL::touchgfx_generic_init().
     *
     * @param      data                   A reference to the BitmapData storage array.
     * @param      n                      The number of bitmaps in the array.
     * @param [in] cachep                 (Optional) Pointer to memory region in which bitmap
     *                                    data can be cached.
     * @param      csize                  (Optional) Size of cache memory region in bytes (0 if
     *                                    unused)
     * @param      numberOfDynamicBitmaps (Optional) Number of dynamic bitmaps to be allowed in
     *                                    the cache.
     */
    static void registerBitmapDatabase(const BitmapData* data, const uint16_t n, uint16_t* cachep = 0, uint32_t csize = 0,
                                       uint32_t numberOfDynamicBitmaps = 0);

    /**
     * Cache this Bitmap into unused RAM in the bitmap cache. A memory region large enough
     * to hold this bitmap must be configured and a large enough part of it must be
     * available. Caching of a bitmap may involve a defragmentation of the bitmap cache.
     *
     * @param  id The id of the Bitmap to cache.
     *
     * @return true if caching went well, false otherwise.
     *
     * @see registerBitmapDatabase, compactCache
     */
    static bool cache(BitmapId id);

    /**
     * Replace a Bitmap in RAM with another Bitmap. The Bitmaps must have same size.
     *
     * @param  out The id of the Bitmap to remove from the cache.
     * @param  in  The id of the Bitmap to cache.
     *
     * @return true if the replacement went well, false otherwise.
     */
    static bool cacheReplaceBitmap(BitmapId out, BitmapId in);

    /**
     * Remove this Bitmap from the RAM cache. Unless the Bitmap is
     * otherwise stored in (slower) memory it can not be drawn anymore
     * and must be cached again before use. The RAM freed can be used
     * for caching of another bitmap.
     *
     * @param  id The id of the Bitmap to cache.
     *
     * @return true if Bitmap was found and removed, false otherwise.
     *
     * @see registerBitmapDatabase
     */
    static bool cacheRemoveBitmap(BitmapId id);

    /**
     * Get address of cache buffer for this Bitmap.
     *
     * @param  id The id of the Bitmap in cache.
     *
     * @return Address if Bitmap was found, zero otherwise.
     *
     * @note The address is only valid until next Bitmap::cache() call.
     */
    static uint8_t* cacheGetAddress(BitmapId id);

    /**
     * Check if the Bitmap is cached.
     *
     * @param  id The id of the Bitmap.
     *
     * @return true if Bitmap is cached.
     */
    static bool cacheIsCached(BitmapId id);

    /**
     * Cache all bitmaps from the Bitmap Database into RAM. A memory region large enough to
     * hold all bitmaps must be configured.
     *
     * @return True if all bitmaps where cached.
     *
     * @see cache
     */
    static bool cacheAll();

    /** Clears the cached bitmaps from RAM. */
    static void clearCache();

    /**
     * Decompress a compressed bitmap into the bitmap cache. The
     * decompressed bitmap will automatically be used by all Widgets.
     *
     * Only compressed L8 images can be decompressed. The decompressed
     * bitmap will be L8 with an unchanged palette.
     *
     * When decompressing L8 bitmaps compressed with LZW an array of
     * size 2048 bytes (16 bit aligned) must be supplied. The array is
     * only used during decompressing.
     *
     * @param  id The id of the Bitmap to decompress.
     * @param  buffer Pointer to a buffer for LZW decompression.
     * @return true if the bitmap was decompressed.
     */
    static bool decompress(BitmapId id, uint16_t* buffer = 0);

    /**
     * Create a dynamic Bitmap. The clutFormat parameter is ignored for bitmaps not in L8 format
     * (consider using dynamicBitmapCreateL8 instead). Creation of a new dynamic bitmap may cause
     * existing dynamic bitmaps to be moved in memory. Do not rely on bitmap memory addresses of
     * dynamic bitmaps obtained from dynamicBitmapGetAddress() to be valid across calls to
     * dynamicBitmapCreate().
     *
     * @param   width       Width of the Bitmap.
     * @param   height      Height of the Bitmap.
     * @param   format      Bitmap format of the Bitmap.
     * @param   clutFormat  (Optional) Color LookUp Table format of the Bitmap (only used if format
     *                      is Bitmap::L8).
     *
     * @return  BitmapId of the new Bitmap or #BITMAP_INVALID if cache memory is full.
     *
     * @see DynamicBitmapData, dynamicBitmapCreateL8, dynamicBitmapCreateCopy
     */
    static BitmapId dynamicBitmapCreate(const uint16_t width, const uint16_t height, BitmapFormat format, ClutFormat clutFormat = CLUT_FORMAT_L8_ARGB8888);

    /**
     * Create a dynamic Bitmap as a copy of an existing bitmap.
     *
     * @param   id  The ID of the bitmap to copy.
     *
     * @return  BitmapId of the new Bitmap or #BITMAP_INVALID if cache memory is full.
     *
     * @see dynamicBitmapCreate
     */
    static BitmapId dynamicBitmapCreateCopy(const BitmapId id);

    /**
     * Create a dynamic L8 Bitmap. Creation of a new dynamic bitmap may cause existing dynamic
     * bitmaps to be moved in memory. Do not rely on bitmap memory addresses of dynamic bitmaps
     * obtained from dynamicBitmapGetAddress() to be valid across calls to dynamicBitmapCreate().
     *
     * @param   width       Width of the Bitmap.
     * @param   height      Height of the Bitmap.
     * @param   clutFormat  Color LookUp Table format of the L8 Bitmap.
     * @param   clutSize    (Optional) Color LookUp Table palette size (default=256).
     *
     * @return  BitmapId of the new Bitmap or #BITMAP_INVALID if cache memory is full.
     *
     * @see DynamicBitmapData, dynamicBitmapCreate
     */
    static BitmapId dynamicBitmapCreateL8(const uint16_t width, const uint16_t height, ClutFormat clutFormat, uint16_t clutSize = 256);

    /**
     * Create a dynamic bitmap in custom format. size number of bytes
     * is reserved in the dynamic bitmap cache. A more specific format
     * can be given in the customSubformat parameter for use when
     * handling more than one CUSTOM format. Set the solid rect if
     * applicable.
     *
     * @param width           Width of the bitmap.
     * @param height          Height of the bitmap.
     * @param customSubformat Custom format specifier
     * @param size            Size in bytes of the dynamic bitmap
     *
     * @return BitmapId of the new bitmap or BITMAP_INVALID if cache memory is full.
     *
     * @note Creation of a new dynamic bitmap may cause existing dynamic bitmaps to be moved in
     *       memory. Do not rely on bitmap memory addresses of dynamic bitmaps obtained from
     *       dynamicBitmapGetAddress() to be valid across calls to dynamicBitmapCreateCustom() .
     *
     * @see dynamicBitmapGetAddress, dynamicBitmapCreate, dynamicBitmapSetSolidRect
     */
    static BitmapId dynamicBitmapCreateCustom(const uint16_t width, const uint16_t height, uint8_t customSubformat, uint32_t size);

    /**
     * Create a dynamic bitmap without reserving memory in the dynamic
     * bitmap cache. The pixels must be already available in the
     * memory, e.g. in flash. No copying is performed.
     *
     * @param width           Width of the bitmap.
     * @param height          Height of the bitmap.
     * @param pixels          Pointer to the bitmap pixels.
     * @param format          Bitmap format of the bitmap.
     * @param customSubformat Custom format specifier
     *
     * @return BitmapId of the new bitmap or BITMAP_INVALID if not possible.
     *
     * @see dynamicBitmapGetAddress, dynamicBitmapCreate, dynamicBitmapSetSolidRect
     */
    static BitmapId dynamicBitmapCreateExternal(const uint16_t width, const uint16_t height, const void* pixels, BitmapFormat format, uint8_t customSubformat = 0);

    /**
     * Fill a dynamic Bitmap with a color. If alpha is less than 255, the color will be blended onto
     * the existing data in the dynamic bitmap.
     *
     * @param   id      The ID of the dynamic bitmap to fill.
     * @param   color   The color.
     * @param   alpha   (Optional) The alpha (default is 255, i.e. solid).
     *
     * @see dynamicBitmapCreateCopy, dynamicBitmapFillRect
     */
    static void dynamicBitmapFill(const BitmapId id, const colortype color, const uint8_t alpha = 255);

    /**
     * Fill parts of a dynamic Bitmap with a color. If alpha is less than 255, the color will be
     * blended onto the existing data in the dynamic bitmap.
     *
     * @param   id      The ID of the dynamic bitmap to fill.
     * @param   rect    The rectangle to fill.
     * @param   color   The color.
     * @param   alpha   (Optional) The alpha (default is 255, i.e. solid).
     *
     * @see dynamicBitmapCreateCopy, dynamicBitmapFill
     */
    static void dynamicBitmapFillRect(const BitmapId id, const Rect& rect, const colortype color, const uint8_t alpha = 255);

    /**
     * Delete a dynamic bitmap.
     *
     * @param  id The BitmapId of the dynamic Bitmap.
     *
     * @return true if it succeeds, false if it fails.
     */
    static bool dynamicBitmapDelete(BitmapId id);

    /**
     * Check if a given bitmap id is the id of a dynamic bitmap.
     *
     * @param  id The BitmapId of the dynamic Bitmap.
     *
     * @return true if the bitmap is dynamic, false otherwise.
     */
    static bool isDynamicBitmap(BitmapId id);

    /**
     * Get the address of the dynamic Bitmap data. It is important that the address of a
     * dynamic Bitmap is not stored elsewhere as a dynamic Bitmap may be moved in memory
     * when other bitmaps are added and removed. Only store the BitmapId and ask for the
     * address of the Bitmap data when needed. The address of a dynamic bitmap may change
     * when other dynamic bitmaps are added and removed.
     *
     * @param  id The BitmapId of the dynamic bitmap.
     *
     * @return null if it fails, else an uint8_t*.
     *
     * @note Never keep the address of dynamic images, only store the BitmapId as that will not
     *       change.
     */
    static uint8_t* dynamicBitmapGetAddress(BitmapId id);

    /**
     * Set the solid rectangle of a dynamic Bitmap. Only relevant for ARGB8888 Bitmap and
     * 8bpp Bitmap formats, as these formats include an alpha channel. The solid part of the
     * Bitmap is drawn faster than the transparent parts.
     *
     * @param  id        The identifier.
     * @param  solidRect The solid rectangle.
     *
     * @return true if it succeeds, false if it fails.
     */
    static bool dynamicBitmapSetSolidRect(BitmapId id, const Rect& solidRect);

    /**
     * Updates the solid rectangle of a dynamic Bitmap to include the given rectangle. Only
     * relevant for ARGB8888 bitmap and 8bpp bitmap formats, as these formats include an
     * alpha channel. The solid part of the Bitmap is drawn faster than the transparent
     * parts.
     *
     * @param  id        The identifier.
     * @param  solidRect The solid rectangle.
     *
     * @return true if it succeeds, false if it fails.
     */
    static bool dynamicBitmapAddSolidRect(BitmapId id, const Rect& solidRect);

    /// @cond
    /**
     * Gets the subformat of the dynamic bitmap. Zero is returned if
     * the subformat was not set.
     *
     * @return the subformat
     */
    static uint8_t dynamicBitmapGetCustomSubformat(BitmapId id);

    /**
     * @return The number of dynamic bitmaps.
     */
    static uint32_t dynamicBitmapGetNumberOfBitmaps();
    /// @endcond

    /**
     * Register a memory region in which Bitmap data can be cached.
     *
     * @param [in] cachep                 Pointer to memory region in which bitmap data can be
     *                                    cached.
     * @param      csize                  Size of cache memory region in bytes.
     * @param      numberOfDynamicBitmaps (Optional) Number of dynamic bitmaps to be allowed in
     *                                    the cache.
     */
    static void setCache(uint16_t* cachep, uint32_t csize, uint32_t numberOfDynamicBitmaps = 0);

    /**
     * Removes the Bitmap cache. The memory can hereafter be used for other purposes. All
     * dynamic Bitmap IDs are invalid after this.
     */
    static void removeCache();

    /**
     * Gets the address of the first unused memory in the cache. Can be used in advanced
     * application to reduce power consumption of external RAM by turning off unused RAM.
     *
     * @return Returns the highest used address in the cache.
     */
    static uint8_t* getCacheTopAddress()
    {
        return nextFreeData;
    }

    /**
     * Compact the bitmap cache to get continuous free memory on top. This method is called
     * by Bitmap::cache when required.
     */
    static void compactCache();

private:
    static uint32_t getSizeOfBitmap(BitmapId id);
    static uint32_t getSizeOfBitmapData(BitmapId id);
    static uint32_t getSizeOfBitmapExtraData(BitmapId id);
    static bool cacheInternal(BitmapId id, uint32_t size, bool doCopy = true);
    static bool isCustomDynamicBitmap(BitmapId id);
    static bool copyBitmapToCache(BitmapId id, uint8_t* const dst);
    static uint32_t firstFreeDynamicBitmapId();
    static uint32_t decompressL8_L4(uint8_t* dst, BitmapId id);
    static uint32_t decompressL8_RLE(uint8_t* dst, BitmapId id);
    static uint32_t decompressL8_LZW9(uint8_t* dst, BitmapId id, uint16_t* buffer = 0);

    BitmapId bitmapId;
    static const BitmapData* bitmaps;
    static DynamicBitmapData* dynBitmaps;
    static CacheTableEntry* cacheTable; ///< Address of allocation point cache
    static BitmapId* allocationTable;   ///< Order of allocations in cache
    static uint8_t* nextFreeData;
    static uint16_t nextAllocationIndex;
    static uint32_t memoryRemaining;
    static uint32_t totalMemory;
    static uint16_t numberOfBitmaps;
    static uint16_t numberOfDynamicBitmaps;
    static uint16_t uncachedCount; ///< Uncached images, sort of ...

    static const uint16_t RLE_BLOCK_SIZE = 1024U;
};

} // namespace touchgfx

#endif // TOUCHGFX_BITMAP_HPP
