BRL-CAD
color.h
Go to the documentation of this file.
1 /* C O L O R . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 
21 /** @file color.h
22  */
23 #ifndef BU_COLOR_H
24 #define BU_COLOR_H
25 
26 #include "common.h"
27 
28 #include "bu/defines.h"
29 #include "bu/magic.h"
30 
32 
33 /*----------------------------------------------------------------------*/
34 
35 /** @addtogroup color */
36 /** @{ */
37 /** @file libbu/color.c */
38 
39 #define RED 0
40 #define GRN 1
41 #define BLU 2
42 
43 #define HUE 0
44 #define SAT 1
45 #define VAL 2
46 
47 #define ACHROMATIC -1.0
48 
49 struct bu_color
50 {
51  uint32_t buc_magic;
53 };
54 typedef struct bu_color bu_color_t;
55 #define BU_COLOR_NULL ((struct bu_color *) 0)
56 
57 /**
58  * asserts the integrity of a bu_color struct.
59  */
60 #define BU_CK_COLOR(_c) BU_CKMAG(_c, BU_COLOR_MAGIC, "bu_color")
61 
62 /**
63  * initializes a bu_bitv struct without allocating any memory.
64  */
65 #define BU_COLOR_INIT(_c) { \
66  (_c)->buc_magic = BU_COLOR_MAGIC; \
67  (_c)->buc_rgb[0] = (_c)->buc_rgb[1] = (_c)->buc_rgb[2] = 0; \
68  }
69 
70 /**
71  * macro suitable for declaration statement initialization of a bu_color
72  * struct. does not allocate memory.
73  */
74 #define BU_COLOR_INIT_ZERO { BU_COLOR_MAGIC, {0, 0, 0} }
75 
76 /**
77  * returns truthfully whether a bu_color has been initialized
78  */
79 #define BU_COLOR_IS_INITIALIZED(_c) (((struct bu_color *)(_c) != BU_COLOR_NULL) && LIKELY((_c)->magic == BU_COLOR_MAGIC))
80 
81 /**
82  * Function to generate random color
83  *
84  * TODO - multiple possibilities here - truly random color,
85  * or "constrained" random aka the BRLCADWrapper:getRandomColor
86  * function. Need a function that provides flexibility. Possible
87  * calling syntax:
88  @code
89  * bu_color_rand(cp, NULL, NULL, NULL, 0); #generate a totally random color value
90  * bu_color_rand(cp, NULL, rgb_seed, NULL, COLOR_SET_R); #randomize the R value only, else use rgb_seed values
91  * bu_color_rand(cp, NULL, rgb_seed, NULL, COLOR_GOLDEN); #use the golden ratio constraining technique
92  * bu_color_rand(cp, NULL, NULL, hsv_seed, COLOR_GOLDEN); #use the golden ratio constraining technique with an hsv input
93  * bu_color_rand(cp, seed, NULL, NULL, 0); #randomize, using bu_color seed
94  @endcode
95  * Passing multiple seeds would be an error - the multiple slots are for formatting convenience. May be
96  * better to use just one bu_color seed and make callers pre-package it - not sure yet. If we go that
97  * route, we'll have to implement the unimplemented utility functions below.
98  *
99  */
100 #if 0
101 #define COLOR_SET_R 0x1
102 #define COLOR_SET_G 0x2
103 #define COLOR_SET_B 0x4
104 #define COLOR_SET_RGB 0x7 /* Either 0x0 or 0x7 will do this - default behavior */
105 #define COLOR_GOLDEN 0x8 /* Needs seed color */
106 BU_EXPORT extern int bu_color_rand(struct bu_color *cp,
107  const struct bu_color *seed,
108  const unsigned char *seed_rgb,
109  const fastf_t *seed_hsv,
110  int flags);
111 #endif
112 
113 /**
114  * Convert between RGB and HSV color models
115  *
116  * R, G, and B are in {0, 1, ..., 255},
117  *
118  * H is in [0.0, 360.0), and S and V are in [0.0, 1.0],
119  *
120  * unless S = 0.0, in which case H = ACHROMATIC.
121  *
122  * These two routines are adapted from:
123  * pp. 592-3 of J.D. Foley, A. van Dam, S.K. Feiner, and J.F. Hughes,
124  * _Computer graphics: principles and practice_, 2nd ed., Addison-Wesley,
125  * Reading, MA, 1990.
126  */
127 BU_EXPORT extern void bu_rgb_to_hsv(unsigned char *rgb, fastf_t *hsv);
128 BU_EXPORT extern int bu_hsv_to_rgb(fastf_t *hsv, unsigned char *rgb);
129 
130 
131 /**
132  * Utility functions to convert between various containers
133  * for color handling
134  */
135 BU_EXPORT extern int bu_str_to_rgb(char *str, unsigned char *rgb);
136 BU_EXPORT extern int bu_color_from_rgb_floats(struct bu_color *cp, fastf_t *rgb);
137 BU_EXPORT extern int bu_color_to_rgb_floats(struct bu_color *cp, fastf_t *rgb);
138 
139 /* UNIMPLEMENTED
140  *
141  * BU_EXPORT export void bu_color_from_rgb_chars(struct bu_color *cp, unsigned char *rgb);
142  * BU_EXPORT export int bu_color_to_rgb_chars(struct bu_color *cp, unsigned char *rgb);
143  * BU_EXPORT export int bu_color_from_hsv_floats(struct bu_color *cp, fastf_t *hsv);
144  * BU_EXPORT export int bu_color_to_hsv_floats(struct bu_color *cp, fastf_t *hsv);
145  */
146 
147 
148 /** @} */
149 
151 
152 #endif /* BU_COLOR_H */
153 
154 /*
155  * Local Variables:
156  * mode: C
157  * tab-width: 8
158  * indent-tabs-mode: t
159  * c-file-style: "stroustrup"
160  * End:
161  * ex: shiftwidth=4 tabstop=8
162  */
int bu_hsv_to_rgb(fastf_t *hsv, unsigned char *rgb)
Definition: color.c:121
int bu_str_to_rgb(char *str, unsigned char *rgb)
Definition: color.c:178
fastf_t buc_rgb[3]
Definition: color.h:52
Header file for the BRL-CAD common definitions.
void bu_rgb_to_hsv(unsigned char *rgb, fastf_t *hsv)
Definition: color.c:60
int bu_color_to_rgb_floats(struct bu_color *cp, fastf_t *rgb)
Definition: color.c:220
#define __BEGIN_DECLS
Definition: common.h:73
int bu_color_from_rgb_floats(struct bu_color *cp, fastf_t *rgb)
Definition: color.c:235
uint32_t buc_magic
Definition: color.h:51
#define __END_DECLS
Definition: common.h:74
double fastf_t
Definition: defines.h:300
Definition: color.h:49