489c07167a7b16c840f341d6cf71a98add818772
[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      */
71     static void getDirectColor(double s, double* colormap, int colormapSize, float* returnedColor);
72
73     /**
74      * Outputs an RGB color directly mapped to a scalar value s.
75      * The output color is looked up in an RGB colormap, using s as a direct index.
76      * White and black are respectively output when s <= -3 and -3 < s < 0 ; s is also
77      * clamped to the colormap's upper bound (colormapSize-1). If s is a Nan value, black is also
78      * output.
79      * @param[in] the scalar value used as an index.
80      * @param[in] a pointer to the colormap used.
81      * @param[in] the colormap's size.
82      * @param[out] a pointer to the array into which the resulting color is output (its R, G, B components are written consecutively).
83      */
84     static void getDirectByteColor(double s, double* colormap, int colormapSize, unsigned char* returnedColor);
85
86     /**
87      * Returns a colormap index from a scalar value s.
88      * Indices corresponding to white and black are respectively output when -4 < s <= -3 and -3 < s < 0;
89      * if s <= -4, the lower colormap index is returned (0).
90      * s is also clamped to the colormap's uppderbound (colormapSize-1).
91      * @param[in] the scalar value used as an index.
92      * @param[in] the colormap's size.
93      * @return the index obtained from s.
94      */
95     static double getDirectIndex(double s, int colormapSize);
96
97     /**
98      * Outputs an RGB color directly mapped to a scalar value s.
99      * The output color is looked up in an RGB colormap, using s as a direct index,
100      * which is clamped to the colormap bounds, that is [0, colormapSize-1] . If s is a Nan value,
101      * the black color is output.
102      * @param[in] the scalar value used as an index.
103      * @param[in] a pointer to the colormap used.
104      * @param[in] the colormap's size.
105      * @param[out] a pointer to the array into which the resulting color is output (its R, G, B components are written consecutively).
106      */
107     static void getClampedDirectColor(double s, double* colormap, int colormapSize, float* returnedColor);
108
109     /**
110      * Returns the given index rounded down and clamped to the colormap size.
111      * @param[in] the scalar value used as an index.
112      * @param[in] the colormap's size.
113      * @return the index clamped to the colormap size.
114      */
115     static double getClampedDirectIndex(double s, int colormapSize);
116
117     /**
118      * Returns a colormap index mapped to a scalar value s belonging to an [smin, smax] interval.
119      * The index belongs to an [imin, imax] interval which is linearly mapped to s, smin and smax respectively
120      * corresponding to the imin and imax indices. The computed index is rounded down and then clamped to
121      * the [imin, imax] interval.
122      * It neither checks whether srange is greater than 0 nor verifies than minIndex and maxIndex are valid colormap
123      * indices.
124      * @param[in] the scalar value.
125      * @param[in] the scale value's minimum value.
126      * @param[in] the scalar value interval's range (smax-smin).
127      * @param[in] an offset added to the index computed from s.
128      * @param[in] the index specifying the index interval's lower bound.
129      * @param[in] the index specifying the index interval's upper bound.
130      * @return the computed index.
131      */
132     static double getIndex(double s, double smin, double srange, double indexOffset, int minIndex, int maxIndex);
133 };
134
135 /**
136  * Offset passed to the getColor function for colors mapped to z values.
137  */
138 #define Z_COLOR_OFFSET    0.5
139
140 /**
141  * Offset passed to the getColor function for linearly mapped colors.
142  */
143 #define COLOR_OFFSET      0.1
144
145 /**
146  * Special color index values.
147  */
148 enum SpecialColorIndexValues {
149     WHITE_LOWER_INDEX = -4,
150     BLACK_LOWER_INDEX = -3,
151     BLACK_UPPER_INDEX = 0
152 };
153
154 /**
155  * The minimum value of a single R, G or B component.
156  */
157 #define MIN_COMPONENT_VALUE    0.0
158
159 /**
160  * The maximum value of a single R, G or B component.
161  */
162 #define MAX_COMPONENT_VALUE    1.0
163
164 /**
165  * The index value corresponding to white.
166  */
167 #define WHITE_INDEX    -2.0
168
169 /**
170  * The index value corresponding to black.
171  */
172 #define BLACK_INDEX    -1.0
173
174 /**
175  * An offset used to center the color index when computing
176  * colormap texture coordinates.
177  */
178 #define COLOR_TEXTURE_OFFSET    0.5
179
180 #endif