/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgsmultirenderchecker.h                                     *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/





class QgsMultiRenderChecker
{
%Docstring(signature="appended")
This class allows checking rendered images against comparison images.

Its main purpose is for the unit testing framework.

It will either:

- take an externally rendered image (:py:func:`~setRenderedImage`)
- render the image based on provided mapSettings (:py:func:`~setMapSettings`)

This image will then be compared against one or several images in a
folder inside the control directory
(tests/testdata/control_images/{controlName}).

There are modes for single and for multiple reference images.

- If there are no subfolders in the control directory, it will assume an
  image with the name {controlImage}.png in the control directory
  itself.
- If there are subfolders inside the control directory, it will search
  for images with the name {controlImage}.png in every subfolder.

For every control image there may be one or several randomly named
anomaly images defining allowed anomalies. For every control image, the
allowed mismatch and color tolerance values will be calculated
individually.
%End

%TypeHeaderCode
#include "qgsmultirenderchecker.h"
%End
  public:

    QgsMultiRenderChecker();
%Docstring
Constructor for QgsMultiRenderChecker.
%End

    virtual ~QgsMultiRenderChecker();

    void setControlName( const QString &name );
%Docstring
Base directory name for the control image (with control image path
suffixed) the path to the image will be constructed like this:
controlImagePath + '/' + mControlName + '/' + mControlName + '.png'
%End

    void setFileFunctionLine( const QString &file, const QString &function, int line );
%Docstring
Sets the source ``file``, ``function`` and ``line`` from where the test
originates.

.. versionadded:: 3.36
%End

    void setControlPathPrefix( const QString &prefix );
%Docstring
Sets the path ``prefix`` where the control images are kept.
%End

    void setRenderedImage( const QString &renderedImagePath );
%Docstring
Set the path to the rendered image. If this is not set or set to null
QString, an image will be rendered based on the provided mapsettings

:param renderedImagePath: A path to the rendered image with which
                          control images will be compared
%End

    void setExpectFail( bool expectFail );
%Docstring
Sets whether the comparison is expected to fail.

.. versionadded:: 3.28
%End

    void setMapSettings( const QgsMapSettings &mapSettings );
%Docstring
Set the map settings to use to render the image

:param mapSettings: The map settings
%End

    void setColorTolerance( unsigned int colorTolerance );
%Docstring
Set tolerance for color components used by
:py:func:`~QgsMultiRenderChecker.runTest` Default value is 0.

:param colorTolerance: The maximum difference for each color component
                       including alpha to be considered correct.
%End

    void setSizeTolerance( int xTolerance, int yTolerance );
%Docstring
Sets the largest allowable difference in size between the rendered and
the expected image.

:param xTolerance: x tolerance in pixels
:param yTolerance: y tolerance in pixels
%End

    bool runTest( const QString &testName, unsigned int mismatchCount = 0 );
%Docstring
Test using renderer to generate the image to be compared.

:param testName: to be used as the basis for writing a file to e.g.
                 /tmp/theTestName.png

:param mismatchCount: defaults to 0. The number of pixels that are
                      allowed to be different from the control image. In
                      some cases rendering may be non-deterministic.
                      This parameter allows you to account for that by
                      providing a tolerance.

.. note::

   make sure to call setExpectedImage and setMapSettings first
%End

    QString report() const;
%Docstring
Returns a HTML report for this test.

The report will be empty if the test was successfully run.

.. seealso:: :py:func:`markdownReport`
%End

    QString markdownReport() const;
%Docstring
Returns a markdown report for this test.

The report will be empty if the test was successfully run.

.. seealso:: :py:func:`report`

.. versionadded:: 3.34
%End

    QString controlImagePath() const;
%Docstring
Returns the path to the control images.
%End

    static void drawBackground( QImage *image );
%Docstring
Draws a checkboard pattern for image backgrounds, so that opacity is
visible without requiring a transparent background for the image
%End

};


class QgsLayoutChecker : QgsMultiRenderChecker
{
%Docstring(signature="appended")
Renders a layout to an image and compares with an expected output
%End

%TypeHeaderCode
#include "qgsmultirenderchecker.h"
%End
  public:

    QgsLayoutChecker( const QString &testName, QgsLayout *layout );
%Docstring
Constructor for QgsLayoutChecker.
%End

    void setSize( QSize size );
%Docstring
Sets the output (reference) image ``size``.
%End

    bool testLayout( QString &report /Out/, int page = 0, int pixelDiff = 0, bool createReferenceImage = false );
%Docstring
Runs a render check on the layout, adding results to the specified
``report``.

The maximum number of allowable pixels differing from the reference
image is specified via the ``pixelDiff`` argument.

A reference image can be created by setting ``createReferenceImage`` to
``True`` in this case the test will always return ``True``.

The page number is specified via ``page``, where 0 corresponds to the
first page in the layout.

:param page: page number from layout to render and check
:param pixelDiff: number of pixels which are permitted to differ from
                  reference image.
:param createReferenceImage: if ``True``, the rendered reference image
                             will be regenerated instead of performing a
                             comparison test with the existing image

:return: - ``True`` if the rendered layout matches the expected
           reference image.
         - report: generated test report
%End

};


/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgsmultirenderchecker.h                                     *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/