bdb1ef6ab858409f48effe2de67d9545e173467d
[scilab.git] / scilab / modules / graphic_objects / includes / ColorComputer.hxx
1 /*
2  *  Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
3  *  Copyright (C) 2011 - DIGITEO - Manuel Juliachs
4  *
5  *  This file must be used under the terms of the CeCILL.
6  *  This source file is licensed as described in the file COPYING, which
7  *  you should have received as part of this distribution.  The terms
8  *  are also available at
9  *  http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
10  *
11  */
12
13 #ifndef COLORCOMPUTER_HXX
14 #define COLORCOMPUTER_HXX
15
16 /**
17  * ColorComputer class
18  * Various utility functions used to compute colors.
19  * To be extended.
20  */
21 class ColorComputer
22 {
23
24 public :
25
26     /**
27      * Ouputs an RGB color mapped to a scalar value s belonging to an [smin, smax] interval.
28      * The output color is looked up in an RGB colormap, using a linear mapping between the latter and s.
29      * It does not currently check whether srange is greater than 0.
30      * If s is a Nan value, the black color is output.
31      * @param[in] the scalar value.
32      * @param[in] the interval's minimum value.
33      * @param[in] the interval's range (smax-smin).
34      * @param[in] an offset added to the index computed from s.
35      * @param[in] a pointer to the colormap used.
36      * @param[in] the colormap's size.
37      * @param[out] a pointer to the array into which the resulting color is output (its R, G, B components are written consecutively).
38      */
39     static void getColor(double s, double smin, double srange, double indexOffset, double* colormap, int colormapSize, float* returnedColor);
40
41     /**
42      * Outputs an RGB color mapped to a scalar value s belonging to an [smin, smax] interval.
43      * The output color is looked up in an RGB colormap, using a linear mapping between a sub-interval of the latter and s.
44      * It neither checks whether srange is greater than 0 nor verifies that the sub-interval is included within the colormap's
45      * range (which must be ensured when specifying the sub-interval's bounds).
46      * If s is a Nan value, the black color is output.
47      * @param[in] the scalar value.
48      * @param[in] the interval's minimum value.
49      * @param[in] the interval's range (smax-smin).
50      * @param[in] an offset added to the index computed from s.
51      * @param[in] a pointer to the colormap used.
52      * @param[in] the colormap's size.
53      * @param[in] the index specifying the colormap sub-interval's lower bound.
54      * @param[in] the index specifying the colormap sub-interval's upper bound.
55      * @param[out] a pointer to the array into which the resulting color is output (its R, G, B components are written consecutively).
56      */
57     static void getColor(double s, double smin, double srange, double indexOffset, double* colormap, int minIndex, int maxIndex,
58                          int colormapSize, float* returnedColor);
59
60     /**
61      * Outputs an RGB color directly mapped to a scalar value s.
62      * The output color is looked up in an RGB colormap, using s as a direct index.
63      * White and black are respectively output when s <= -3 and -3 < s < 0 ; s is also
64      * clamped to the colormap's upper bound (colormapSize-1). If s is a Nan value, black is also
65      * output.
66      * @param[in] the scalar value used as an index.
67      * @param[in] a pointer to the colormap used.
68      * @param[in] the colormap's size.
69      * @param[out] a pointer to the array into which the resulting color is output (its R, G, B components are written consecutively).
70      * @param[in] a boolean to indicate if the color is clamped (by default true).
71      */
72     static void getDirectColor(double s, double* colormap, int colormapSize, float* returnedColor, bool clamped = true);
73
74     /**
75      * Outputs an RGB color directly mapped to a scalar value s.
76      * The output color is looked up in an RGB colormap, using s as a direct index.
77      * White and black are respectively output when s <= -3 and -3 < s < 0 ; s is also
78      * clamped to the colormap's upper bound (colormapSize-1). If s is a Nan value, black is also
79      * output.
80      * @param[in] the scalar value used as an index.
81      * @param[in] a pointer to the colormap used.
82      * @param[in] the colormap's size.
83      * @param[out] a pointer to the array into which the resulting color is output (its R, G, B components are written consecutively).
84      * @param[in] a boolean to indicate if the color is clamped (by default true).
85      */
86     static void getDirectByteColor(double s, double* colormap, int colormapSize, unsigned char* returnedColor, bool clamped = true);
87
88     /**
89      * Returns a colormap index from a scalar value s.
90      * Indices corresponding to white and black are respectively output when -4 < s <= -3 and -3 < s < 0;
91      * if s <= -4, the lower colormap index is returned (0).
92      * s is also clamped to the colormap's uppderbound (colormapSize-1).
93      * @param[in] the scalar value used as an index.
94      * @param[in] the colormap's size.
95      * @return the index obtained from s.
96      */
97     static double getDirectIndex(double s, int colormapSize);
98
99     /**
100      * Outputs an RGB color directly mapped to a scalar value s.
101      * The output color is looked up in an RGB colormap, using s as a direct index,
102      * which is clamped to the colormap bounds, that is [0, colormapSize-1] . If s is a Nan value,
103      * the black color is output.
104      * @param[in] the scalar value used as an index.
105      * @param[in] a pointer to the colormap used.
106      * @param[in] the colormap's size.
107      * @param[out] a pointer to the array into which the resulting color is output (its R, G, B components are written consecutively).
108      */
109     static void getClampedDirectColor(double s, double* colormap, int colormapSize, float* returnedColor);
110
111     /**
112      * Returns the given index rounded down and clamped to the colormap size.
113      * @param[in] the scalar value used as an index.
114      * @param[in] the colormap's size.
115      * @return the index clamped to the colormap size.
116      */
117     static double getClampedDirectIndex(double s, int colormapSize);
118
119     /**
120      * Returns a colormap index mapped to a scalar value s belonging to an [smin, smax] interval.
121      * The index belongs to an [imin, imax] interval which is linearly mapped to s, smin and smax respectively
122      * corresponding to the imin and imax indices. The computed index is rounded down and then clamped to
123      * the [imin, imax] interval.
124      * It neither checks whether srange is greater than 0 nor verifies than minIndex and maxIndex are valid colormap
125      * indices.
126      * @param[in] the scalar value.
127      * @param[in] the scale value's minimum value.
128      * @param[in] the scalar value interval's range (smax-smin).
129      * @param[in] an offset added to the index computed from s.
130      * @param[in] the index specifying the index interval's lower bound.
131      * @param[in] the index specifying the index interval's upper bound.
132      * @return the computed index.
133      */
134     static double getIndex(double s, double smin, double srange, double indexOffset, int minIndex, int maxIndex);
135 };
136
137 /**
138  * Offset passed to the getColor function for colors mapped to z values.
139  */
140 #define Z_COLOR_OFFSET    0.5
141
142 /**
143  * Offset passed to the getColor function for linearly mapped colors.
144  */
145 #define COLOR_OFFSET      0.1
146
147 /**
148  * Special color index values.
149  */
150 enum SpecialColorIndexValues
151 {
152     WHITE_LOWER_INDEX = -4,
153     BLACK_LOWER_INDEX = -3,
154     BLACK_UPPER_INDEX = 0
155 };
156
157 /**
158  * The minimum value of a single R, G or B component.
159  */
160 #define MIN_COMPONENT_VALUE    0.0
161
162 /**
163  * The maximum value of a single R, G or B component.
164  */
165 #define MAX_COMPONENT_VALUE    1.0
166
167 /**
168  * The index value corresponding to white.
169  */
170 #define WHITE_INDEX    -2.0
171
172 /**
173  * The index value corresponding to black.
174  */
175 #define BLACK_INDEX    -1.0
176
177 /**
178  * An offset used to center the color index when computing
179  * colormap texture coordinates.
180  */
181 #define COLOR_TEXTURE_OFFSET    0.5
182
183 #endif
184