1 /* 2 * Cogl 3 * 4 * A Low Level GPU Graphics and Utilities API 5 * 6 * Copyright (C) 2008,2009 Intel Corporation. 7 * 8 * Permission is hereby granted, free of charge, to any person 9 * obtaining a copy of this software and associated documentation 10 * files (the "Software"), to deal in the Software without 11 * restriction, including without limitation the rights to use, copy, 12 * modify, merge, publish, distribute, sublicense, and/or sell copies 13 * of the Software, and to permit persons to whom the Software is 14 * furnished to do so, subject to the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be 17 * included in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 23 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 24 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 25 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 26 * SOFTWARE. 27 * 28 * 29 */ 30 31 #if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION) 32 #error "Only <cogl/cogl.h> can be included directly." 33 #endif 34 35 #ifndef __COGL_COLOR_H__ 36 #define __COGL_COLOR_H__ 37 38 /** 39 * SECTION:cogl-color 40 * @short_description: A generic color definition 41 * 42 * #CoglColor is a simple structure holding the definition of a color such 43 * that it can be efficiently used by GL 44 * 45 * Since: 1.0 46 */ 47 48 #include <cogl/cogl-types.h> 49 #include <cogl/cogl-macros.h> 50 51 #include <glib-object.h> 52 53 G_BEGIN_DECLS 54 55 /** 56 * cogl_color_get_gtype: 57 * 58 * Returns: a #GType that can be used with the GLib type system. 59 */ 60 COGL_EXPORT 61 GType cogl_color_get_gtype (void); 62 63 /** 64 * cogl_color_new: 65 * 66 * Creates a new (empty) color 67 * 68 * Return value: a newly-allocated #CoglColor. Use cogl_color_free() 69 * to free the allocated resources 70 * 71 * Since: 1.0 72 */ 73 COGL_EXPORT CoglColor * 74 cogl_color_new (void); 75 76 /** 77 * cogl_color_copy: 78 * @color: the color to copy 79 * 80 * Creates a copy of @color 81 * 82 * Return value: a newly-allocated #CoglColor. Use cogl_color_free() 83 * to free the allocate resources 84 * 85 * Since: 1.0 86 */ 87 COGL_EXPORT CoglColor * 88 cogl_color_copy (const CoglColor *color); 89 90 /** 91 * cogl_color_free: 92 * @color: the color to free 93 * 94 * Frees the resources allocated by cogl_color_new() and cogl_color_copy() 95 * 96 * Since: 1.0 97 */ 98 COGL_EXPORT void 99 cogl_color_free (CoglColor *color); 100 101 /** 102 * cogl_color_init_from_4ub: 103 * @color: A pointer to a #CoglColor to initialize 104 * @red: value of the red channel, between 0 and 255 105 * @green: value of the green channel, between 0 and 255 106 * @blue: value of the blue channel, between 0 and 255 107 * @alpha: value of the alpha channel, between 0 and 255 108 * 109 * Sets the values of the passed channels into a #CoglColor. 110 * 111 * Since: 1.4 112 */ 113 COGL_EXPORT void 114 cogl_color_init_from_4ub (CoglColor *color, 115 uint8_t red, 116 uint8_t green, 117 uint8_t blue, 118 uint8_t alpha); 119 120 /** 121 * cogl_color_init_from_4f: 122 * @color: A pointer to a #CoglColor to initialize 123 * @red: value of the red channel, between 0 and 1.0 124 * @green: value of the green channel, between 0 and 1.0 125 * @blue: value of the blue channel, between 0 and 1.0 126 * @alpha: value of the alpha channel, between 0 and 1.0 127 * 128 * Sets the values of the passed channels into a #CoglColor 129 * 130 * Since: 1.4 131 */ 132 COGL_EXPORT void 133 cogl_color_init_from_4f (CoglColor *color, 134 float red, 135 float green, 136 float blue, 137 float alpha); 138 139 /** 140 * cogl_color_init_from_4fv: 141 * @color: A pointer to a #CoglColor to initialize 142 * @color_array: a pointer to an array of 4 float color components 143 * 144 * Sets the values of the passed channels into a #CoglColor 145 * 146 * Since: 1.4 147 */ 148 COGL_EXPORT void 149 cogl_color_init_from_4fv (CoglColor *color, 150 const float *color_array); 151 152 /** 153 * cogl_color_get_red_byte: 154 * @color: a #CoglColor 155 * 156 * Retrieves the red channel of @color as a byte value 157 * between 0 and 255 158 * 159 * Return value: the red channel of the passed color 160 * 161 * Since: 1.0 162 */ 163 COGL_EXPORT unsigned char 164 cogl_color_get_red_byte (const CoglColor *color); 165 166 /** 167 * cogl_color_get_green_byte: 168 * @color: a #CoglColor 169 * 170 * Retrieves the green channel of @color as a byte value 171 * between 0 and 255 172 * 173 * Return value: the green channel of the passed color 174 * 175 * Since: 1.0 176 */ 177 COGL_EXPORT unsigned char 178 cogl_color_get_green_byte (const CoglColor *color); 179 180 /** 181 * cogl_color_get_blue_byte: 182 * @color: a #CoglColor 183 * 184 * Retrieves the blue channel of @color as a byte value 185 * between 0 and 255 186 * 187 * Return value: the blue channel of the passed color 188 * 189 * Since: 1.0 190 */ 191 COGL_EXPORT unsigned char 192 cogl_color_get_blue_byte (const CoglColor *color); 193 194 /** 195 * cogl_color_get_alpha_byte: 196 * @color: a #CoglColor 197 * 198 * Retrieves the alpha channel of @color as a byte value 199 * between 0 and 255 200 * 201 * Return value: the alpha channel of the passed color 202 * 203 * Since: 1.0 204 */ 205 COGL_EXPORT unsigned char 206 cogl_color_get_alpha_byte (const CoglColor *color); 207 208 /** 209 * cogl_color_get_red_float: 210 * @color: a #CoglColor 211 * 212 * Retrieves the red channel of @color as a floating point 213 * value between 0.0 and 1.0 214 * 215 * Return value: the red channel of the passed color 216 * 217 * Since: 1.0 218 */ 219 COGL_EXPORT float 220 cogl_color_get_red_float (const CoglColor *color); 221 222 /** 223 * cogl_color_get_green_float: 224 * @color: a #CoglColor 225 * 226 * Retrieves the green channel of @color as a floating point 227 * value between 0.0 and 1.0 228 * 229 * Return value: the green channel of the passed color 230 * 231 * Since: 1.0 232 */ 233 COGL_EXPORT float 234 cogl_color_get_green_float (const CoglColor *color); 235 236 /** 237 * cogl_color_get_blue_float: 238 * @color: a #CoglColor 239 * 240 * Retrieves the blue channel of @color as a floating point 241 * value between 0.0 and 1.0 242 * 243 * Return value: the blue channel of the passed color 244 * 245 * Since: 1.0 246 */ 247 COGL_EXPORT float 248 cogl_color_get_blue_float (const CoglColor *color); 249 250 /** 251 * cogl_color_get_alpha_float: 252 * @color: a #CoglColor 253 * 254 * Retrieves the alpha channel of @color as a floating point 255 * value between 0.0 and 1.0 256 * 257 * Return value: the alpha channel of the passed color 258 * 259 * Since: 1.0 260 */ 261 COGL_EXPORT float 262 cogl_color_get_alpha_float (const CoglColor *color); 263 264 /** 265 * cogl_color_get_red: 266 * @color: a #CoglColor 267 * 268 * Retrieves the red channel of @color as a fixed point 269 * value between 0 and 1.0. 270 * 271 * Return value: the red channel of the passed color 272 * 273 * Since: 1.0 274 */ 275 COGL_EXPORT float 276 cogl_color_get_red (const CoglColor *color); 277 278 /** 279 * cogl_color_get_green: 280 * @color: a #CoglColor 281 * 282 * Retrieves the green channel of @color as a fixed point 283 * value between 0 and 1.0. 284 * 285 * Return value: the green channel of the passed color 286 * 287 * Since: 1.0 288 */ 289 COGL_EXPORT float 290 cogl_color_get_green (const CoglColor *color); 291 292 /** 293 * cogl_color_get_blue: 294 * @color: a #CoglColor 295 * 296 * Retrieves the blue channel of @color as a fixed point 297 * value between 0 and 1.0. 298 * 299 * Return value: the blue channel of the passed color 300 * 301 * Since: 1.0 302 */ 303 COGL_EXPORT float 304 cogl_color_get_blue (const CoglColor *color); 305 306 /** 307 * cogl_color_get_alpha: 308 * @color: a #CoglColor 309 * 310 * Retrieves the alpha channel of @color as a fixed point 311 * value between 0 and 1.0. 312 * 313 * Return value: the alpha channel of the passed color 314 * 315 * Since: 1.0 316 */ 317 COGL_EXPORT float 318 cogl_color_get_alpha (const CoglColor *color); 319 320 /** 321 * cogl_color_set_red_byte: 322 * @color: a #CoglColor 323 * @red: a byte value between 0 and 255 324 * 325 * Sets the red channel of @color to @red. 326 * 327 * Since: 1.4 328 */ 329 COGL_EXPORT void 330 cogl_color_set_red_byte (CoglColor *color, 331 unsigned char red); 332 333 /** 334 * cogl_color_set_green_byte: 335 * @color: a #CoglColor 336 * @green: a byte value between 0 and 255 337 * 338 * Sets the green channel of @color to @green. 339 * 340 * Since: 1.4 341 */ 342 COGL_EXPORT void 343 cogl_color_set_green_byte (CoglColor *color, 344 unsigned char green); 345 346 /** 347 * cogl_color_set_blue_byte: 348 * @color: a #CoglColor 349 * @blue: a byte value between 0 and 255 350 * 351 * Sets the blue channel of @color to @blue. 352 * 353 * Since: 1.4 354 */ 355 COGL_EXPORT void 356 cogl_color_set_blue_byte (CoglColor *color, 357 unsigned char blue); 358 359 /** 360 * cogl_color_set_alpha_byte: 361 * @color: a #CoglColor 362 * @alpha: a byte value between 0 and 255 363 * 364 * Sets the alpha channel of @color to @alpha. 365 * 366 * Since: 1.4 367 */ 368 COGL_EXPORT void 369 cogl_color_set_alpha_byte (CoglColor *color, 370 unsigned char alpha); 371 372 /** 373 * cogl_color_set_red_float: 374 * @color: a #CoglColor 375 * @red: a float value between 0.0f and 1.0f 376 * 377 * Sets the red channel of @color to @red. 378 * 379 * since: 1.4 380 */ 381 COGL_EXPORT void 382 cogl_color_set_red_float (CoglColor *color, 383 float red); 384 385 /** 386 * cogl_color_set_green_float: 387 * @color: a #CoglColor 388 * @green: a float value between 0.0f and 1.0f 389 * 390 * Sets the green channel of @color to @green. 391 * 392 * since: 1.4 393 */ 394 COGL_EXPORT void 395 cogl_color_set_green_float (CoglColor *color, 396 float green); 397 398 /** 399 * cogl_color_set_blue_float: 400 * @color: a #CoglColor 401 * @blue: a float value between 0.0f and 1.0f 402 * 403 * Sets the blue channel of @color to @blue. 404 * 405 * since: 1.4 406 */ 407 COGL_EXPORT void 408 cogl_color_set_blue_float (CoglColor *color, 409 float blue); 410 411 /** 412 * cogl_color_set_alpha_float: 413 * @color: a #CoglColor 414 * @alpha: a float value between 0.0f and 1.0f 415 * 416 * Sets the alpha channel of @color to @alpha. 417 * 418 * since: 1.4 419 */ 420 COGL_EXPORT void 421 cogl_color_set_alpha_float (CoglColor *color, 422 float alpha); 423 424 /** 425 * cogl_color_set_red: 426 * @color: a #CoglColor 427 * @red: a float value between 0.0f and 1.0f 428 * 429 * Sets the red channel of @color to @red. 430 * 431 * Since: 1.4 432 */ 433 COGL_EXPORT void 434 cogl_color_set_red (CoglColor *color, 435 float red); 436 437 /** 438 * cogl_color_set_green: 439 * @color: a #CoglColor 440 * @green: a float value between 0.0f and 1.0f 441 * 442 * Sets the green channel of @color to @green. 443 * 444 * Since: 1.4 445 */ 446 COGL_EXPORT void 447 cogl_color_set_green (CoglColor *color, 448 float green); 449 450 /** 451 * cogl_color_set_blue: 452 * @color: a #CoglColor 453 * @blue: a float value between 0.0f and 1.0f 454 * 455 * Sets the blue channel of @color to @blue. 456 * 457 * Since: 1.4 458 */ 459 COGL_EXPORT void 460 cogl_color_set_blue (CoglColor *color, 461 float blue); 462 463 /** 464 * cogl_color_set_alpha: 465 * @color: a #CoglColor 466 * @alpha: a float value between 0.0f and 1.0f 467 * 468 * Sets the alpha channel of @color to @alpha. 469 * 470 * Since: 1.4 471 */ 472 COGL_EXPORT void 473 cogl_color_set_alpha (CoglColor *color, 474 float alpha); 475 476 /** 477 * cogl_color_premultiply: 478 * @color: the color to premultiply 479 * 480 * Converts a non-premultiplied color to a pre-multiplied color. For 481 * example, semi-transparent red is (1.0, 0, 0, 0.5) when non-premultiplied 482 * and (0.5, 0, 0, 0.5) when premultiplied. 483 * 484 * Since: 1.0 485 */ 486 COGL_EXPORT void 487 cogl_color_premultiply (CoglColor *color); 488 489 /** 490 * cogl_color_unpremultiply: 491 * @color: the color to unpremultiply 492 * 493 * Converts a pre-multiplied color to a non-premultiplied color. For 494 * example, semi-transparent red is (0.5, 0, 0, 0.5) when premultiplied 495 * and (1.0, 0, 0, 0.5) when non-premultiplied. 496 * 497 * Since: 1.4 498 */ 499 COGL_EXPORT void 500 cogl_color_unpremultiply (CoglColor *color); 501 502 /** 503 * cogl_color_equal: 504 * @v1: a #CoglColor 505 * @v2: a #CoglColor 506 * 507 * Compares two #CoglColor<!-- -->s and checks if they are the same. 508 * 509 * This function can be passed to g_hash_table_new() as the @key_equal_func 510 * parameter, when using #CoglColor<!-- -->s as keys in a #GHashTable. 511 * 512 * Return value: %TRUE if the two colors are the same. 513 * 514 * Since: 1.0 515 */ 516 COGL_EXPORT gboolean 517 cogl_color_equal (const void *v1, const void *v2); 518 519 /** 520 * cogl_color_to_hsl: 521 * @color: a #CoglColor 522 * @hue: (out): return location for the hue value or %NULL 523 * @saturation: (out): return location for the saturation value or %NULL 524 * @luminance: (out): return location for the luminance value or %NULL 525 * 526 * Converts @color to the HLS format. 527 * 528 * The @hue value is in the 0 .. 360 range. The @luminance and 529 * @saturation values are in the 0 .. 1 range. 530 * 531 * Since: 1.16 532 */ 533 COGL_EXPORT void 534 cogl_color_to_hsl (const CoglColor *color, 535 float *hue, 536 float *saturation, 537 float *luminance); 538 539 /** 540 * cogl_color_init_from_hsl: 541 * @color: (out): return location for a #CoglColor 542 * @hue: hue value, in the 0 .. 360 range 543 * @saturation: saturation value, in the 0 .. 1 range 544 * @luminance: luminance value, in the 0 .. 1 range 545 * 546 * Converts a color expressed in HLS (hue, luminance and saturation) 547 * values into a #CoglColor. 548 * 549 * Since: 1.16 550 */ 551 COGL_EXPORT void 552 cogl_color_init_from_hsl (CoglColor *color, 553 float hue, 554 float saturation, 555 float luminance); 556 557 G_END_DECLS 558 559 #endif /* __COGL_COLOR_H__ */ 560