juce_Image.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   By using JUCE, you agree to the terms of both the JUCE 7 End-User License
   Agreement and JUCE Privacy Policy.
 
   End User License Agreement: www.juce.com/juce-7-licence
   Privacy Policy: www.juce.com/juce-privacy-policy
 
   Or: You may also use this code under the terms of the GPL v3 (see
   www.gnu.org/licenses).
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
class ImageType;
class ImagePixelData;
 
 
//==============================================================================
class JUCE_API  Image  final
{
public:
    //==============================================================================
    enum PixelFormat
    {
        UnknownFormat,
        RGB,                
        ARGB,               
        SingleChannel       
    };
 
    //==============================================================================
    Image() noexcept;

    Image (PixelFormat format, int imageWidth, int imageHeight, bool clearImage);

    Image (PixelFormat format, int imageWidth, int imageHeight, bool clearImage, const ImageType& type);

    Image (const Image&) noexcept;

    Image& operator= (const Image&);

    Image (Image&&) noexcept;

    Image& operator= (Image&&) noexcept;

    ~Image();

    bool operator== (const Image& other) const noexcept     { return image == other.image; }

    bool operator!= (const Image& other) const noexcept     { return image != other.image; }

    inline bool isValid() const noexcept                    { return image != nullptr; }

    inline bool isNull() const noexcept                     { return image == nullptr; }
 
    //==============================================================================
    int getWidth() const noexcept;

    int getHeight() const noexcept;

    Rectangle<int> getBounds() const noexcept;

    PixelFormat getFormat() const noexcept;

    bool isARGB() const noexcept;

    bool isRGB() const noexcept;

    bool isSingleChannel() const noexcept;

    bool hasAlphaChannel() const noexcept;
 
    //==============================================================================
    void clear (const Rectangle<int>& area, Colour colourToClearTo = Colour (0x00000000));

    Image rescaled (int newWidth, int newHeight,
                    Graphics::ResamplingQuality quality = Graphics::mediumResamplingQuality) const;

    Image createCopy() const;

    Image convertedToFormat (PixelFormat newFormat) const;

    void duplicateIfShared();

    Image getClippedImage (const Rectangle<int>& area) const;
 
    //==============================================================================
    Colour getPixelAt (int x, int y) const;

    void setPixelAt (int x, int y, Colour colour);

    void multiplyAlphaAt (int x, int y, float multiplier);

    void multiplyAllAlphas (float amountToMultiplyBy);

    void desaturate();
 
    //==============================================================================
    class JUCE_API  BitmapData  final
    {
    public:
        enum ReadWriteMode
        {
            readOnly,
            writeOnly,
            readWrite
        };
 
        BitmapData (Image& image, int x, int y, int w, int h, ReadWriteMode mode);
        BitmapData (const Image& image, int x, int y, int w, int h);
        BitmapData (const Image& image, ReadWriteMode mode);
        ~BitmapData();

        inline uint8* getLinePointer (int y) const noexcept                 { return data + (size_t) y * (size_t) lineStride; }

        inline uint8* getPixelPointer (int x, int y) const noexcept         { return data + (size_t) y * (size_t) lineStride + (size_t) x * (size_t) pixelStride; }

        Colour getPixelColour (int x, int y) const noexcept;

        void setPixelColour (int x, int y, Colour colour) const noexcept;

        Rectangle<int> getBounds() const noexcept                           { return Rectangle<int> (width, height); }
 
        uint8* data;             
        size_t size;             
        PixelFormat pixelFormat; 
        int lineStride;          
        int pixelStride;         
        int width, height;
 
        //==============================================================================
        class BitmapDataReleaser
        {
        protected:
            BitmapDataReleaser() = default;
        public:
            virtual ~BitmapDataReleaser() = default;
        };
 
        std::unique_ptr<BitmapDataReleaser> dataReleaser;
 
    private:
        JUCE_DECLARE_NON_COPYABLE (BitmapData)
    };
 
    //==============================================================================
    void moveImageSection (int destX, int destY,
                           int sourceX, int sourceY,
                           int width, int height);

    void createSolidAreaMask (RectangleList<int>& result, float alphaThreshold) const;
 
    //==============================================================================
    NamedValueSet* getProperties() const;
 
    //==============================================================================
    std::unique_ptr<LowLevelGraphicsContext> createLowLevelContext() const;

    int getReferenceCount() const noexcept;
 
    //==============================================================================
    ImagePixelData* getPixelData() const noexcept       { return image.get(); }

    explicit Image (ReferenceCountedObjectPtr<ImagePixelData>) noexcept;
 
    //==============================================================================
   #if JUCE_ALLOW_STATIC_NULL_VARIABLES && ! defined (DOXYGEN)
    /* A null Image object that can be used when you need to return an invalid image. */
    [[deprecated ("If you need a default-constructed var, just use Image() or {}.")]]
    static const Image null;
   #endif
 
private:
    //==============================================================================
    ReferenceCountedObjectPtr<ImagePixelData> image;
 
    JUCE_LEAK_DETECTOR (Image)
};
 
 
//==============================================================================
class JUCE_API  ImagePixelData  : public ReferenceCountedObject
{
public:
    ImagePixelData (Image::PixelFormat, int width, int height);
    ~ImagePixelData() override;
 
    using Ptr = ReferenceCountedObjectPtr<ImagePixelData>;

    virtual std::unique_ptr<LowLevelGraphicsContext> createLowLevelContext() = 0;
    virtual Ptr clone() = 0;
    virtual std::unique_ptr<ImageType> createType() const = 0;
    virtual void initialiseBitmapData (Image::BitmapData&, int x, int y, Image::BitmapData::ReadWriteMode) = 0;
    virtual int getSharedCount() const noexcept;
 

    const Image::PixelFormat pixelFormat;
    const int width, height;

    NamedValueSet userData;
 
    //==============================================================================
    struct Listener
    {
        virtual ~Listener() = default;
 
        virtual void imageDataChanged (ImagePixelData*) = 0;
        virtual void imageDataBeingDeleted (ImagePixelData*) = 0;
    };
 
    ListenerList<Listener> listeners;
 
    void sendDataChangeMessage();
 
private:
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ImagePixelData)
};
 
//==============================================================================
class JUCE_API  ImageType
{
public:
    ImageType();
    virtual ~ImageType();

    virtual ImagePixelData::Ptr create (Image::PixelFormat, int width, int height, bool shouldClearImage) const = 0;

    virtual int getTypeID() const = 0;

    virtual Image convert (const Image& source) const;
};
 
//==============================================================================
class JUCE_API  SoftwareImageType   : public ImageType
{
public:
    SoftwareImageType();
    ~SoftwareImageType() override;
 
    ImagePixelData::Ptr create (Image::PixelFormat, int width, int height, bool clearImage) const override;
    int getTypeID() const override;
};
 
//==============================================================================
class JUCE_API  NativeImageType   : public ImageType
{
public:
    NativeImageType();
    ~NativeImageType() override;
 
    ImagePixelData::Ptr create (Image::PixelFormat, int width, int height, bool clearImage) const override;
    int getTypeID() const override;
};
 
} // namespace juce