1/*!
2 * \file colorstop.hpp
3 * \brief file colorstop.hpp
4 *
5 * Copyright 2016 by Intel.
6 *
7 * Contact: kevin.rogovin@gmail.com
8 *
9 * This Source Code Form is subject to the
10 * terms of the Mozilla Public License, v. 2.0.
11 * If a copy of the MPL was not distributed with
12 * this file, You can obtain one at
13 * http://mozilla.org/MPL/2.0/.
14 *
15 * \author Kevin Rogovin <kevin.rogovin@gmail.com>
16 *
17 */
18
19
20#ifndef FASTUIDRAW_COLORSTOP_HPP
21#define FASTUIDRAW_COLORSTOP_HPP
22
23#include <fastuidraw/util/util.hpp>
24#include <fastuidraw/util/vecN.hpp>
25#include <fastuidraw/util/c_array.hpp>
26#include <fastuidraw/util/reference_counted.hpp>
27
28namespace fastuidraw
29{
30///@cond
31class ColorStopAtlas;
32///@endcond
33
34/*!\addtogroup Imaging
35 * @{
36 */
37
38 /*!
39 * \brief
40 * A ColorStop is a pair consisting of an RGBA value and a place. The
41 * value of the place is a floating point value in the range [0, 1].
42 */
43 class ColorStop
44 {
45 public:
46 /*!
47 * Default ctor. Initializes m_color as (0, 0, 0, 0)
48 * and m_place as 0.0f.
49 */
50 ColorStop(void):
51 m_color(0, 0, 0, 0),
52 m_place(0.0f)
53 {}
54
55 /*!
56 * Ctor
57 * \param c value with which to initialize m_color
58 * \param p value with which to initialize m_place
59 */
60 ColorStop(u8vec4 c, float p):
61 m_color(c),
62 m_place(p)
63 {}
64
65 /*!
66 * Comparison operator to sort ColorStop values by m_place.
67 * \param rhs value to which to compare
68 */
69 bool
70 operator<(const ColorStop &rhs) const
71 {
72 return m_place < rhs.m_place;
73 }
74
75 /*!
76 * The RGBA value of the color of the ColorStop.
77 */
78 u8vec4 m_color;
79
80 /*!
81 * The place of the ColorStop.
82 */
83 float m_place;
84 };
85
86 /*!
87 * \brief
88 * A ColorStopArray is a sequence of ColorStop values used to
89 * define the color stops of a gradient.
90 *
91 * The values are sorted by ColorStop::m_place and each ColorStop
92 * value of a ColorStopArray must have a unique value for
93 * ColorStop::m_place. A color is computed (in drawing) from a
94 * ColorStopArray at a point q as follows. First the color stops
95 * S and T are found so that q is in the range [S.m_place, T.m_place].
96 * The color value is then given by the value
97 * (1-t) * S.m_color + t * S.m_color where t is given by
98 * (q-S.m_place) / (T.m_place - S.m_place).
99 */
100 class ColorStopArray:noncopyable
101 {
102 public:
103 /*!
104 * Ctor, inits ColorStopArray as empty
105 */
106 ColorStopArray(void);
107
108 /*!
109 * Ctor, inits ColorStopArray as empty
110 * but pre-reserves memory for color stops
111 * added via add().
112 * \param reserve number of slots to reserve in memory
113 */
114 explicit
115 ColorStopArray(int reserve);
116
117 ~ColorStopArray();
118
119 /*!
120 * Add a ColorStop to this ColorStopArray
121 * \param c value to add
122 */
123 void
124 add(const ColorStop &c);
125
126 /*!
127 * Add a sequence of stops.
128 * \tparam iterator type to ColorStop
129 * \param begin iterator to 1st stop to add
130 * \param end iterator to one past the last stop to add
131 */
132 template<typename iterator>
133 void
134 add(iterator begin, iterator end)
135 {
136 for(; begin != end; ++begin)
137 {
138 add(*begin);
139 }
140 }
141
142 /*!
143 * Clear all stops from this ColorStopArray.
144 */
145 void
146 clear(void);
147
148 /*!
149 * Returns the values added by add() sorted by ColorStop::m_place.
150 * Sorting is done lazily, i.e. on calling values().
151 */
152 c_array<const ColorStop>
153 values(void) const;
154
155 private:
156 void *m_d;
157 };
158
159 /*!
160 * \brief
161 * A ColorStopSequence is a \ref ColorStopArray on a \ref ColorStopAtlas.
162 * A \ref ColorStopAtlas is backed by a 1D texture array with linear filtering.
163 * The values of ColorStop::m_place are discretized. Values in between the
164 * \ref ColorStop 's of a \ref ColorStopArray are interpolated.
165 */
166 class ColorStopSequence:public resource_base
167 {
168 public:
169 ~ColorStopSequence();
170
171 /*!
172 * Returns the location in the backing store to
173 * the logical start of the ColorStopSequence.
174 * A ColorStopSequence is added to an atlas
175 * so that the first and last texel are repeated, thus
176 * allowing for implementation to use linear texture
177 * filtering to implement color interpolation quickly
178 * in a shader.
179 */
180 ivec2
181 texel_location(void) const;
182
183 /*!
184 * Returns the number of texels NOT including repeating the
185 * boundary texels used in the backing store.
186 */
187 int
188 width(void) const;
189
190 /*!
191 * Returns the atlas on which the object resides
192 */
193 ColorStopAtlas&
194 atlas(void) const;
195
196 private:
197 friend class ColorStopAtlas;
198
199 ColorStopSequence(const ColorStopArray &color_stops,
200 ColorStopAtlas& atlas, unsigned int pwidth);
201 void *m_d;
202 };
203
204/*! @} */
205}
206
207#endif
208