root/trunk/doc/color.html

Revision 5, 41.5 kB (checked in by nail, 3 years ago)

Initial import

Line 
1 <html><head>
2 <meta http-equiv="content-type" content="text/html; charset=utf-8">
3 <meta content="text/javascript" http-equiv="content-script-type">
4 <title>helix.color</title>
5 <link rel="stylesheet" type="text/css" href="candydoc/style.css">
6 <!--[if lt IE 7]><link rel="stylesheet" type="text/css" href="candydoc/ie56hack.css"><![endif]-->
7 <script language="JavaScript" src="candydoc/util.js" type="text/javascript"></script>
8 <script language="JavaScript" src="candydoc/tree.js" type="text/javascript"></script>
9 <script language="JavaScript" src="candydoc/explorer.js" type="text/javascript"></script>
10 </head><body>
11 <div id="tabarea"></div><div id="explorerclient"></div>
12 <div id="content"><script>explorer.initialize("helix.color");</script>
13     <table class="content">
14         <tr><td id="docbody"><h1>helix.color</h1><!-- Generated by Ddoc from c:\sdk\helix\trunk\helix\color.d -->
15 Module with classes and functions for working with color values.
16 <br><br>
17 There are structs for representation Red Green Blue color (Color3),
18 RGB+Alpha color (Color4) and Hue Saturation Luminance triple (HSL).
19 <br><br>
20
21 All components of those structs are float values, not integers.
22 Rationale is that under different circumstances it is necessary to
23 work with different standards of integer representation. Frequently
24 one byte-wise integer layout needed for one API and another for second.
25 One can require XRGB order, another BGRA. So it's better to operate with
26 floats and to convert them to integer just when it is necessary.
27 <br><br>
28
29 Normal range for float components' values is [0; 1]. Normal range for integer
30 values is [0; 255] for Color3 and Color4, and [0; 240] for HSL. Each struct
31 has several methods to convert native float representation to integer and
32 back.
33
34 <br><br>
35 <b>Authors:</b><br>
36 Victor Nakoryakov, nail-mail[at]mail.ru
37 <br><br>
38
39
40 <script>explorer.outline.incSymbolLevel();</script>
41 <dl>
42 <script>explorer.outline.writeEnabled = true;</script>
43 <dt><span class="decl">enum
44 <span class="currsymbol">ByteOrder</span>
45 <script>explorer.outline.addDecl('ByteOrder');</script>
46
47 ;
48 </span></dt>
49 <script>explorer.outline.writeEnabled = false;</script>
50
51
52 <dd>Defines bytes orders for float to uint conversions.
53 <br><br>
54
55
56 <script>explorer.outline.incSymbolLevel();</script>
57 <dl>
58 <script>explorer.outline.writeEnabled = true;</script>
59 <dt><span class="decl">
60 <span class="currsymbol">XRGB</span>
61 <script>explorer.outline.addDecl('XRGB');</script>
62
63 <br>
64 <span class="currsymbol">XBGR</span>
65 <script>explorer.outline.addDecl('XBGR');</script>
66
67 <br>
68 <span class="currsymbol">RGBX</span>
69 <script>explorer.outline.addDecl('RGBX');</script>
70
71 <br>
72 <span class="currsymbol">BGRX</span>
73 <script>explorer.outline.addDecl('BGRX');</script>
74
75 <br>
76 <span class="currsymbol">ARGB</span>
77 <script>explorer.outline.addDecl('ARGB');</script>
78
79 <br>
80 <span class="currsymbol">ABGR</span>
81 <script>explorer.outline.addDecl('ABGR');</script>
82
83 <br>
84 <span class="currsymbol">RGBA</span>
85 <script>explorer.outline.addDecl('RGBA');</script>
86
87 <br>
88 <span class="currsymbol">BGRA</span>
89 <script>explorer.outline.addDecl('BGRA');</script>
90
91 </span></dt>
92 <script>explorer.outline.writeEnabled = false;</script>
93
94
95 <dd><br><br>
96 </dd>
97 </dl>
98 <script>explorer.outline.decSymbolLevel();</script>
99
100
101 </dd>
102
103 <script>explorer.outline.writeEnabled = true;</script>
104 <dt><span class="decl">template
105 <span class="currsymbol">Color</span>
106 <script>explorer.outline.addDecl('Color');</script>
107
108 (float_t)</span></dt>
109 <script>explorer.outline.writeEnabled = false;</script>
110
111
112 <dd>Wrapper template to provide possibility to use different float types
113 in implemented structs and routines.
114 <br><br>
115
116
117 <script>explorer.outline.incSymbolLevel();</script>
118 <dl>
119 <script>explorer.outline.writeEnabled = true;</script>
120 <dt><span class="decl">struct
121 <span class="currsymbol">HSL</span>
122 <script>explorer.outline.addDecl('HSL');</script>
123
124 ;
125 </span></dt>
126 <script>explorer.outline.writeEnabled = false;</script>
127
128
129 <dd>Hue, Saturation, Luminance triple.
130    
131 <br><br>
132
133
134 <script>explorer.outline.incSymbolLevel();</script>
135 <dl>
136 <script>explorer.outline.writeEnabled = true;</script>
137 <dt><span class="decl">float_t
138 <span class="currsymbol">h</span>
139 <script>explorer.outline.addDecl('h');</script>
140
141 ;
142 </span></dt>
143 <script>explorer.outline.writeEnabled = false;</script>
144
145
146 <dd>Hue.
147 <br><br>
148
149 </dd>
150
151 <script>explorer.outline.writeEnabled = true;</script>
152 <dt><span class="decl">float_t
153 <span class="currsymbol">s</span>
154 <script>explorer.outline.addDecl('s');</script>
155
156 ;
157 </span></dt>
158 <script>explorer.outline.writeEnabled = false;</script>
159
160
161 <dd>Saturation.
162 <br><br>
163
164 </dd>
165
166 <script>explorer.outline.writeEnabled = true;</script>
167 <dt><span class="decl">float_t
168 <span class="currsymbol">l</span>
169 <script>explorer.outline.addDecl('l');</script>
170
171 ;
172 </span></dt>
173 <script>explorer.outline.writeEnabled = false;</script>
174
175
176 <dd>Luminance.
177 <br><br>
178
179 </dd>
180
181 <script>explorer.outline.writeEnabled = true;</script>
182 <dt><span class="decl">HSL
183 <span class="currsymbol">opCall</span>
184 <script>explorer.outline.addDecl('opCall');</script>
185
186 (float_t <span class="funcparam">h</span>, float_t <span class="funcparam">s</span>, float_t <span class="funcparam">l</span>);
187 </span></dt>
188 <script>explorer.outline.writeEnabled = false;</script>
189
190
191 <dd>Method to construct struct in C-like syntax.
192 <br><br>
193 <b>Examples:</b><br>
194 <pre class="d_code">        HSL hsl = HSL(0.1, 0.2, 0.3);
195 </pre>
196        
197 <br><br>
198
199 </dd>
200
201 <script>explorer.outline.writeEnabled = true;</script>
202 <dt><span class="decl">void
203 <span class="currsymbol">set</span>
204 <script>explorer.outline.addDecl('set');</script>
205
206 (float_t <span class="funcparam">h</span>, float_t <span class="funcparam">s</span>, float_t <span class="funcparam">l</span>);
207 </span></dt>
208 <script>explorer.outline.writeEnabled = false;</script>
209
210
211 <dd>Sets components to values of passed arguments.
212 <br><br>
213
214 </dd>
215
216 <script>explorer.outline.writeEnabled = true;</script>
217 <dt><span class="decl">uint
218 <span class="currsymbol">hi</span>
219 <script>explorer.outline.addDecl('hi');</script>
220
221 ();
222 <br>uint
223 <span class="currsymbol">si</span>
224 <script>explorer.outline.addDecl('si');</script>
225
226 ();
227 <br>uint
228 <span class="currsymbol">li</span>
229 <script>explorer.outline.addDecl('li');</script>
230
231 ();
232 </span></dt>
233 <script>explorer.outline.writeEnabled = false;</script>
234
235
236 <dd><b>Returns:</b><br>
237 Integer value of corresponding component in range [0; 240].
238 <br><br>
239
240 </dd>
241
242 <script>explorer.outline.writeEnabled = true;</script>
243 <dt><span class="decl">void
244 <span class="currsymbol">hi</span>
245 <script>explorer.outline.addDecl('hi');</script>
246
247 (uint <span class="funcparam">h</span>);
248 <br>void
249 <span class="currsymbol">si</span>
250 <script>explorer.outline.addDecl('si');</script>
251
252 (uint <span class="funcparam">s</span>);
253 <br>void
254 <span class="currsymbol">li</span>
255 <script>explorer.outline.addDecl('li');</script>
256
257 (uint <span class="funcparam">l</span>);
258 </span></dt>
259 <script>explorer.outline.writeEnabled = false;</script>
260
261
262 <dd>Set components to values of passed arguments. It is assumed that values of
263         arguments are in range [0; 240].
264        
265 <br><br>
266
267 </dd>
268
269 <script>explorer.outline.writeEnabled = true;</script>
270 <dt><span class="decl">bool
271 <span class="currsymbol">opEquals</span>
272 <script>explorer.outline.addDecl('opEquals');</script>
273
274 (HSL <span class="funcparam">hsl</span>);
275 </span></dt>
276 <script>explorer.outline.writeEnabled = false;</script>
277
278
279 <dd>Component-wise equality operator.
280 <br><br>
281
282 </dd>
283
284 <script>explorer.outline.writeEnabled = true;</script>
285 <dt><span class="decl">Color3
286 <span class="currsymbol">toColor3</span>
287 <script>explorer.outline.addDecl('toColor3');</script>
288
289 ();
290 </span></dt>
291 <script>explorer.outline.writeEnabled = false;</script>
292
293
294 <dd><b>Returns:</b><br>
295 Color3 representing the same color as this triple.
296 <br><br>
297
298 </dd>
299 </dl>
300 <script>explorer.outline.decSymbolLevel();</script>
301
302
303 </dd>
304
305 <script>explorer.outline.writeEnabled = true;</script>
306 <dt><span class="decl">bool
307 <span class="currsymbol">equal</span>
308 <script>explorer.outline.addDecl('equal');</script>
309
310 (HSL <span class="funcparam">a</span>, HSL <span class="funcparam">b</span>, int <span class="funcparam">relprec</span> = defrelprec, int <span class="funcparam">absprec</span> = defabsprec);
311 </span></dt>
312 <script>explorer.outline.writeEnabled = false;</script>
313
314
315 <dd>Approximate equality function.
316 <br><br>
317 <b>Params:</b><br>
318 <table></table><br>
319
320 </dd>
321
322 <script>explorer.outline.writeEnabled = true;</script>
323 <dt><span class="decl">struct
324 <span class="currsymbol">Color3</span>
325 <script>explorer.outline.addDecl('Color3');</script>
326
327 ;
328 </span></dt>
329 <script>explorer.outline.writeEnabled = false;</script>
330
331
332 <dd>Red, Green, Blue triple.
333    
334 <br><br>
335
336
337 <script>explorer.outline.incSymbolLevel();</script>
338 <dl>
339 <script>explorer.outline.writeEnabled = true;</script>
340 <dt><span class="decl">float_t
341 <span class="currsymbol">r</span>
342 <script>explorer.outline.addDecl('r');</script>
343
344 ;
345 </span></dt>
346 <script>explorer.outline.writeEnabled = false;</script>
347
348
349 <dd>Red.
350 <br><br>
351
352 </dd>
353
354 <script>explorer.outline.writeEnabled = true;</script>
355 <dt><span class="decl">float_t
356 <span class="currsymbol">g</span>
357 <script>explorer.outline.addDecl('g');</script>
358
359 ;
360 </span></dt>
361 <script>explorer.outline.writeEnabled = false;</script>
362
363
364 <dd>Green.
365 <br><br>
366
367 </dd>
368
369 <script>explorer.outline.writeEnabled = true;</script>
370 <dt><span class="decl">float_t
371 <span class="currsymbol">b</span>
372 <script>explorer.outline.addDecl('b');</script>
373
374 ;
375 </span></dt>
376 <script>explorer.outline.writeEnabled = false;</script>
377
378
379 <dd>Blue.
380 <br><br>
381
382 </dd>
383
384 <script>explorer.outline.writeEnabled = true;</script>
385 <dt><span class="decl">Color3
386 <span class="currsymbol">nan</span>
387 <script>explorer.outline.addDecl('nan');</script>
388
389 ;
390 </span></dt>
391 <script>explorer.outline.writeEnabled = false;</script>
392
393
394 <dd>Color3 with all components seted to NaN.
395 <br><br>
396
397 </dd>
398
399 <script>explorer.outline.writeEnabled = true;</script>
400 <dt><span class="decl">Color3
401 <span class="currsymbol">opCall</span>
402 <script>explorer.outline.addDecl('opCall');</script>
403
404 (float_t <span class="funcparam">r</span>, float_t <span class="funcparam">g</span>, float_t <span class="funcparam">b</span>);
405 </span></dt>
406 <script>explorer.outline.writeEnabled = false;</script>
407
408
409 <dd>Method to construct color in C-like syntax.
410 <br><br>
411 <b>Examples:</b><br>
412 <pre class="d_code">        Color3 c = Color3(0.1, 0.2, 0.3);
413 </pre>
414        
415 <br><br>
416
417 </dd>
418
419 <script>explorer.outline.writeEnabled = true;</script>
420 <dt><span class="decl">Color3
421 <span class="currsymbol">opCall</span>
422 <script>explorer.outline.addDecl('opCall');</script>
423
424 (uint <span class="funcparam">src</span>, ByteOrder <span class="funcparam">order</span>);
425 </span></dt>
426 <script>explorer.outline.writeEnabled = false;</script>
427
428
429 <dd>Method to construct color in C-like syntax from value specified
430         in uint parameter.
431 <br><br>
432 <b>Params:</b><br>
433 <table><tr>
434 <td nowrap valign="top" style="padding-right: 8px">uint <span class="funcparam">src</span></td>
435
436                
437 <td>uint to extract value from.</td></tr>
438 <tr>
439 <td nowrap valign="top" style="padding-right: 8px">ByteOrder <span class="funcparam">order</span></td>
440
441                
442 <td>specifies byte-wise order in <span class="funcparam">src</span>.</td></tr>
443 </table><br>
444 <b>Examples:</b><br>
445 <pre class="d_code">        Color3 c = Color3(0x00FFEEDD, ByteOrder.XRGB);
446 </pre>
447        
448 <br><br>
449
450 </dd>
451
452 <script>explorer.outline.writeEnabled = true;</script>
453 <dt><span class="decl">void
454 <span class="currsymbol">set</span>
455 <script>explorer.outline.addDecl('set');</script>
456
457 (float_t <span class="funcparam">r</span>, float_t <span class="funcparam">g</span>, float_t <span class="funcparam">b</span>);
458 </span></dt>
459 <script>explorer.outline.writeEnabled = false;</script>
460
461
462 <dd>Sets components to values of passed arguments.
463 <br><br>
464
465 </dd>
466
467 <script>explorer.outline.writeEnabled = true;</script>
468 <dt><span class="decl">void
469 <span class="currsymbol">set</span>
470 <script>explorer.outline.addDecl('set');</script>
471
472 (uint <span class="funcparam">src</span>, ByteOrder <span class="funcparam">order</span> = ByteOrder.XRGB);
473 </span></dt>
474 <script>explorer.outline.writeEnabled = false;</script>
475
476
477 <dd>Sets components according to color packed in <span class="funcparam">src</span> uint argument.
478 <br><br>
479 <b>Params:</b><br>
480 <table><tr>
481 <td nowrap valign="top" style="padding-right: 8px">uint <span class="funcparam">src</span></td>
482
483                
484 <td>uint to extract value from.</td></tr>
485 <tr>
486 <td nowrap valign="top" style="padding-right: 8px">ByteOrder <span class="funcparam">order</span></td>
487
488                
489 <td>specifies byte-wise component layout in <span class="funcparam">src</span>.</td></tr>
490 </table><br>
491
492 </dd>
493
494 <script>explorer.outline.writeEnabled = true;</script>
495 <dt><span class="decl">bool
496 <span class="currsymbol">isnormal</span>
497 <script>explorer.outline.addDecl('isnormal');</script>
498
499 ();
500 </span></dt>
501 <script>explorer.outline.writeEnabled = false;</script>
502
503
504 <dd><b>Returns:</b><br>
505 Whether all components are normalized numbers.
506 <br><br>
507
508 </dd>
509
510 <script>explorer.outline.writeEnabled = true;</script>
511 <dt><span class="decl">int
512 <span class="currsymbol">ri</span>
513 <script>explorer.outline.addDecl('ri');</script>
514
515 ();
516 <br>int
517 <span class="currsymbol">gi</span>
518 <script>explorer.outline.addDecl('gi');</script>
519
520 ();
521 <br>int
522 <span class="currsymbol">bi</span>
523 <script>explorer.outline.addDecl('bi');</script>
524
525 ();
526 </span></dt>
527 <script>explorer.outline.writeEnabled = false;</script>
528
529
530 <dd><b>Returns:</b><br>
531 Integer value of corresponding component.
532 <br><br>
533
534         Float value 0 is mapped to integer 0. Float value 1 is mapped to
535         integer 255.
536        
537 <br><br>
538
539 </dd>
540
541 <script>explorer.outline.writeEnabled = true;</script>
542 <dt><span class="decl">void
543 <span class="currsymbol">ri</span>
544 <script>explorer.outline.addDecl('ri');</script>
545
546 (int <span class="funcparam">r</span>);
547 <br>void
548 <span class="currsymbol">gi</span>
549 <script>explorer.outline.addDecl('gi');</script>
550
551 (int <span class="funcparam">g</span>);
552 <br>void
553 <span class="currsymbol">bi</span>
554 <script>explorer.outline.addDecl('bi');</script>
555
556 (int <span class="funcparam">b</span>);
557 </span></dt>
558 <script>explorer.outline.writeEnabled = false;</script>
559
560
561 <dd>Sets corresponding component value to mapped value of passed argument.
562 <br><br>
563 Integer value 0 is mapped to float 0. Integer value 255 is mapped to
564         float 1.
565        
566 <br><br>
567
568 </dd>
569
570 <script>explorer.outline.writeEnabled = true;</script>
571 <dt><span class="decl">uint
572 <span class="currsymbol">toUint</span>
573 <script>explorer.outline.addDecl('toUint');</script>
574
575 (ByteOrder <span class="funcparam">order</span>);
576 </span></dt>
577 <script>explorer.outline.writeEnabled = false;</script>
578
579
580 <dd><b>Returns:</b><br>
581 This color packed to uint.
582 <br><br>
583 <b>Params:</b><br>
584 <table><tr>
585 <td nowrap valign="top" style="padding-right: 8px">ByteOrder <span class="funcparam">order</span></td>
586
587                
588 <td>specifies byte-wise component layout in src.</td></tr>
589 </table><br>
590 <b>Throws:</b><br>
591 AssertError if any component is out of range [0; 1] and module was
592             compiled with asserts.
593        
594 <br><br>
595
596 </dd>
597
598 <script>explorer.outline.writeEnabled = true;</script>
599 <dt><span class="decl">HSL
600 <span class="currsymbol">toHSL</span>
601 <script>explorer.outline.addDecl('toHSL');</script>
602
603 ();
604 </span></dt>
605 <script>explorer.outline.writeEnabled = false;</script>
606
607
608 <dd><b>Returns:</b><br>
609 HSL triple representing same color as this.
610        
611 <br><br>
612
613 </dd>
614
615 <script>explorer.outline.writeEnabled = true;</script>
616 <dt><span class="decl">float_t*
617 <span class="currsymbol">ptr</span>
618 <script>explorer.outline.addDecl('ptr');</script>
619
620 ();
621 </span></dt>
622 <script>explorer.outline.writeEnabled = false;</script>
623
624
625 <dd><b>Returns:</b><br>
626 float_t pointer to r component of this color. It's like a ptr method for arrays.
627 <br><br>
628
629 </dd>
630
631 <script>explorer.outline.writeEnabled = true;</script>
632 <dt><span class="decl">bool
633 <span class="currsymbol">opEquals</span>
634 <script>explorer.outline.addDecl('opEquals');</script>
635
636 (Color3 <span class="funcparam">v</span>);
637 <br>Color3
638 <span class="currsymbol">opNeg</span>
639 <script>explorer.outline.addDecl('opNeg');</script>
640
641 ();
642 <br>Color3
643 <span class="currsymbol">opAdd</span>
644 <script>explorer.outline.addDecl('opAdd');</script>
645
646 (Color3 <span class="funcparam">v</span>);
647 <br>void
648 <span class="currsymbol">opAddAssign</span>
649 <script>explorer.outline.addDecl('opAddAssign');</script>
650
651 (Color3 <span class="funcparam">v</span>);
652 <br>Color3
653 <span class="currsymbol">opSub</span>
654 <script>explorer.outline.addDecl('opSub');</script>
655
656 (Color3 <span class="funcparam">v</span>);
657 <br>void
658 <span class="currsymbol">opSubAssign</span>
659 <script>explorer.outline.addDecl('opSubAssign');</script>
660
661 (Color3 <span class="funcparam">v</span>);
662 <br>Color3
663 <span class="currsymbol">opMul</span>
664 <script>explorer.outline.addDecl('opMul');</script>
665
666 (real <span class="funcparam">k</span>);
667 <br>void
668 <span class="currsymbol">opMulAssign</span>
669 <script>explorer.outline.addDecl('opMulAssign');</script>
670
671 (real <span class="funcparam">k</span>);
672 <br>Color3
673 <span class="currsymbol">opMulr</span>
674 <script>explorer.outline.addDecl('opMulr');</script>
675
676 (real <span class="funcparam">k</span>);
677 <br>Color3
678 <span class="currsymbol">opDiv</span>
679 <script>explorer.outline.addDecl('opDiv');</script>
680
681 (real <span class="funcparam">k</span>);
682 <br>void
683 <span class="currsymbol">opDivAssign</span>
684 <script>explorer.outline.addDecl('opDivAssign');</script>
685
686 (real <span class="funcparam">k</span>);
687 </span></dt>
688 <script>explorer.outline.writeEnabled = false;</script>
689
690
691 <dd>Standard operators that have meaning exactly the same as for Vector3, i.e. do
692         component-wise operations.
693 <br><br>
694 Note that division operators do no cheks of value of k, so in case of division
695         by 0 result vector will have infinity components. You can check this with isnormal()
696         method.
697        
698 <br><br>
699
700 </dd>
701
702 <script>explorer.outline.writeEnabled = true;</script>
703 <dt><span class="decl">void
704 <span class="currsymbol">clampBelow</span>
705 <script>explorer.outline.addDecl('clampBelow');</script>
706
707 (float_t <span class="funcparam">inf</span> = 0);
708 </span></dt>
709 <script>explorer.outline.writeEnabled = false;</script>
710
711
712 <dd>Sets all components less than <span class="funcparam">inf</span> to <span class="funcparam">inf</span>.
713 <br><br>
714
715 </dd>
716
717 <script>explorer.outline.writeEnabled = true;</script>
718 <dt><span class="decl">Color3
719 <span class="currsymbol">clampedBelow</span>
720 <script>explorer.outline.addDecl('clampedBelow');</script>
721
722 (float_t <span class="funcparam">inf</span> = 0);
723 </span></dt>
724 <script>explorer.outline.writeEnabled = false;</script>