Perceptual Color

gradientimageparameters.h
1// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
2// SPDX-License-Identifier: BSD-2-Clause OR MIT
3
4#ifndef GRADIENTIMAGEPARAMETERS_H
5#define GRADIENTIMAGEPARAMETERS_H
6
7#include "lchadouble.h"
8#include <qglobal.h>
9#include <qimage.h>
10#include <qmetatype.h>
11#include <qsharedpointer.h>
12#include <qvariant.h>
13
14namespace PerceptualColor
15{
16class AsyncImageRenderCallback;
17class RgbColorSpace;
18
19/** @internal
20 *
21 * @brief Parameters for image of a gradient.
22 *
23 * For usage with @ref AsyncImageProvider.
24 *
25 * As the hue is a circular property, there exists two ways to go one hue to
26 * another (clockwise or counter-clockwise). This gradient takes always the
27 * shortest way.
28 *
29 * The image has properties that can be accessed by the corresponding setters
30 * and getters or directly. You should explicitly set all values
31 * <em>before</em> calling the first time @ref render().
32 *
33 * This class supports HiDPI via its @ref setDevicePixelRatioF function.
34 *
35 * @todo Instead of providing an image that has actually the size that
36 * has been requested, we could provide just a tile. The user would have
37 * to tile the surface. In many cases, we could get away with much smaller
38 * images. Attention: Test if this approach works fine when the screen scale
39 * factor is not an integer! */
40struct GradientImageParameters final {
41public:
42 explicit GradientImageParameters();
43 [[nodiscard]] bool operator==(const GradientImageParameters &other) const;
44 [[nodiscard]] bool operator!=(const GradientImageParameters &other) const;
45
46 /** @brief Pointer to @ref RgbColorSpace object */
48
49 [[nodiscard]] LchaDouble colorFromValue(qreal value) const;
50 static void render(const QVariant &variantParameters, AsyncImageRenderCallback &callbackObject);
51 void setDevicePixelRatioF(const qreal newDevicePixelRatioF);
52 void setFirstColor(const LchaDouble &newFirstColor);
53 void setGradientLength(const int newGradientLength);
54 void setGradientThickness(const int newGradientThickness);
55 void setSecondColor(const LchaDouble &newFirstColor);
56
57private:
58 /** @internal @brief Only for unit tests. */
59 friend class TestGradientImageParameters;
60
61 // Methods
62 [[nodiscard]] static LchaDouble completlyNormalizedAndBounded(const LchaDouble &color);
63 void updateSecondColor();
64
65 // Data members
66 /** @brief Internal storage of the device pixel ratio as floating point.
67 *
68 * @sa @ref setDevicePixelRatioF() */
69 qreal m_devicePixelRatioF = 1;
70 /** @brief Internal storage of the first color.
71 *
72 * The color is normalized and bound to the LCH color space.
73 * @sa @ref completlyNormalizedAndBounded() */
74 LchaDouble m_firstColorCorrected;
75 /** @brief Internal storage for the gradient length, measured in
76 * physical pixels.
77 *
78 * @sa @ref setGradientLength() */
79 int m_gradientLength = 0;
80 /** @brief Internal storage for the gradient thickness, measured in
81 * physical pixels.
82 *
83 * @sa @ref setGradientThickness() */
84 int m_gradientThickness = 0;
85 /** @brief Internal storage of the image (cache).
86 *
87 * - If <tt>m_image.isNull()</tt> than either no cache is available
88 * or @ref m_gradientLength or @ref m_gradientThickness is <tt>0</tt>.
89 * Before using it, a new image has to be rendered. (If
90 * @ref m_gradientLength or @ref m_gradientThickness is
91 * <tt>0</tt>, this will be extremly fast.)
92 * - If <tt>m_image.isNull()</tt> is <tt>false</tt>, than the cache
93 * is valid and can be used directly. */
94 QImage m_image;
95 /** @brief Internal storage of the second color (corrected and altered
96 * value).
97 *
98 * The color is normalized and bound to the LCH color space. In an
99 * additional step, it has been altered (by increasing or decreasing the
100 * hue component in steps of 360°) to minimize the distance in hue
101 * from this color to @ref m_firstColorCorrected. This is necessary to
102 * easily allow to calculate the intermediate colors of the gradient, so
103 * that they take the shortest way through the color space.
104 * @sa @ref setFirstColor()
105 * @sa @ref setSecondColor()
106 * @sa @ref completlyNormalizedAndBounded()
107 * @sa @ref updateSecondColor() */
108 LchaDouble m_secondColorCorrectedAndAltered;
109};
110
111} // namespace PerceptualColor
112
113Q_DECLARE_METATYPE(PerceptualColor::GradientImageParameters)
114
115#endif // GRADIENTIMAGEPARAMETERS_H
The namespace of this library.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:48:43 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.