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 COGL_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 GType cogl_color_get_gtype (void); 61 62 /** 63 * cogl_color_new: 64 * 65 * Creates a new (empty) color 66 * 67 * Return value: a newly-allocated #CoglColor. Use cogl_color_free() 68 * to free the allocated resources 69 * 70 * Since: 1.0 71 */ 72 CoglColor * 73 cogl_color_new (void); 74 75 /** 76 * cogl_color_copy: 77 * @color: the color to copy 78 * 79 * Creates a copy of @color 80 * 81 * Return value: a newly-allocated #CoglColor. Use cogl_color_free() 82 * to free the allocate resources 83 * 84 * Since: 1.0 85 */ 86 CoglColor * 87 cogl_color_copy (const CoglColor *color); 88 89 /** 90 * cogl_color_free: 91 * @color: the color to free 92 * 93 * Frees the resources allocated by cogl_color_new() and cogl_color_copy() 94 * 95 * Since: 1.0 96 */ 97 void 98 cogl_color_free (CoglColor *color); 99 100 /** 101 * cogl_color_init_from_4ub: 102 * @color: A pointer to a #CoglColor to initialize 103 * @red: value of the red channel, between 0 and 255 104 * @green: value of the green channel, between 0 and 255 105 * @blue: value of the blue channel, between 0 and 255 106 * @alpha: value of the alpha channel, between 0 and 255 107 * 108 * Sets the values of the passed channels into a #CoglColor. 109 * 110 * Since: 1.4 111 */ 112 void 113 cogl_color_init_from_4ub (CoglColor *color, 114 uint8_t red, 115 uint8_t green, 116 uint8_t blue, 117 uint8_t alpha); 118 119 /** 120 * cogl_color_set_from_4ub: 121 * @color: A pointer to a #CoglColor to initialize 122 * @red: value of the red channel, between 0 and 255 123 * @green: value of the green channel, between 0 and 255 124 * @blue: value of the blue channel, between 0 and 255 125 * @alpha: value of the alpha channel, between 0 and 255 126 * 127 * Sets the values of the passed channels into a #CoglColor. 128 * 129 * Since: 1.0 130 * Deprecated: 1.4: Use cogl_color_init_from_4ub instead. 131 */ 132 COGL_DEPRECATED_IN_1_4_FOR (cogl_color_init_from_4ub) 133 void 134 cogl_color_set_from_4ub (CoglColor *color, 135 uint8_t red, 136 uint8_t green, 137 uint8_t blue, 138 uint8_t alpha); 139 140 /** 141 * cogl_color_init_from_4f: 142 * @color: A pointer to a #CoglColor to initialize 143 * @red: value of the red channel, between 0 and 1.0 144 * @green: value of the green channel, between 0 and 1.0 145 * @blue: value of the blue channel, between 0 and 1.0 146 * @alpha: value of the alpha channel, between 0 and 1.0 147 * 148 * Sets the values of the passed channels into a #CoglColor 149 * 150 * Since: 1.4 151 */ 152 void 153 cogl_color_init_from_4f (CoglColor *color, 154 float red, 155 float green, 156 float blue, 157 float alpha); 158 159 /** 160 * cogl_color_set_from_4f: 161 * @color: A pointer to a #CoglColor to initialize 162 * @red: value of the red channel, between 0 and %1.0 163 * @green: value of the green channel, between 0 and %1.0 164 * @blue: value of the blue channel, between 0 and %1.0 165 * @alpha: value of the alpha channel, between 0 and %1.0 166 * 167 * Sets the values of the passed channels into a #CoglColor 168 * 169 * Since: 1.0 170 * Deprecated: 1.4: Use cogl_color_init_from_4f instead. 171 */ 172 COGL_DEPRECATED_IN_1_4_FOR (cogl_color_init_from_4f) 173 void 174 cogl_color_set_from_4f (CoglColor *color, 175 float red, 176 float green, 177 float blue, 178 float alpha); 179 180 /** 181 * cogl_color_init_from_4fv: 182 * @color: A pointer to a #CoglColor to initialize 183 * @color_array: a pointer to an array of 4 float color components 184 * 185 * Sets the values of the passed channels into a #CoglColor 186 * 187 * Since: 1.4 188 */ 189 void 190 cogl_color_init_from_4fv (CoglColor *color, 191 const float *color_array); 192 193 /** 194 * cogl_color_get_red_byte: 195 * @color: a #CoglColor 196 * 197 * Retrieves the red channel of @color as a byte value 198 * between 0 and 255 199 * 200 * Return value: the red channel of the passed color 201 * 202 * Since: 1.0 203 */ 204 unsigned char 205 cogl_color_get_red_byte (const CoglColor *color); 206 207 /** 208 * cogl_color_get_green_byte: 209 * @color: a #CoglColor 210 * 211 * Retrieves the green channel of @color as a byte value 212 * between 0 and 255 213 * 214 * Return value: the green channel of the passed color 215 * 216 * Since: 1.0 217 */ 218 unsigned char 219 cogl_color_get_green_byte (const CoglColor *color); 220 221 /** 222 * cogl_color_get_blue_byte: 223 * @color: a #CoglColor 224 * 225 * Retrieves the blue channel of @color as a byte value 226 * between 0 and 255 227 * 228 * Return value: the blue channel of the passed color 229 * 230 * Since: 1.0 231 */ 232 unsigned char 233 cogl_color_get_blue_byte (const CoglColor *color); 234 235 /** 236 * cogl_color_get_alpha_byte: 237 * @color: a #CoglColor 238 * 239 * Retrieves the alpha channel of @color as a byte value 240 * between 0 and 255 241 * 242 * Return value: the alpha channel of the passed color 243 * 244 * Since: 1.0 245 */ 246 unsigned char 247 cogl_color_get_alpha_byte (const CoglColor *color); 248 249 /** 250 * cogl_color_get_red_float: 251 * @color: a #CoglColor 252 * 253 * Retrieves the red channel of @color as a floating point 254 * value between 0.0 and 1.0 255 * 256 * Return value: the red channel of the passed color 257 * 258 * Since: 1.0 259 */ 260 float 261 cogl_color_get_red_float (const CoglColor *color); 262 263 /** 264 * cogl_color_get_green_float: 265 * @color: a #CoglColor 266 * 267 * Retrieves the green channel of @color as a floating point 268 * value between 0.0 and 1.0 269 * 270 * Return value: the green channel of the passed color 271 * 272 * Since: 1.0 273 */ 274 float 275 cogl_color_get_green_float (const CoglColor *color); 276 277 /** 278 * cogl_color_get_blue_float: 279 * @color: a #CoglColor 280 * 281 * Retrieves the blue channel of @color as a floating point 282 * value between 0.0 and 1.0 283 * 284 * Return value: the blue channel of the passed color 285 * 286 * Since: 1.0 287 */ 288 float 289 cogl_color_get_blue_float (const CoglColor *color); 290 291 /** 292 * cogl_color_get_alpha_float: 293 * @color: a #CoglColor 294 * 295 * Retrieves the alpha channel of @color as a floating point 296 * value between 0.0 and 1.0 297 * 298 * Return value: the alpha channel of the passed color 299 * 300 * Since: 1.0 301 */ 302 float 303 cogl_color_get_alpha_float (const CoglColor *color); 304 305 /** 306 * cogl_color_get_red: 307 * @color: a #CoglColor 308 * 309 * Retrieves the red channel of @color as a fixed point 310 * value between 0 and 1.0. 311 * 312 * Return value: the red channel of the passed color 313 * 314 * Since: 1.0 315 */ 316 float 317 cogl_color_get_red (const CoglColor *color); 318 319 /** 320 * cogl_color_get_green: 321 * @color: a #CoglColor 322 * 323 * Retrieves the green channel of @color as a fixed point 324 * value between 0 and 1.0. 325 * 326 * Return value: the green channel of the passed color 327 * 328 * Since: 1.0 329 */ 330 float 331 cogl_color_get_green (const CoglColor *color); 332 333 /** 334 * cogl_color_get_blue: 335 * @color: a #CoglColor 336 * 337 * Retrieves the blue channel of @color as a fixed point 338 * value between 0 and 1.0. 339 * 340 * Return value: the blue channel of the passed color 341 * 342 * Since: 1.0 343 */ 344 float 345 cogl_color_get_blue (const CoglColor *color); 346 347 /** 348 * cogl_color_get_alpha: 349 * @color: a #CoglColor 350 * 351 * Retrieves the alpha channel of @color as a fixed point 352 * value between 0 and 1.0. 353 * 354 * Return value: the alpha channel of the passed color 355 * 356 * Since: 1.0 357 */ 358 float 359 cogl_color_get_alpha (const CoglColor *color); 360 361 /** 362 * cogl_color_set_red_byte: 363 * @color: a #CoglColor 364 * @red: a byte value between 0 and 255 365 * 366 * Sets the red channel of @color to @red. 367 * 368 * Since: 1.4 369 */ 370 void 371 cogl_color_set_red_byte (CoglColor *color, 372 unsigned char red); 373 374 /** 375 * cogl_color_set_green_byte: 376 * @color: a #CoglColor 377 * @green: a byte value between 0 and 255 378 * 379 * Sets the green channel of @color to @green. 380 * 381 * Since: 1.4 382 */ 383 void 384 cogl_color_set_green_byte (CoglColor *color, 385 unsigned char green); 386 387 /** 388 * cogl_color_set_blue_byte: 389 * @color: a #CoglColor 390 * @blue: a byte value between 0 and 255 391 * 392 * Sets the blue channel of @color to @blue. 393 * 394 * Since: 1.4 395 */ 396 void 397 cogl_color_set_blue_byte (CoglColor *color, 398 unsigned char blue); 399 400 /** 401 * cogl_color_set_alpha_byte: 402 * @color: a #CoglColor 403 * @alpha: a byte value between 0 and 255 404 * 405 * Sets the alpha channel of @color to @alpha. 406 * 407 * Since: 1.4 408 */ 409 void 410 cogl_color_set_alpha_byte (CoglColor *color, 411 unsigned char alpha); 412 413 /** 414 * cogl_color_set_red_float: 415 * @color: a #CoglColor 416 * @red: a float value between 0.0f and 1.0f 417 * 418 * Sets the red channel of @color to @red. 419 * 420 * since: 1.4 421 */ 422 void 423 cogl_color_set_red_float (CoglColor *color, 424 float red); 425 426 /** 427 * cogl_color_set_green_float: 428 * @color: a #CoglColor 429 * @green: a float value between 0.0f and 1.0f 430 * 431 * Sets the green channel of @color to @green. 432 * 433 * since: 1.4 434 */ 435 void 436 cogl_color_set_green_float (CoglColor *color, 437 float green); 438 439 /** 440 * cogl_color_set_blue_float: 441 * @color: a #CoglColor 442 * @blue: a float value between 0.0f and 1.0f 443 * 444 * Sets the blue channel of @color to @blue. 445 * 446 * since: 1.4 447 */ 448 void 449 cogl_color_set_blue_float (CoglColor *color, 450 float blue); 451 452 /** 453 * cogl_color_set_alpha_float: 454 * @color: a #CoglColor 455 * @alpha: a float value between 0.0f and 1.0f 456 * 457 * Sets the alpha channel of @color to @alpha. 458 * 459 * since: 1.4 460 */ 461 void 462 cogl_color_set_alpha_float (CoglColor *color, 463 float alpha); 464 465 /** 466 * cogl_color_set_red: 467 * @color: a #CoglColor 468 * @red: a float value between 0.0f and 1.0f 469 * 470 * Sets the red channel of @color to @red. 471 * 472 * Since: 1.4 473 */ 474 void 475 cogl_color_set_red (CoglColor *color, 476 float red); 477 478 /** 479 * cogl_color_set_green: 480 * @color: a #CoglColor 481 * @green: a float value between 0.0f and 1.0f 482 * 483 * Sets the green channel of @color to @green. 484 * 485 * Since: 1.4 486 */ 487 void 488 cogl_color_set_green (CoglColor *color, 489 float green); 490 491 /** 492 * cogl_color_set_blue: 493 * @color: a #CoglColor 494 * @blue: a float value between 0.0f and 1.0f 495 * 496 * Sets the blue channel of @color to @blue. 497 * 498 * Since: 1.4 499 */ 500 void 501 cogl_color_set_blue (CoglColor *color, 502 float blue); 503 504 /** 505 * cogl_color_set_alpha: 506 * @color: a #CoglColor 507 * @alpha: a float value between 0.0f and 1.0f 508 * 509 * Sets the alpha channel of @color to @alpha. 510 * 511 * Since: 1.4 512 */ 513 void 514 cogl_color_set_alpha (CoglColor *color, 515 float alpha); 516 517 /** 518 * cogl_color_premultiply: 519 * @color: the color to premultiply 520 * 521 * Converts a non-premultiplied color to a pre-multiplied color. For 522 * example, semi-transparent red is (1.0, 0, 0, 0.5) when non-premultiplied 523 * and (0.5, 0, 0, 0.5) when premultiplied. 524 * 525 * Since: 1.0 526 */ 527 void 528 cogl_color_premultiply (CoglColor *color); 529 530 /** 531 * cogl_color_unpremultiply: 532 * @color: the color to unpremultiply 533 * 534 * Converts a pre-multiplied color to a non-premultiplied color. For 535 * example, semi-transparent red is (0.5, 0, 0, 0.5) when premultiplied 536 * and (1.0, 0, 0, 0.5) when non-premultiplied. 537 * 538 * Since: 1.4 539 */ 540 void 541 cogl_color_unpremultiply (CoglColor *color); 542 543 /** 544 * cogl_color_equal: 545 * @v1: a #CoglColor 546 * @v2: a #CoglColor 547 * 548 * Compares two #CoglColor<!-- -->s and checks if they are the same. 549 * 550 * This function can be passed to g_hash_table_new() as the @key_equal_func 551 * parameter, when using #CoglColor<!-- -->s as keys in a #GHashTable. 552 * 553 * Return value: %TRUE if the two colors are the same. 554 * 555 * Since: 1.0 556 */ 557 CoglBool 558 cogl_color_equal (const void *v1, const void *v2); 559 560 /** 561 * cogl_color_to_hsl: 562 * @color: a #CoglColor 563 * @hue: (out): return location for the hue value or %NULL 564 * @saturation: (out): return location for the saturation value or %NULL 565 * @luminance: (out): return location for the luminance value or %NULL 566 * 567 * Converts @color to the HLS format. 568 * 569 * The @hue value is in the 0 .. 360 range. The @luminance and 570 * @saturation values are in the 0 .. 1 range. 571 * 572 * Since: 1.16 573 */ 574 void 575 cogl_color_to_hsl (const CoglColor *color, 576 float *hue, 577 float *saturation, 578 float *luminance); 579 580 /** 581 * cogl_color_init_from_hsl: 582 * @color: (out): return location for a #CoglColor 583 * @hue: hue value, in the 0 .. 360 range 584 * @saturation: saturation value, in the 0 .. 1 range 585 * @luminance: luminance value, in the 0 .. 1 range 586 * 587 * Converts a color expressed in HLS (hue, luminance and saturation) 588 * values into a #CoglColor. 589 * 590 * Since: 1.16 591 */ 592 void 593 cogl_color_init_from_hsl (CoglColor *color, 594 float hue, 595 float saturation, 596 float luminance); 597 598 COGL_END_DECLS 599 600 #endif /* __COGL_COLOR_H__ */ 601