cogl/cogl-color.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2008,2009 Intel Corporation.
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  20  *
  21  *
  22  */
  23
  24 /**
  25  * SECTION:cogl-color
  26  * @short_description: A generic color definition
  27  *
  28  * #CoglColor is a simple structure holding the definition of a color such
  29  * that it can be efficiently used by GL
  30  *
  31  * Since: 1.0
  32  */
  33
  34 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
  35 #error "Only <cogl/cogl.h> can be included directly."
  36 #endif
  37
  38 #ifndef __COGL_COLOR_H__
  39 #define __COGL_COLOR_H__
  40
  41 #include <cogl/cogl-types.h>
  42
  43 G_BEGIN_DECLS
  44
  45 /**
  46  * cogl_color_new:
  47  *
  48  * Creates a new (empty) color
  49  *
  50  * Return value: a newly-allocated #CoglColor. Use cogl_color_free()
  51  *   to free the allocated resources
  52  *
  53  * Since: 1.0
  54  */
  55 CoglColor *
  56 cogl_color_new (void);
  57
  58 /**
  59  * cogl_color_copy:
  60  * @color: the color to copy
  61  *
  62  * Creates a copy of @color
  63  *
  64  * Return value: a newly-allocated #CoglColor. Use cogl_color_free()
  65  *   to free the allocate resources
  66  *
  67  * Since: 1.0
  68  */
  69 CoglColor *
  70 cogl_color_copy (const CoglColor *color);
  71
  72 /**
  73  * cogl_color_free:
  74  * @color: the color to free
  75  *
  76  * Frees the resources allocated by cogl_color_new() and cogl_color_copy()
  77  *
  78  * Since: 1.0
  79  */
  80 void
  81 cogl_color_free (CoglColor *color);
  82
  83 /**
  84  * cogl_color_init_from_4ub:
  85  * @color: A pointer to a #CoglColor to initialize
  86  * @red: value of the red channel, between 0 and 255
  87  * @green: value of the green channel, between 0 and 255
  88  * @blue: value of the blue channel, between 0 and 255
  89  * @alpha: value of the alpha channel, between 0 and 255
  90  *
  91  * Sets the values of the passed channels into a #CoglColor.
  92  *
  93  * Since: 1.4
  94  */
  95 void
  96 cogl_color_init_from_4ub (CoglColor *color,
  97                           guint8 red,
  98                           guint8 green,
  99                           guint8 blue,
 100                           guint8 alpha);
 101
 102 /**
 103  * cogl_color_set_from_4ub:
 104  * @color: A pointer to a #CoglColor to initialize
 105  * @red: value of the red channel, between 0 and 255
 106  * @green: value of the green channel, between 0 and 255
 107  * @blue: value of the blue channel, between 0 and 255
 108  * @alpha: value of the alpha channel, between 0 and 255
 109  *
 110  * Sets the values of the passed channels into a #CoglColor.
 111  *
 112  * Since: 1.0
 113  * Deprecated: 1.4: Use cogl_color_init_from_4ub instead.
 114  */
 115 void
 116 cogl_color_set_from_4ub (CoglColor *color,
 117                          guint8 red,
 118                          guint8 green,
 119                          guint8 blue,
 120                          guint8 alpha);
 121
 122 /**
 123  * cogl_color_init_from_4f:
 124  * @color: A pointer to a #CoglColor to initialize
 125  * @red: value of the red channel, between 0 and %1.0
 126  * @green: value of the green channel, between 0 and %1.0
 127  * @blue: value of the blue channel, between 0 and %1.0
 128  * @alpha: value of the alpha channel, between 0 and %1.0
 129  *
 130  * Sets the values of the passed channels into a #CoglColor
 131  *
 132  * Since: 1.4
 133  */
 134 void
 135 cogl_color_init_from_4f (CoglColor *color,
 136                          float red,
 137                          float green,
 138                          float blue,
 139                          float alpha);
 140
 141 /**
 142  * cogl_color_set_from_4f:
 143  * @color: A pointer to a #CoglColor to initialize
 144  * @red: value of the red channel, between 0 and %1.0
 145  * @green: value of the green channel, between 0 and %1.0
 146  * @blue: value of the blue channel, between 0 and %1.0
 147  * @alpha: value of the alpha channel, between 0 and %1.0
 148  *
 149  * Sets the values of the passed channels into a #CoglColor
 150  *
 151  * Since: 1.0
 152  * Deprecated: 1.4: Use cogl_color_init_from_4f instead.
 153  */
 154 void
 155 cogl_color_set_from_4f (CoglColor *color,
 156                         float red,
 157                         float green,
 158                         float blue,
 159                         float alpha);
 160
 161 /**
 162  * cogl_color_init_from_4fv:
 163  * @color: A pointer to a #CoglColor to initialize
 164  * @color_array: a pointer to an array of 4 float color components
 165  *
 166  * Sets the values of the passed channels into a #CoglColor
 167  *
 168  * Since: 1.4
 169  */
 170 void
 171 cogl_color_init_from_4fv (CoglColor *color,
 172                           float *color_array);
 173
 174 /**
 175  * cogl_color_get_red_byte:
 176  * @color: a #CoglColor
 177  *
 178  * Retrieves the red channel of @color as a byte value
 179  * between 0 and 255
 180  *
 181  * Return value: the red channel of the passed color
 182  *
 183  * Since: 1.0
 184  */
 185 unsigned char
 186 cogl_color_get_red_byte (const CoglColor *color);
 187
 188 /**
 189  * cogl_color_get_green_byte:
 190  * @color: a #CoglColor
 191  *
 192  * Retrieves the green channel of @color as a byte value
 193  * between 0 and 255
 194  *
 195  * Return value: the green channel of the passed color
 196  *
 197  * Since: 1.0
 198  */
 199 unsigned char
 200 cogl_color_get_green_byte (const CoglColor *color);
 201
 202 /**
 203  * cogl_color_get_blue_byte:
 204  * @color: a #CoglColor
 205  *
 206  * Retrieves the blue channel of @color as a byte value
 207  * between 0 and 255
 208  *
 209  * Return value: the blue channel of the passed color
 210  *
 211  * Since: 1.0
 212  */
 213 unsigned char
 214 cogl_color_get_blue_byte (const CoglColor *color);
 215
 216 /**
 217  * cogl_color_get_alpha_byte:
 218  * @color: a #CoglColor
 219  *
 220  * Retrieves the alpha channel of @color as a byte value
 221  * between 0 and 255
 222  *
 223  * Return value: the alpha channel of the passed color
 224  *
 225  * Since: 1.0
 226  */
 227 unsigned char
 228 cogl_color_get_alpha_byte (const CoglColor *color);
 229
 230 /**
 231  * cogl_color_get_red_float:
 232  * @color: a #CoglColor
 233  *
 234  * Retrieves the red channel of @color as a floating point
 235  * value between 0.0 and 1.0
 236  *
 237  * Return value: the red channel of the passed color
 238  *
 239  * Since: 1.0
 240  */
 241 float
 242 cogl_color_get_red_float (const CoglColor *color);
 243
 244 /**
 245  * cogl_color_get_green_float:
 246  * @color: a #CoglColor
 247  *
 248  * Retrieves the green channel of @color as a floating point
 249  * value between 0.0 and 1.0
 250  *
 251  * Return value: the green channel of the passed color
 252  *
 253  * Since: 1.0
 254  */
 255 float
 256 cogl_color_get_green_float (const CoglColor *color);
 257
 258 /**
 259  * cogl_color_get_blue_float:
 260  * @color: a #CoglColor
 261  *
 262  * Retrieves the blue channel of @color as a floating point
 263  * value between 0.0 and 1.0
 264  *
 265  * Return value: the blue channel of the passed color
 266  *
 267  * Since: 1.0
 268  */
 269 float
 270 cogl_color_get_blue_float (const CoglColor *color);
 271
 272 /**
 273  * cogl_color_get_alpha_float:
 274  * @color: a #CoglColor
 275  *
 276  * Retrieves the alpha channel of @color as a floating point
 277  * value between 0.0 and 1.0
 278  *
 279  * Return value: the alpha channel of the passed color
 280  *
 281  * Since: 1.0
 282  */
 283 float
 284 cogl_color_get_alpha_float (const CoglColor *color);
 285
 286 /**
 287  * cogl_color_get_red:
 288  * @color: a #CoglColor
 289  *
 290  * Retrieves the red channel of @color as a fixed point
 291  * value between 0 and %1.0.
 292  *
 293  * Return value: the red channel of the passed color
 294  *
 295  * Since: 1.0
 296  */
 297 float
 298 cogl_color_get_red (const CoglColor *color);
 299
 300 /**
 301  * cogl_color_get_green:
 302  * @color: a #CoglColor
 303  *
 304  * Retrieves the green channel of @color as a fixed point
 305  * value between 0 and %1.0.
 306  *
 307  * Return value: the green channel of the passed color
 308  *
 309  * Since: 1.0
 310  */
 311 float
 312 cogl_color_get_green (const CoglColor *color);
 313
 314 /**
 315  * cogl_color_get_blue:
 316  * @color: a #CoglColor
 317  *
 318  * Retrieves the blue channel of @color as a fixed point
 319  * value between 0 and %1.0.
 320  *
 321  * Return value: the blue channel of the passed color
 322  *
 323  * Since: 1.0
 324  */
 325 float
 326 cogl_color_get_blue (const CoglColor *color);
 327
 328 /**
 329  * cogl_color_get_alpha:
 330  * @color: a #CoglColor
 331  *
 332  * Retrieves the alpha channel of @color as a fixed point
 333  * value between 0 and %1.0.
 334  *
 335  * Return value: the alpha channel of the passed color
 336  *
 337  * Since: 1.0
 338  */
 339 float
 340 cogl_color_get_alpha (const CoglColor *color);
 341
 342 /**
 343  * cogl_color_set_red_byte:
 344  * @color: a #CoglColor
 345  * @red: a byte value between 0 and 255
 346  *
 347  * Sets the red channel of @color to @red.
 348  *
 349  * Since: 1.4
 350  */
 351 void
 352 cogl_color_set_red_byte (CoglColor     *color,
 353                          unsigned char  red);
 354
 355 /**
 356  * cogl_color_set_green_byte:
 357  * @color: a #CoglColor
 358  * @green: a byte value between 0 and 255
 359  *
 360  * Sets the green channel of @color to @green.
 361  *
 362  * Since: 1.4
 363  */
 364 void
 365 cogl_color_set_green_byte (CoglColor     *color,
 366                            unsigned char  green);
 367
 368 /**
 369  * cogl_color_set_blue_byte:
 370  * @color: a #CoglColor
 371  * @blue: a byte value between 0 and 255
 372  *
 373  * Sets the blue channel of @color to @blue.
 374  *
 375  * Since: 1.4
 376  */
 377 void
 378 cogl_color_set_blue_byte (CoglColor     *color,
 379                           unsigned char  blue);
 380
 381 /**
 382  * cogl_color_set_alpha_byte:
 383  * @color: a #CoglColor
 384  * @alpha: a byte value between 0 and 255
 385  *
 386  * Sets the alpha channel of @color to @alpha.
 387  *
 388  * Since: 1.4
 389  */
 390 void
 391 cogl_color_set_alpha_byte (CoglColor     *color,
 392                            unsigned char  alpha);
 393
 394 /**
 395  * cogl_color_set_red_float:
 396  * @color: a #CoglColor
 397  * @red: a float value between 0.0f and 1.0f
 398  *
 399  * Sets the red channel of @color to @red.
 400  *
 401  * since: 1.4
 402  */
 403 void
 404 cogl_color_set_red_float (CoglColor *color,
 405                           float      red);
 406
 407 /**
 408  * cogl_color_set_green_float:
 409  * @color: a #CoglColor
 410  * @green: a float value between 0.0f and 1.0f
 411  *
 412  * Sets the green channel of @color to @green.
 413  *
 414  * since: 1.4
 415  */
 416 void
 417 cogl_color_set_green_float (CoglColor *color,
 418                             float      green);
 419
 420 /**
 421  * cogl_color_set_blue_float:
 422  * @color: a #CoglColor
 423  * @blue: a float value between 0.0f and 1.0f
 424  *
 425  * Sets the blue channel of @color to @blue.
 426  *
 427  * since: 1.4
 428  */
 429 void
 430 cogl_color_set_blue_float (CoglColor *color,
 431                            float      blue);
 432
 433 /**
 434  * cogl_color_set_alpha_float:
 435  * @color: a #CoglColor
 436  * @alpha: a float value between 0.0f and 1.0f
 437  *
 438  * Sets the alpha channel of @color to @alpha.
 439  *
 440  * since: 1.4
 441  */
 442 void
 443 cogl_color_set_alpha_float (CoglColor *color,
 444                             float      alpha);
 445
 446 /**
 447  * cogl_color_set_red:
 448  * @color: a #CoglColor
 449  * @red: a float value between 0.0f and 1.0f
 450  *
 451  * Sets the red channel of @color to @red.
 452  *
 453  * Since: 1.4
 454  */
 455 void
 456 cogl_color_set_red (CoglColor *color,
 457                     float      red);
 458
 459 /**
 460  * cogl_color_set_green:
 461  * @color: a #CoglColor
 462  * @green: a float value between 0.0f and 1.0f
 463  *
 464  * Sets the green channel of @color to @green.
 465  *
 466  * Since: 1.4
 467  */
 468 void
 469 cogl_color_set_green (CoglColor *color,
 470                       float      green);
 471
 472 /**
 473  * cogl_color_set_blue:
 474  * @color: a #CoglColor
 475  * @blue: a float value between 0.0f and 1.0f
 476  *
 477  * Sets the blue channel of @color to @blue.
 478  *
 479  * Since: 1.4
 480  */
 481 void
 482 cogl_color_set_blue (CoglColor *color,
 483                      float      blue);
 484
 485 /**
 486  * cogl_color_set_alpha:
 487  * @color: a #CoglColor
 488  * @alpha: a float value between 0.0f and 1.0f
 489  *
 490  * Sets the alpha channel of @color to @alpha.
 491  *
 492  * Since: 1.4
 493  */
 494 void
 495 cogl_color_set_alpha (CoglColor *color,
 496                       float      alpha);
 497
 498 /**
 499  * cogl_color_premultiply:
 500  * @color: the color to premultiply
 501  *
 502  * Converts a non-premultiplied color to a pre-multiplied color. For
 503  * example, semi-transparent red is (1.0, 0, 0, 0.5) when non-premultiplied
 504  * and (0.5, 0, 0, 0.5) when premultiplied.
 505  *
 506  * Since: 1.0
 507  */
 508 void
 509 cogl_color_premultiply (CoglColor *color);
 510
 511 /**
 512  * cogl_color_unpremultiply:
 513  * @color: the color to unpremultiply
 514  *
 515  * Converts a pre-multiplied color to a non-premultiplied color. For
 516  * example, semi-transparent red is (0.5, 0, 0, 0.5) when premultiplied
 517  * and (1.0, 0, 0, 0.5) when non-premultiplied.
 518  *
 519  * Since: 1.4
 520  */
 521 void
 522 cogl_color_unpremultiply (CoglColor *color);
 523
 524 /**
 525  * cogl_color_equal:
 526  * @v1: a #CoglColor
 527  * @v2: a #CoglColor
 528  *
 529  * Compares two #CoglColor<!-- -->s and checks if they are the same.
 530  *
 531  * This function can be passed to g_hash_table_new() as the @key_equal_func
 532  * parameter, when using #CoglColor<!-- -->s as keys in a #GHashTable.
 533  *
 534  * Return value: %TRUE if the two colors are the same.
 535  *
 536  * Since: 1.0
 537  */
 538 gboolean
 539 cogl_color_equal (gconstpointer v1,
 540                   gconstpointer v2);
 541
 542 G_END_DECLS
 543
 544 #endif /* __COGL_COLOR_H__ */