aboutsummaryrefslogblamecommitdiffstats
path: root/doc/info/chap/colour-spaces.texinfo
blob: 89e7677205a52e1609544e4088d2bed33e4e713a (plain) (tree)
1
2
3
4
5
6
7
8
9
10
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673


                      




                                                                                  

                                                              



                                                                  











                                                                
                                                             
                                                        
                                                             








                                                               
                                          



















                                                           
                                          

























































                                                            
                                      


















                                                         
                                      


















                                                       
                                      




                                                       
                                                       























































































                                                         



































































































































































































































































































































































































































                                                                       

          
























































                                                                                                    
      












































                                                          











                                                          

















                                                          











                                                                       





                                                        











                                                         

             
      


                                                         






























                                                          
     




















































                                                                      
                            



                                            

                                                 
                                          

                                                  
























                                                                   
                                                        

                                                           

                                                            




















                                                                    
 






                                                            
                                                         




























                                                                       
 








                                                              
                                      


                                                    
                                              






























                                                                       
































































                                                                  
@node Colour Spaces
@chapter Colour Spaces

@menu
* RGB Conversion::                          RGB colour space conversion functions.
@end menu


@command{libclut} has a number of functions for converting
between colour space models. The supported colour space models
are [0, 1] sRGB, [0, 1] linear sRGB, CIE xyY, CIE XYZ, CIE L*a*b*,
CIE 1976 (L*, u*, v*), CIELCh@sub{uv}, YIQ, YD@sub{b}D@sub{r},
YP@sub{b}P@sub{r}, YCgCo, CIE 1960 USC, CIE U*V*W*,

These functions are implemented as macros, but regular functions
are available either by putting the name in the function is
brackets, taking the address of the function, or by undefining
the macro with the name of the function.

@command{libclut} has two functions intended for internal use.
If the macro verions are used, their parameter must not have
any side-effets. Additionally their macro versions require
linking with @option{-lm}.

@table @code
@item double libclut_model_linear_to_standard1(double c)
Convert one component from [0, 1] linear sRGB to [0, 1] sRGB.
@item double libclut_model_standard_to_linear1(double c)
Convert one component from [0, 1] sRGB to [0, 1] linear sRGB.
@end table

@command{libclut} has ten functions that are intended for the
user to use, but some are used internally too. These functions'
parameters may have side-effects. All parameters are of the
type @code{double}, and they do not have a return value.

@table @code
@item libclut_model_linear_to_standard(*r. *g, *b)
Convert [0, 1] linear sRGB to [0, 1] sRGB.

The macro variant requires linking with @option{-lm}, if
the @code{libclut_model_linear_to_standard1} is defined,
otherwise it requires linking with @option{-lclut}.

Parameters:
@table @code
@item r
Pointer to the linear red component, and output parameter
for the red component.
@item g
Pointer to the linear green component, and output parameter
for the green component.
@item b
Pointer to the linear blue component, and output parameter
for the blue component.
@end table


@item libclut_model_standard_to_linear(*r, *g, *b)
Convert [0, 1] sRGB to [0, 1] linear sRGB.

The macro variant requires linking with @option{-lm}, if
the @code{libclut_model_standard_to_linear1} is defined,
otherwise it requires linking with @option{-lclut}.

Parameters:
@table @code
@item r
Pointer to the red component, and output parameter for the
linear red component.
@item g
Pointer to the green component, and output parameter for the
linear green component.
@item b
Pointer to the blue component, and output parameter for the
linear blue component.
@end table


@item libclut_model_ciexyy_to_ciexyz(x, y, Y, *X, *Z)
Convert CIE xyY to CIE XYZ.

Parameters:
@table @code
@item x
The x parameter.
@item y
The y parameter.
@item Y
The Y parameter. This is also the Y (middle) parameter
for the CIE XYZ colour.
@item X
Output parameter for the X parameter.
@item Z
Output parameter for the Z parameter.
@end table


@item libclut_model_ciexyz_to_ciexyy(X, Y, Z, *x, *y)
Convert CIE XYZ to CIE xyY.

Parameters:
@table @code
@item X
The X parameter.
@item Y
The Y parameter. This is also the Y (last) parameter
for the CIE xyY colour.
@item Z
The Z parameter.
@item x
Output parameter for the x parameter.
@item y
Output parameter for the y parameter.
@end table


@item libclut_model_ciexyz_to_linear(X, Y, Z, *r, *g, *b)
Convert CIE XYZ to [0, 1] linear sRGB.

Parameters:
@table @code
@item X
The X parameter.
@item Y
The Y parameter.
@item Z
The Z parameter.
@item r
Output parameter for the red component.
@item g
Output parameter for the green component.
@item b
Output parameter for the blue component.
@end table


@item libclut_model_linear_to_ciexyz(r, g, b, *X, *Y, *Z)
Convert [0, 1] linear sRGB to CIE XYZ.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item X
Output parameter for the X parameter.
@item Y
Output parameter for the Y parameter.
@item Z
Output parameter for the Z parameter.
@end table


@item libclut_model_srgb_to_ciexyy(r, g, b, *x, *y, *Y)
Convert [0, 1] linear sRGB to CIE xyY.

The macro variant requires linking with @option{-lclut}
if any of @code{libclut_model_ciexyz_to_ciexyy},
@code{libclut_model_linear_to_ciexyz}, and
@code{libclut_model_standard_to_linear} are undefined.
The macro variant requires linking with @option{-lm} if
neither @code{libclut_model_standard_to_linear} nor
@code{libclut_model_standard_to_linear1} are undefined.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item x
Output parameter for the x parameter.
@item y
Output parameter for the y parameter.
@item Y
Output parameter for the Y parameter.
@end table


@item libclut_model_ciexyy_to_srgb(x, y, Y, *r, *g, *b)
Convert CIE xyY to [0, 1] sRGB.

The macro variant requires linking with @option{-lclut}
if any of @code{libclut_model_ciexyy_to_ciexyz},
@code{libclut_model_ciexyz_to_linear}, and
@code{libclut_model_linear_to_standard} are undefined.
The macro variant requires linking with @option{-lm} if
neither @code{libclut_model_linear_to_standard} nor
@code{libclut_model_linear_to_standard1} are undefined.

Parameters:
@table @code
@item x
The x parameter.
@item y
The y parameter.
@item Y
The Y parameter.
@item r
Output parameter for the red component.
@item g
Output parameter for the green component.
@item b
Output parameter for the blue component.
@end table


@item libclut_model_ciexyz_to_cielab(X, Y, Z, *L, *a, *b)
Convert from CIE XYZ to CIE L*a*b*.

The macro variant requires linking with @option{-lm}.

Parameters:
@table @code
@item X
The X parameter.
@item Y
The Y parameter.
@item Z
The Z parameter.
@item L
Output parameter for the L* component.
@item a
Output parameter for the a* component.
@item b
Output parameter for the b* component.
@end table


@item libclut_model_cielab_to_ciexyz(L, a, b, *X, *Y, *Z)
Convert from CIE L*a*b* to CIE XYZ.

Parameters:
@table @code
@item L
The L* component.
@item a
The a* component.
@item b
The b* component.
@item X
Output parameter for the X parameter.
@item Y
Output parameter for the Y parameter.
@item Z
Output parameter for the Z parameter.
@end table


@item libclut_model_ciexyz_to_cieluv(X, Y, Z, Xn, Yn, Zn, *L, *u, *v)
Convert from CIE XYZ to CIE 1976 (L*, u*, v*).

The macro variant requires linking with @option{-lm}.

Parameters:
@table @code
@item L
The X component.
@item a
The Y component.
@item b
The Z component.
@item Xn
The X component of the specified white object (white point).
@item Yn
The Y component of the specified white object (white point).
@item Zn
The Z component of the specified white object (white point).
@item X
Output parameter for the L* parameter.
@item Y
Output parameter for the u* parameter.
@item Z
Output parameter for the v* parameter.
@end table


@item libclut_model_cieluv_to_ciexyz(L, u, v, Xn, Yn, Zn, *X, *Y, *Z)
Convert from CIE 1976 (L*, u*, v*) to CIE XYZ.

Parameters:
@table @code
@item L
The L* component.
@item a
The u* component.
@item b
The v* component.
@item Xn
The X component of the specified white object (white point).
@item Yn
The Y component of the specified white object (white point).
@item Zn
The Z component of the specified white object (white point).
@item X
Output parameter for the X parameter.
@item Y
Output parameter for the Y parameter.
@item Z
Output parameter for the Z parameter.
@end table


@item libclut_model_cielch_to_cieluv(C, h, *u, *v)
Convert from CIE LCh@sub{uv} to CIE 1976 (L*, u*, v*).

The L* component remains unchanged.

The macro variant requires linking with @option{-lm}.

Parameters:
@table @code
@item C
The C*@sub{uv} component.
@item h
The h@sub{uv} component.
@item u
Output parameter for the u* parameter.
@item v
Output parameter for the v* parameter.
@end table


@item libclut_model_cieluv_to_cielch(u, v, *C, *h)
Convert from CIE 1976 (L*, u*, v*) to CIE LCh@sub{uv}.

The L* component remains unchanged.

The macro variant requires linking with @option{-lm}.

Parameters:
@table @code
@item a
The u* component.
@item b
The v* component.
@item C
Output parameter for the C*@sub{uv} parameter.
@item h
Output parameter for the h@sub{uv} parameter.
@end table


@item libclut_model_srgb_to_yiq(r, g, b, *Y, *I, *Q)
Convert from [0, 1] sRGB to YIQ.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_standard_to_linear1} has been
undefined.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item Y
Output parameter for the Y parameter.
@item I
Output parameter for the I parameter.
@item Q
Output parameter for the Q parameter.
@end table


@item libclut_model_yiq_to_srgb(Y, I, Q, *r, *g, *b)
Convert from YIQ to [0, 1] sRGB.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_linear_to_standard1} has been
undefined.

Parameters:
@table @code
@item Y
The Y component.
@item I
The I component.
@item Q
The Q component.
@item r
Output parameter for the red parameter.
@item g
Output parameter for the green parameter.
@item b
Output parameter for the blue parameter.
@end table


@item libclut_model_srgb_to_ydbdr(r, g, b, *Y, *Db, *Dr)
Convert from [0, 1] sRGB to YD@sub{b}D@sub{r}.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_standard_to_linear1} has been
undefined.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item Y
Output parameter for the Y parameter.
@item Db
Output parameter for the D@sub{b} parameter.
@item Dr
Output parameter for the D@sub{r} parameter.
@end table


@item libclut_model_ydbdr_to_srgb(Y, Db, Dr, *r, *g, *b)
Convert from YD@sub{b}D@sub{r} to [0, 1] sRGB.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_linear_to_standard1} has been
undefined.

Parameters:
@table @code
@item Y
The Y component.
@item Db
The D@sub{b} component.
@item Dr
The D@sub{r} component.
@item r
Output parameter for the red parameter.
@item g
Output parameter for the green parameter.
@item b
Output parameter for the blue parameter.
@end table


@item libclut_model_yuv_to_ydbdr(U, V, *Db, *Dr)
Convert from YUV to YD@sub{b}D@sub{r}.

The Y component remains unchanged.

Parameters:
@table @code
@item Y
The U component.
@item V
The V component.
@item Db
Output parameter for the D@sub{b} parameter.
@item Dr
Output parameter for the D@sub{r} parameter.
@end table


@item libclut_model_ydbdr_to_yuv(Db, Dr, *U, *V)
Convert from YD@sub{b}D@sub{r} to YUV.

The Y component remains unchanged.

Parameters:
@table @code
@item Db
The D@sub{b} component.
@item Dr
The D@sub{r} component.
@item U
Output parameter for the U parameter.
@item V
Output parameter for the V parameter.
@end table


@item libclut_model_srgb_to_ypbpr(r, g, b, *Y, *Pb, *Pr)
Convert from [0, 1] sRGB to YP@sub{b}P@sub{r}.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_standard_to_linear1} has been
undefined.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item Y
Output parameter for the Y parameter.
@item Pb
Output parameter for the P@sub{b} parameter.
@item Pr
Output parameter for the P@sub{r} parameter.
@end table


@item libclut_model_ypbpr_to_srgb(Y, Pb, Pr, *r, *g, *b)
Convert from YP@sub{b}P@sub{r} to [0, 1] sRGB.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_linear_to_standard1} has been
undefined.

Parameters:
@table @code
@item Y
The Y component.
@item Pb
The P@sub{b} component.
@item Pr
The P@sub{r} component.
@item r
Output parameter for the red parameter.
@item g
Output parameter for the green parameter.
@item b
Output parameter for the blue parameter.
@end table


@item libclut_model_srgb_to_ycgco(r, g, b, *Y, *Cg, *Co)
Convert from [0, 1] sRGB to YCgCo.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_standard_to_linear1} has been
undefined.

Parameters:
@table @code
@item r
The red component.
@item g
The green component.
@item b
The blue component.
@item Y
Output parameter for the Y parameter.
@item Cg
Output parameter for the Cg parameter.
@item Co
Output parameter for the Co parameter.
@end table


@item libclut_model_ycgco_to_srgb(Y, Cg, Co, *r, *g, *b)
Convert from YCgCo to [0, 1] sRGB.

The macro variant requires linking with @option{-lm},
or if @option{-lclut} if the macro
@code{libclut_model_linear_to_standard1} has been
undefined.

Parameters:
@table @code
@item Y
The Y component.
@item Cg
The Cg component.
@item Co
The Co component.
@item r
Output parameter for the red parameter.
@item g
Output parameter for the green parameter.
@item b
Output parameter for the blue parameter.
@end table


@item libclut_model_cie_1960_ucs_to_ciexyz(u, v, Y, *x, *y, *z)
Convert from CIE 1960 UCS to CIE XYZ.

Parameters:
@table @code
@item u
The u component.
@item v
The v component.
@item Y
The Y component.
@item x
Output parameter for the X parameter.
@item y
Output parameter for the Y parameter.
@item z
Output parameter for the Z parameter.
@end table


@item libclut_model_ciexyz_to_cie_1960_ucs(x, y, z, *u, *v, *Y)
Convert from CIE XYZ to CIE 1960 UCS.

Parameters:
@table @code
@item x
The X component.
@item y
The Y component.
@item z
The Z component.
@item u
Output parameter for the u parameter.
@item v
Output parameter for the v parameter.
@item Y
Output parameter for the Y parameter.
@end table


@item libclut_model_cie_1960_ucs_to_cieuvw(U, V, W, u0, v0, *x, *y, *z)
Convert from CIE 1960 UCS to CIE U*V*W*.

Parameters:
@table @code
@item U
The U* component.
@item V
The V* component.
@item W
The W* component.
@item u0
The u parameter for the white point.
@item v0
The v parameter for the white point.
@item x
Output parameter for the X parameter.
@item y
Output parameter for the Y parameter.
@item z
Output parameter for the Z parameter.
@end table


@item libclut_model_cieuvw_to_cie_1960_ucs(x, y, z, u0, v0, *U, *V, *W)
Convert from CIE U*V*W* to CIE 1960 UCS.

The macro variant requires linking with @option{-lm}.

Parameters:
@table @code
@item x
The X component.
@item y
The Y component.
@item z
The Z component.
@item u0
The u parameter for the white point.
@item v0
The v parameter for the white point.
@item U*
Output parameter for the u parameter.
@item V*
Output parameter for the v parameter.
@item W*
Output parameter for the Y parameter.
@end table
@end table


@node RGB Conversion
@section RGB Conversion

@command{libclut} provides a functions for converting
RGB values between RGB colour spaces. An RGB colour space
is described using @code{struct libclut_rgb_colour_space}
(also known as @code{libclut_rgb_colour_space_t}). It
describes the colour of the red, green, and blue,
stimuli as well as the white point, in CIE xyY. It does
however not describe the colour space's gamma function,
because sRGB uses a irregular gamma function, and
ECI@tie{}RGB@tie{}v2 uses L*. The structure contains
the following @code{double}:s:

@table @code
@item red_x
The CIE xyY x-value of the red stimulus.
@item red_y
The CIE xyY y-value of the red stimulus.
@item red_Y
The CIE xyY Y-value of the red stimulus.
@item green_x
The CIE xyY x-value of the green stimulus.
@item green_y
The CIE xyY y-value of the green stimulus.
@item green_Y
The CIE xyY Y-value of the green stimulus.
@item blue_x
The CIE xyY x-value of the blue stimulus.
@item blue_y
The CIE xyY y-value of the blue stimulus.
@item blue_Y
The CIE xyY Y-value of the blue stimulus.
@item white_x
The CIE xyY x-value of the white point.
@item white_y
The CIE xyY y-value of the white point.
@item white_Y
The CIE xyY Y-value of the white point.
@end table

@code{libclut} provides macros used to initialise a
@code{struct libclut_rgb_colour_space} with values
for a number of RGB colour spaces. These are listed
below, along with the gamma each colour space uses.

@multitable {PAL/SECAM RGB} {@b{Gamma}} {@code{LIBCLUT_RGB_COLOUR_SPACE_WIDE_GAMUT_RGB_INITIALISER}}
@item
@b{Model}
@tab
@b{Gamma}
@tab
@b{Initialiser}
@item
sRGB
@tab
custom
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_SRGB_INITIALISER}
@item
Adobe RGB (1998)
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_ADOBE_RGB_INITIALISER}
@item
Apple RGB
@tab
1.8
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_APPLE_RGB_INITIALISER}
@item
Best RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_BEST_RGB_INITIALISER}
@item
Beta RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_BETA_RGB_INITIALISER}
@item
Bruce RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_BRUCE_RGB_INITIALISER}
@item
CIE RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_CIE_RGB_INITIALISER}
@item
ColorMatch RGB
@tab
1.8
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_COLORMATCH_RGB_INITIALISER}
@item
DCI-P3 D65
@tab
2.6
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_DCI_P3_D65_INITIALISER}
@item
DCI-P3 Theater
@tab
2.6
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_DCI_P3_THEATER_INITIALISER}
@item
Don RGB 4
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_DON_RGB_4_INITIALISER}
@item
ECI RGB v2
@tab
L*
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_ECI_RGB_V2_INITIALISER}
@item
Ekta Space PS5
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_EKTA_SPACE_PS5_INITIALISER}
@item
525 line@footnote{ITU-R Recommendation BT.601 (ITU-R BT.601), 525 line}
@tab
custom
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_ITU_R_BT_601_525_LINE_INITIALISER}
@item
625 line@footnote{ITU-R Recommendation BT.601 (ITU-R BT.601), 625 line}
@tab
custom
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_ITU_R_BT_601_625_LINE_INITIALISER}
@item
ITU-R BT.709@footnote{ITU-R Recommendation BT.709}
@tab
2.4
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_ITU_R_BT_709_INITIALISER}
@item
ITU-R BT.2020@footnote{ITU-R Recommendation BT.2020}
@tab
custom
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_ITU_R_BT_2020_INITIALISER}
@item
ITU-R BT.2100@footnote{ITU-R Recommendation BT.2100}
@tab
custom
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_ITU_R_BT_2100_INITIALISER}
@item
Lightroom RGB
@tab
linear
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_LIGHTROOM_RGB_INITIALISER}
@item
NTSC RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_NTSC_RGB_INITIALISER}
@item
PAL/SECAM RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_PAL_SECAM_RGB_INITIALISER}
@item
ProPhoto RGB
@tab
1.8
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_PROPHOTO_RGB_INITIALISER}
@item
SMPTE-C RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_SMPTE_C_RGB_INITIALISER}
@item
Wide Gamut RGB
@tab
2.2
@tab
@code{LIBCLUT_RGB_COLOUR_SPACE_WIDE_GAMUT_RGB_INITIALISER}
@end multitable

@page
To create a description for the sRGB colour space write:

@example
struct libclut_rgb_colour_space srgb = \
        LIBCLUT_RGB_COLOUR_SPACE_SRGB_INITIALISER;
@end example

@command{libgamma} and @command{libcoopgamma} can be used
to get the x and y values of the user's monitors' red,
green, and blue stimuli. Otherwise, all values specified
by @code{LIBCLUT_RGB_COLOUR_SPACE_SRGB_INITIALISER} can
be used, and the sRGB gamma function can be used. However,
the Y values of the stimuli may be off, however, this does
not affect conversion.

sRGB uses an irregular gamma function. @command{libclut}
assumes that the colour spaces uses this gamma function
when converting between RGB colour spaces. If you want to
convert from a colour space with another gamma function,
you must first convert the gamma function. This can be
done by linearising the values and then use
@code{libclut_model_linear_to_standard1},
@code{libclut_model_linear_to_standard}, or
@code{libclut_standardise}. If you want to convert to a
colour spce with another gamma function, you must after
the conversion also convert the gamma function. This can
be done by using @code{libclut_model_standard_to_linear1},
@code{libclut_model_standard_to_linear}, or
@code{libclut_linearise}, and then converting from linear
to the proper gamma function. Note that even if you are
converting between two colour spaces with the same gamma
function, gamma function conversion must be done (before
and after) unless they use the sRGB gamma function.

Before RGB colour space conversion can be done, you need
to create a conversion matrix. It has the type

@example
typedef double libclut_colour_space_conversion_matrix_t[3][3];
@end example

@noindent
and can be created with
@table @code
@item int libclut_model_get_rgb_conversion_matrix(*from, *to, M, Minv)
Create a conversion matrix from one RGB colour space to another
RGB colour space, and optionally a matrix for an inverse conversion.

Returns 0 on success, and -1 on error. The only possible error is
@code{EINVAL}, which indicates that there is something wrong with
the colour spaces and a conversion matrix cannot be created.

This function is not available as a macro, thus, linking with
@option{-lclut} is required.

Parameters:
@table @code
@item const libclut_rgb_colour_space_t* from
Description of the input colour space. CIE XYZ is
used use if this parameter is @code{NULL}.
@item const libclut_rgb_colour_space_t* to
Description of the output colour space. CIE XYZ is
used use if this parameter is @code{NULL}.
@item libclut_colour_space_conversion_matrix_t M
Matrix to fill with values so it can be used for
converting from the input colour space to the
output colour space.
@item libclut_colour_space_conversion_matrix_t Minv
Matrix to fill with values so it can be used for
converting from the output colour space to the
input colour space. (That is, inverse conversion.)
This parameter may be @code{NULL}.
@end table
@end table

You can also create the matrix manually. If you for example
have a @code{libclut_colour_space_conversion_matrix_t} named
@code{M}, and want to set the cell at row 1 and column 3, to
0.5, you make the assignment @code{M[0][2] = 0.5}.

Once you have your conversion matrix, @command{libclut} has
three macro functions you can used to convert colours between
RGB colour space. Remember that they require the sRGB gamma
function.

@table @code
@item libclut_model_convert_rgb(r, g, b, M, *out_r, *out_g, *out_b)
Convert a single RGB colour into another RGB colour space.
The colour space must have same gamma functions as sRGB.

This macro is also available a function. If the function is
used, linking with @option{-lclut} is required, otherwise,
linking with @option{-lm} is required, or @option{-lclut} if
@code{libclut_model_standard_to_linear1} or
@code{libclut_model_linear_to_standard1} is undefined.

Parameters:
@table @code
@item double r
The red value of the colour to convert.
@item double g
The green value of the colour to convert.
@item double b
The blue value of the colour to convert.
@item libclut_colour_space_conversion_matrix_t M
The conversion matrix.
@item double* out_r
Output parameter for the red value of the colour after conversion.
@item double* out_g
Output parameter for the green value of the colour after conversion.
@item double* out_b
Output parameter for the blue value of the colour after conversion.
@end table


@item libclut_convert_rgb_inplace(clut, max, type, m, trunc)
Convert the curves between two RGB colour spaces.

The red, green, and blue ramps must be of the same size.

None of the parameter may have side-effects.

Requires linking with @option{-lm}, or @option{-lclut} if
@code{libclut_model_standard_to_linear1},
@code{libclut_model_linear_to_standard1}, or
@code{libclut_model_convert_rgb}  is undefined.

Parameters:
@table @code
@item clut
Pointer to the gamma ramps to convert. This must be a pointer to
an instance of a struct that must at least have the array members
@code{red}, @code{green}, and @code{blue}, whose elements shall be
of the type specified by the parameter @code{type}. The @code{struct}
must also have the scalar members @code{red_size}, @code{green_size},
and @code{blue_size}, and shall be of the type @code{size_t}; they
shall specify the number of stops (elements) in the arrays @code{.red},
@code{.green}, and @code{.blue}, respectively, which shall be the
gamma ramp for the red, green, and blue channels respectively. Its
values will be modified to the new values.
@item max
The maximum value on each stop in the ramps.
@item type
The data type used for each stop in the ramps.
@item libclut_colour_space_conversion_matrix_t m
Conversion matrix.
@item int trunc
If this is a non-zero value, resulting colours that are
out of gamut are truncated. (Not necessarily the best
approximation.)
@end table


@item libclut_convert_rgb(clut, max, type, m, trunc, out)
Convert the curves between two RGB colour spaces.

This is a slower version of @code{libclut_convert_rgb_inplace}
that supports clut:s where the red, green, and blue ramps
are not of the same size.

None of the parameter may have side-effects.

Requires linking with @option{-lm}. If
@code{libclut_model_linear_to_standard1},
@code{libclut_model_standard_to_linear1}, or
@code{libclut_model_convert_rgb} has been undefined,
linking with @option{-lclut} is also required.

Parameters:
@table @code
@item clut
Pointer to the gamma ramps to convert. This must be a pointer to
an instance of a struct that must at least have the array members
@code{red}, @code{green}, and @code{blue}, whose elements shall be
of the type specified by the parameter @code{type}. The @code{struct}
must also have the scalar members @code{red_size}, @code{green_size},
and @code{blue_size}, and shall be of the type @code{size_t}; they
shall specify the number of stops (elements) in the arrays @code{.red},
@code{.green}, and @code{.blue}, respectively, which shall be the
gamma ramp for the red, green, and blue channels respectively. Its
values are not modified.
@item max
The maximum value on each stop in the ramps.
@item type
The data type used for each stop in the ramps.
@item libclut_colour_space_conversion_matrix_t m
Conversion matrix.
@item int trunc
If this is a non-zero value, resulting colours that are
out of gamut are truncated. (Not necessarily the best
approximation.)
@item clut
Pointer to the gamma ramps of the output values. Shall be of
the same data type as @code{clut}. And have the same values on
@code{.red_size}, @code{.green_size}, and @code{.blue_size} as
@code{clut}.
@end table
@end table

There is also two functions for converting between a custom RGB
colour space and CIE XYZ, one function in each direction. Note
that the three functions above do not work if one of the colour
spaces is CIE XYZ.

@table @code
@item libclut_model_rgb_to_ciexyz(r, g, b, M, *X, *Y, *Z)
Convert a single RGB colour if a custom RGB colour space
to CIE XYZ.

The RGB colour space must have the same gamma function as sRGB.

This macro is also available a function. If the function is
used, linking with @option{-lclut} is required, otherwise,
linking with @option{-lm} is required, or @option{-lclut} if
@code{libclut_model_standard_to_linear1} is undefined.

Parameters:
@table @code
@item double r
The red component.
@item double g
The green component.
@item double b
The blue component.
@item libclut_colour_space_conversion_matrix_t M
The conversion matrix.
@item double* X
Output parameter for the X component.
@item double* Y
Output parameter for the Y component.
@item double* Z
Output parameter for the Z component.
@end table


@item libclut_model_rgb_to_ciexyz(X, Y, Z, M, *r, *g, *b)
Convert a single colour from CIE XYZ to a custom RGB colour space.

The RGB colour space must have the same gamma function as sRGB.

This macro is also available a function. If the function is
used, linking with @option{-lclut} is required, otherwise,
linking with @option{-lm} is required, or @option{-lclut} if
@code{libclut_model_linear_to_standard1} is undefined.

Parameters:
@table @code
@item double X
The X component.
@item double Y
The Y component.
@item double Z
The Z component.
@item libclut_colour_space_conversion_matrix_t M
The conversion matrix.
@item double* r
Output parameter for the red component.
@item double* g
Output parameter for the green component.
@item double* b
Output parameter for the blue component.
@end table
@end table