/***************************************************************************
                          qgsrasterlayerutils.h
                          -------------------------
    begin                : March 2024
    copyright            : (C) 2024 by Nyall Dawson
    email                : nyall dot dawson at gmail dot com
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

#ifndef QGSRASTERLAYERUTILS_H
#define QGSRASTERLAYERUTILS_H

#include "qgis_core.h"
#include "qgis_sip.h"
#include "qgspointxy.h"
#include "qgsrange.h"

class QgsRasterLayer;
class QgsRasterDataProvider;
class QgsRasterMinMaxOrigin;
class QgsRectangle;

/**
 * \class QgsRasterLayerUtils
 * \ingroup core
 * \brief Contains utility functions for working with raster layers.
 *
 * \since QGIS 3.38
 */
class CORE_EXPORT QgsRasterLayerUtils
{
  public:
    /**
     * Given a raster \a layer, returns the band which should be used for
     * rendering the layer for a specified temporal and elevation range,
     * respecting any elevation and temporal settings which affect the rendered band.
     *
     * \param layer Target raster layer
     * \param temporalRange temporal range for rendering
     * \param elevationRange elevation range for rendering
     * \param matched will be set to TRUE if a band matching the temporal and elevation range was found
     *
     * \returns Matched band, or -1 if the layer does not have any elevation or temporal settings which affect the rendered band.
     */
    static int renderedBandForElevationAndTemporalRange( QgsRasterLayer *layer, const QgsDateTimeRange &temporalRange, const QgsDoubleRange &elevationRange, bool &matched SIP_OUT );

    /**
     * Compute the \a min \a max values for \a provider along \a band according to
     * MinMaxOrigin parameters \a mmo and \a extent.
     *
     * \since QGIS 4.0
     */
    static void computeMinMax(
      QgsRasterDataProvider *provider, int band, const QgsRasterMinMaxOrigin &mmo, Qgis::RasterRangeLimit limits, const QgsRectangle &extent, int sampleSize, double &min SIP_OUT, double &max SIP_OUT
    );

    /**
     * Returns a new extent that includes the given \a extent with corners coordinates
     * aligned to the pixel grid defined by the \a origin and \a pixelSizeX and \a pixelSizeY arguments.
     *
     * The resulting extent will be expanded if necessary to ensure that its corners fall on pixel boundaries defined by the origin and pixel sizes.
     *
     * \returns The aligned extent or the original extent if pixel sizes are zero (to avoid division by zero) or if the extent is empty.
     *
     * \since QGIS 4.0
     */
    static QgsRectangle alignRasterExtent( const QgsRectangle &extent, const QgsPointXY &origin, double pixelSizeX, double pixelSizeY );
};

#endif //QGSRASTERLAYERUTILS_H
