/* ============================================================
 *
 * This file is a part of digiKam project
 * https://www.digikam.org
 *
 * Date        : 2005-12-17
 * Description : image file IO threaded interface.
 *
 * SPDX-FileCopyrightText: 2005-2011 by Marcel Wiesweg <marcel dot wiesweg at gmx dot de>
 * SPDX-FileCopyrightText: 2005-2026 by Gilles Caulier <caulier dot gilles at gmail dot com>
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 *
 * ============================================================ */

#pragma once

// Qt includes

#include <QThread>
#include <QMutex>
#include <QList>
#include <QDateTime>
#include <QWaitCondition>
#include <QEvent>

// Local includes

#include "dimg.h"
#include "digikam_export.h"
#include "dynamicthread.h"
#include "loadingdescription.h"

namespace Digikam
{

class DMetadata;
class LoadSaveTask;

class DIGIKAM_EXPORT LoadSaveNotifier
{
public:

    LoadSaveNotifier()          = default;
    virtual ~LoadSaveNotifier() = default;

    virtual void imageStartedLoading(const LoadingDescription& loadingDescription)                  = 0;
    virtual void loadingProgress(const LoadingDescription& loadingDescription, float progress)      = 0;
    virtual void imageLoaded(const LoadingDescription& loadingDescription, const DImg& img)         = 0;
    virtual void moreCompleteLoadingAvailable(const LoadingDescription& oldLoadingDescription,
                                              const LoadingDescription& newLoadingDescription)      = 0;
    virtual void imageStartedSaving(const QString& filePath)                                        = 0;
    virtual void savingProgress(const QString& filePath, float progress)                            = 0;
    virtual void imageSaved(const QString& filePath, bool success)                                  = 0;
    virtual void thumbnailLoaded(const LoadingDescription& loadingDescription, const QImage& img)   = 0;

private:

    Q_DISABLE_COPY(LoadSaveNotifier)
};

// -------------------------------------------------------------------------------------------------------

class DIGIKAM_EXPORT LoadSaveFileInfoProvider
{
public:

    LoadSaveFileInfoProvider()          = default;
    virtual ~LoadSaveFileInfoProvider() = default;

    /**
     * Gives a hint at the orientation of the image.
     * This can be used to supersede the Exif information in the file.
     * Will not be used if DMetadata::ORIENTATION_UNSPECIFIED (default value)
     */
    virtual int   orientationHint(const QString& path)  = 0;

    /**
     * Gives a hint at the size of the image.
     * This can be used to supersede the Exif information in the file.
     */
    virtual QSize dimensionsHint(const QString& path)   = 0;

private:

    Q_DISABLE_COPY(LoadSaveFileInfoProvider)
};

// -------------------------------------------------------------------------------------------------------

class DIGIKAM_EXPORT LoadSaveThread : public DynamicThread,
                                      public LoadSaveNotifier
{
    Q_OBJECT

public:

    enum NotificationPolicy
    {
        /**
         * Always send notification, unless the last event is still in the event queue
         */
        NotificationPolicyDirect,
        /**
         * Always wait for a certain amount of time after the last event sent.
         * In particular, the first event will be sent only after waiting for this time span.
         * (Or no event will be sent, when the loading has finished before)
         * This is the default.
         */
        NotificationPolicyTimeLimited
    };

    /**
     * used by SharedLoadSaveThread only
     */
    enum AccessMode
    {
        /**
         * image will only be used for reading
         */
        AccessModeRead,
        /**
         * image data will possibly be changed
         */
        AccessModeReadWrite
    };

public:

    explicit LoadSaveThread(QObject* const parent = nullptr);

    /**
     * Destructor:
     * The thread will execute all pending tasks and wait for this upon destruction
     */
    ~LoadSaveThread() override;

    /**
     * Append a task to load the given file to the task list
     */
    virtual void load(const LoadingDescription& description);

    /**
     * Append a task to save the image to the task list
     */
    virtual void save(const DImg& image, const QString& filePath, const QString& format);

    void setNotificationPolicy(NotificationPolicy notificationPolicy);

public:

    static void setInfoProvider(LoadSaveFileInfoProvider* const infoProvider);
    static LoadSaveFileInfoProvider* infoProvider();

    /**
     * Retrieves the Exif orientation, either from the info provider if available,
     * or from the metadata
     */
    static int exifOrientation(const QString& filePath,
                               const DMetadata& metadata,
                               bool isRaw,
                               bool fromRawEmbeddedPreview);

Q_SIGNALS:

    /**
     * All signals are delivered to the thread from where the LoadSaveThread object
     * has been created. This thread must use its event loop to get the signals.
     * You must connect to these signals with Qt::AutoConnection (default) or Qt::QueuedConnection.
     */

    /**
     * This signal is emitted when the loading process begins.
     */
    void signalImageStartedLoading(const LoadingDescription& loadingDescription);

    /**
     * This signal is emitted whenever new progress info is available
     * and the notification policy allows emitting the signal.
     * No progress info will be sent for preloaded images (ManagedLoadSaveThread).
     */
    void signalLoadingProgress(const LoadingDescription& loadingDescription, float progress);

    /**
     * This signal is emitted when the loading process has finished.
     * If the process failed, img is null.
     */
    void signalImageLoaded(const LoadingDescription& loadingDescription, const DImg& img);

    /**
     * This signal is emitted if
     *  - you are doing shared loading (SharedLoadSaveThread)
     *  - you started a loading operation with a LoadingDescription for
     *    a reduced version of the image
     *  - another thread started a loading operation for a more complete version
     * You may want to cancel the current operation and start with the given loadingDescription
     */
    void signalMoreCompleteLoadingAvailable(const LoadingDescription& oldLoadingDescription,
                                            const LoadingDescription& newLoadingDescription);

    void signalImageStartedSaving(const QString& filePath);
    void signalSavingProgress(const QString& filePath, float progress);
    void signalImageSaved(const QString& filePath, bool success);

    void signalQImageThumbnailLoaded(const LoadingDescription& loadingDescription, const QImage& img);

public:

    void imageStartedLoading(const LoadingDescription& loadingDescription)                override;
    void loadingProgress(const LoadingDescription& loadingDescription, float progress)    override;
    void imageLoaded(const LoadingDescription& loadingDescription, const DImg& img)       override;
    void moreCompleteLoadingAvailable(const LoadingDescription& oldLoadingDescription,
                                      const LoadingDescription& newLoadingDescription)    override;
    void imageStartedSaving(const QString& filePath)                                      override;
    void savingProgress(const QString& filePath, float progress)                          override;
    void imageSaved(const QString& filePath, bool success)                                override;
    void thumbnailLoaded(const LoadingDescription& loadingDescription, const QImage& img) override;

    virtual bool querySendNotifyEvent() const;
    virtual void taskHasFinished();

protected:

    void run()                                                                            override;

    void notificationReceived();

protected:

    QMutex               m_mutex;

    QList<LoadSaveTask*> m_todo;

    LoadSaveTask*        m_currentTask          = nullptr;

    NotificationPolicy   m_notificationPolicy   = NotificationPolicyTimeLimited;

private:

    /// @note disabled
    LoadSaveThread(const LoadSaveThread&)            = delete;
    LoadSaveThread& operator=(const LoadSaveThread&) = delete;

private:

    class Private;
    Private* const d = nullptr;
};

} // namespace Digikam
