summaryrefslogtreecommitdiffstats
path: root/doc/libdimension.texi
blob: f5dfadc35b218fcf1d575a120e116bf56f5adeb8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
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
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
\input texinfo       @c                    -*- Texinfo -*-
@c %**start of header
@setfilename libdimension.info
@settitle The Dimension 3-D Rendering Library
@c %**end of header

@c Combine variable and function indicies
@syncodeindex vr fn

@c Wrap code examples at 72 chars, please

@copying
Copyright @copyright{} 2010 Tavian Barnes
@end copying

@titlepage
@title The Dimension Library
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top The Dimension Library

@insertcopying
@end ifnottex

@menu
* Introduction:: An introduction to the Dimension Library
* Error Handling:: How libdimension handles warnings and errors
* Arrays:: A generic interface for arrays of arbitrary objects
* Asynchronicity:: An interface for controlling background tasks
* Geometry:: Geometric types like vectors, transformation matricies, and lines
* Color:: Correct color handling
* Canvases:: Where the results of rendering are stored
* Objects:: Physical objects in a scene
* Cameras:: How a 3-D image is seen in 2-D
* Scenes:: Scene objects which hold everything needed to render an image
* Type Index::
* Function and Constant Index::
* Concept Index::
@end menu


@node Introduction
@chapter Introduction

@cindex introduction
@cindex overview
The Dimension Library is a C library for rendering photo-realistic 3-D scenes.
It is the workhorse for the ``dimension'' program.
The Dimension Library is currently in the very early stages of development, but does support rendering scenes with transparency and reflection.

The C library is probably not the interface you want to use; the ``dimension'' program will render scenes specified in POV-Ray's Scene Description Language.
This documentation gives a bottom-up overview of the Dimension Library, to allow readers to have a full and complete understanding of the library, rather than a simple top-down overview.

@menu
* Common Definitions:: Definitions used across the Dimension Library
@end menu


@node Common Definitions
@section Common Definitions

@example
@tindex dmnsn_free_fn
typedef void dmnsn_free_fn(void *ptr);
@end example

@code{dmnsn_free_fn} is a type whose signature matches that of @code{free()}, and which is used as a destructor callback type across the Dimension Library.

@node Error Handling
@chapter Error Handling

@example
@tindex dmnsn_severity
typedef enum @{
  @vindex DMNSN_SEVERITY_LOW
  DMNSN_SEVERITY_LOW,    /* Only die on low resilience */
  @vindex DMNSN_SEVERITY_MEDIUM
  DMNSN_SEVERITY_MEDIUM, /* Die on low or medium resilience */
  @vindex DMNSN_SEVERITY_HIGH
  DMNSN_SEVERITY_HIGH    /* Always die */
@} dmnsn_severity;

@findex dmnsn_error()
#define dmnsn_error(severity, str) /* ... */

@findex dmnsn_get_resilience()
dmnsn_severity dmnsn_get_resilience();
@findex dmnsn_set_resilience()
void dmnsn_set_resilience(dmnsn_severity resilience);
@end example

@cindex errors
@cindex warnings
When it makes sense, libdimension reports errors by returning error codes from its functions.
However, when errors are not severe, when said function should not fail, or when the error is very serious, libdimension reports errors using the macro @code{dmnsn_error()}.
@code{dmnsn_error()} takes two parameters: the severity of the error, and a string description of the error.
The macro will conveniently report the description, as well as the function name and code line where the error occured, to standard error.
The severity can be either @code{DMNSN_SEVERITY_LOW}, @code{DMNSN_SEVERITY_MEDIUM}, or @code{DMNSN_SEVERITY_HIGH}.

@cindex resilience
The Dimension Library has also has a user-settable resilience.
The resilience controls the minimum severity at which the library considers an error to be fatal, and calls @code{exit(EXIT_FAILURE)}.
As such, errors of severity @code{DMNSN_SEVERITY_HIGH} are always fatal.
libdimension's resilience defaults to @code{DMNSN_SEVERITY_MEDIUM}, but can be inspected or changed thread-safely by @code{dmnsn_get_resilience()} or @code{dmnsn_set_resilience()}, respectively.
Warnings (non-fatal errors) are formatted like this:

@example
Dimension WARNING: <function>, <file>:<line>: <description>
@end example

@noindent while errors are formatted like this:

@example
Dimension ERROR: <function>, <file>:<line>: <description>
@end example


@node Arrays
@chapter Arrays

@example
@tindex dmnsn_array *
typedef struct @{
  /* ... */
@} dmnsn_array;

/* Array allocation */
@findex dmnsn_new_array()
dmnsn_array *dmnsn_new_array(size_t obj_size);
@findex dmnsn_delete_array()
void dmnsn_delete_array(dmnsn_array *array);

@findex dmnsn_array_push()
void dmnsn_array_push(dmnsn_array *array, const void *obj);
@findex dmnsn_array_pop()
void dmnsn_array_pop(dmnsn_array *array, void *obj);
@findex dmnsn_array_get()
void dmnsn_array_get(const dmnsn_array *array, size_t i, void *obj);
@findex dmnsn_array_set()
void dmnsn_array_set(dmnsn_array *array, size_t i, const void *obj);
@findex dmnsn_array_at()
void *dmnsn_array_at(dmnsn_array *array, size_t i);

@findex dmnsn_array_insert()
void dmnsn_array_insert(dmnsn_array *array, size_t i, const void *obj)
@findex dmnsn_array_remove()
void dmnsn_array_remove(dmnsn_array *array, size_t i)

@findex dmnsn_array_size()
size_t dmnsn_array_size(const dmnsn_array *array);
@findex dmnsn_array_resize()
void   dmnsn_array_resize(dmnsn_array *array, size_t length);
@end example

@cindex array
The Dimension Library often has cause to work with adjustable-size arrays.
It provides an interface for dynamically-allocated arrays of arbitrary objects.
Arrays are allocated with the @code{dmnsn_new_array()} function, and freed with the @code{dmnsn_delete_array()} function, a pattern common in libdimension.
@code{dmnsn_new_array()} takes the size of the new array's elements as its parameter.
Unlike other allocation functions throughout libdimension, @code{dmnsn_new_array()} cannot fail if it returns (other allocators may return NULL).
In fact, all array operations are guaranteed to either succeed or report a fatal error, which may happen if memory allocation fails.

Arrays support the push, pop, get, set, insert, and remove operations for arrays, taking a pointer to an object to read or write as their last parameter, the array index (when applicable) as the second-last parameter, and the @code{dmnsn_array *} as the first parameter.
The get, remove, and pop operations are bounds-checked; other operations dynamically resize the array as needed.
The array's length may be queried with @code{dmnsn_array_size()}, or set with @code{dmnsn_array_resize()}, and a pointer to the @code{i}'th object may be obtained with @code{dmnsn_array_at()}.


@node Asynchronicity
@chapter Asynchronicity

@example
@tindex dmnsn_progress *
typedef struct @{
  /* ... */
@} dmnsn_progress;

/* Progress allocation */
@findex dmnsn_new_progress()
dmnsn_progress *dmnsn_new_progress();
@findex dmnsn_delete_progress()
void dmnsn_delete_progress(dmnsn_progress *progress);

/* Ensures completion of the worker thread */
@findex dmnsn_finish_progress()
int dmnsn_finish_progress(dmnsn_progress *progress);

/* Routines for user */
@findex dmnsn_get_progress()
double dmnsn_get_progress(const dmnsn_progress *progress);
@findex dmnsn_wait_progress()
void dmnsn_wait_progress(const dmnsn_progress *progress, double prog);

/* Routines for worker thread */
@findex dmnsn_new_progress_element()
void dmnsn_new_progress_element(dmnsn_progress *progress,
                                unsigned int total);
@findex dmnsn_increment_progress()
void dmnsn_increment_progress(dmnsn_progress *progress);
@findex dmnsn_done_progress()
void dmnsn_done_progress(dmnsn_progress *progress);
@end example

@cindex asynchronous task
@cindex background task
@cindex progress indicator
As the Dimension Library is a raytracing engine, some routines are likely to take a long time.
These routines may be run in a background thread, and controlled with a common interface.
Routines supporting this interface end in @code{_async}, such as @code{dmnsn_raytrace_scene_async()}, and return a @code{dmnsn_progress *} object, so named because it allows an application to be query the progress of the background task.
By necessity, all @code{dmnsn_progress *} operations are atomic and thread-safe.

Progress objects are allocated and deallocated in the standard libdimension way, but also support a unique @code{dmnsn_finish_progress()} function.
This function waits for the background thread to complete, and then destroys the @code{dmnsn_progress *} object.
Never use the result of a background task before calling @code{dmnsn_finish_progress()}, even if the progress seems to be at 100%!  @code{dmnsn_delete_progress()} should only be called from within failed @code{*_async()} functions, to deallocate a progress object before it is associated with a running thread.

Users of these asynchronous tasks will mainly be interested in the functions @code{dmnsn_get_progress()} and @code{dmnsn_wait_progress()}.
@code{dmnsn_get_progress()} returns the progress of the background task, a value between 0.0 and 1.0.
@code{dmnsn_wait_progress()} simply waits for @code{dmnsn_get_progress()} to be >= @code{prog}, but in a much better way than spinlocking (internally, a condition variable is used).

Background tasks themselves will be interested in three more functions.
To indicate progress to the user, progress objects store one "element" for each level of loop nesting a task would like to report the progress of.
Only the innermost loop need increment the progress counter, as in this example:

@example
dmnsn_new_progress_element(progress, i_max);
for (i = 0; i < i_max; ++i) @{
  dmnsn_new_progress_element(progress, j_max);
  for (j = 0; j < j_max; ++j) @{
    /* Do stuff */
    dmnsn_increment_progress(progress);
  @}
@}
@end example

For robustness, tasks should call @code{dmnsn_done_progress()} when they finish, even if they fail.
This function immediately sets the progress to 100%, which wakes up all waiters.
Otherwise, a user's application may hang calling @code{dmnsn_wait_progress()}.


@node Geometry
@chapter Geometry

@example
/* Vector and matrix types. */

@tindex dmnsn_vector
typedef struct @{
  double x, y, z;
@} dmnsn_vector;

@tindex dmnsn_matrix
typedef struct @{
  double n[4][4];
@} dmnsn_matrix;

/* A line, or ray. */
@tindex dmnsn_line
typedef struct @{
  dmnsn_vector x0; /* A point on the line */
  dmnsn_vector n;  /* A normal vector; the direction of the line */
@} dmnsn_line;

/* Vector/matrix construction */

@findex dmnsn_new_vector()
dmnsn_vector dmnsn_new_vector(double x, double y, double z);

@findex dmnsn_new_matrix()
dmnsn_matrix
dmnsn_new_matrix(double a0, double a1, double a2, double a3,
                 double b0, double b1, double b2, double b3,
                 double c0, double c1, double c2, double c3,
                 double d0, double d1, double d2, double d3);

@findex dmnsn_identity_matrix()
dmnsn_matrix dmnsn_identity_matrix();
@findex dmnsn_scale_matrix()
dmnsn_matrix dmnsn_scale_matrix(dmnsn_vector s);
@findex dmnsn_translation_matrix()
dmnsn_matrix dmnsn_translation_matrix(dmnsn_vector d);
@findex dmnsn_rotation_matrix()
dmnsn_matrix dmnsn_rotation_matrix(dmnsn_vector theta);

@findex dmnsn_new_line()
dmnsn_line dmnsn_new_line(dmnsn_vector x0, dmnsn_vector n);

/* Vector and matrix arithmetic */

@findex dmnsn_vector_add()
dmnsn_vector dmnsn_vector_add(dmnsn_vector lhs, dmnsn_vector rhs);
@findex dmnsn_vector_sub()
dmnsn_vector dmnsn_vector_sub(dmnsn_vector lhs, dmnsn_vector rhs);
@findex dmnsn_vector_mul()
dmnsn_vector dmnsn_vector_mul(double lhs, dmnsn_vector rhs);
@findex dmnsn_vector_div()
dmnsn_vector dmnsn_vector_div(dmnsn_vector lhs, double rhs);

@findex dmnsn_vector_dot()
double       dmnsn_vector_dot(dmnsn_vector lhs, dmnsn_vector rhs);
@findex dmnsn_vector_cross()
dmnsn_vector dmnsn_vector_cross(dmnsn_vector lhs, dmnsn_vector rhs);

@findex dmnsn_vector_norm()
double       dmnsn_vector_norm(dmnsn_vector n);
@findex dmnsn_vector_normalize()
dmnsn_vector dmnsn_vector_normalize(dmnsn_vector n);

@findex dmnsn_matrix_inverse()
dmnsn_matrix dmnsn_matrix_inverse(dmnsn_matrix A);
@findex dmnsn_matrix_mul()
dmnsn_matrix dmnsn_matrix_mul(dmnsn_matrix lhs, dmnsn_matrix rhs);
@findex dmnsn_matrix_vector_mul()
dmnsn_vector dmnsn_matrix_vector_mul(dmnsn_matrix lhs,
                                     dmnsn_vector rhs);
@findex dmnsn_matrix_line_mul()
dmnsn_line   dmnsn_matrix_line_mul(dmnsn_matrix lhs, dmnsn_line rhs);

@findex dmnsn_line_point()
dmnsn_vector dmnsn_line_point(dmnsn_line l, double t);
@findex dmnsn_line_index()
double dmnsn_line_index(dmnsn_line l, dmnsn_vector x);
@end example

@cindex scalar
@cindex vector
@cindex matrix
@cindex line
@cindex ray
For performing 3-D computational geometry, the Dimension Library supports geometric types and many operations on these types.
libdimension defines the @code{dmnsn_vector}, @code{dmnsn_matrix}, and @code{dmnsn_line} geometric types.
They may be easily constructed by the self-explanatory @code{dmnsn_new_vector()}, @code{dmnsn_new_matrix()}, or @code{dmnsn_new_line()}.

@cindex transformation
@cindex norm
@cindex normalization
@cindex dot product
@cindex cross product
Vectors support addition and subtraction, multiplication and division by a scalar, the dot and cross products, the norm and normalization operations, and transformation by a matrix (@code{dmnsn_matrix_vector_mul()}).

@cindex matrix inversion
Matricies support matrix multiplication, and inversion.
Inversion uses a very fast partitioning algorithm.
As well, there are four special matrix constructors.
@code{dmnsn_identity_matrix()} simply returns the identity matrix.
@code{dmnsn_scale_matrix(s)} returns a matrix which scales each dimension by a factor of the corresponding dimension of the @code{s}.
@code{dmnsn_translate_matrix(d)} returns a matrix which translates by @code{d}.
Finally, @code{dmnsn_rotation_matrix(theta)} returns a matrix which rotates by an angle of @code{dmnsn_vector_norm(theta)}, about the axis @code{dmnsn_vector_normalize(theta)}.

Lines support transformation by a matrix (@code{dmnsn_matrix_line_mul(A, l) = dmnsn_new_line(A*l.x0, A*(l.x0 + l.n) - A*l.x0)}).
Also, @code{dmnsn_line_point(l, t) = l.x0 + t*l.n} gives the point @code{t} on the line, and @code{dmnsn_line_index(l, x)} gives the @code{t} value such that @code{dmnsn_line_point(l, t) == x}.

@node Color
@chapter Color

@example
@tindex dmnsn_color
typedef struct @{
  double filter, trans; /* Filter transparancy only lets light of this
                           color through; regular transparancy lets all
                           colors through.  filter + trans should be
                           <= 1.0. */
  /* ... */
@} dmnsn_color;

@tindex dmnsn_CIE_XYZ
typedef struct @{
  double X, Y, Z; /* X, Y, and Z are tristimulus values, unbounded
                     above zero.
Diffuse white is (0.9505, 1,
                     1.089). */
@} dmnsn_CIE_XYZ;

@tindex dmnsn_CIE_xyY
typedef struct @{
  double x, y, Y; /* x and y are chromaticity coordinates, and Y is
                     luminance, in the CIE 1931 xyZ color space.
We
                     use an unlimited light model, so x,y in [0, 1] and
                     Y >= 0, with 1 = diffuse white */
@} dmnsn_CIE_xyY;

@tindex dmnsn_CIE_Lab
typedef struct @{
  double L, a, b; /* L is luminence (100 = diffuse white); a and b are
                     color-opponent dimensions.
This color space is
                     used for color arithmetic. */
@} dmnsn_CIE_Lab;

@tindex dmnsn_CIE_Luv
typedef struct @{
  double L, u, v; /* L is luminence (100 = diffuse white); u and v are
                     chromaticity coordinates. */
@} dmnsn_CIE_Luv;

@tindex dmnsn_sRGB
typedef struct @{
  double R, G, B; /* sRGB R, G, and B values */
@} dmnsn_sRGB;

/* Standard colors */
@vindex dmnsn_black
@vindex dmnsn_white
@vindex dmnsn_red
@vindex dmnsn_green
@vindex dmnsn_blue
@vindex dmnsn_magenta
@vindex dmnsn_yellow
@vindex dmnsn_cyan
extern const dmnsn_color dmnsn_black, dmnsn_white, dmnsn_red,
  dmnsn_green, dmnsn_blue, dmnsn_magenta, dmnsn_yellow, dmnsn_cyan;

/* Standard whitepoint, determined by the conversion of sRGB white to
   CIE XYZ */
@vindex dmnsn_whitepoint
extern const dmnsn_CIE_XYZ dmnsn_whitepoint;

/* Color conversions */

@findex dmnsn_color_from_XYZ()
dmnsn_color dmnsn_color_from_XYZ(dmnsn_CIE_XYZ XYZ);
@findex dmnsn_color_from_xyY()
dmnsn_color dmnsn_color_from_xyY(dmnsn_CIE_xyY xyY);
@findex dmnsn_color_from_Lab()
dmnsn_color dmnsn_color_from_Lab(dmnsn_CIE_Lab Lab,
                                 dmnsn_CIE_XYZ white);
@findex dmnsn_color_from_Luv()
dmnsn_color dmnsn_color_from_Luv(dmnsn_CIE_Luv Luv,
                                 dmnsn_CIE_XYZ white);
@findex dmnsn_color_from_sRGB()
dmnsn_color dmnsn_color_from_sRGB(dmnsn_sRGB sRGB);

@findex dmnsn_XYZ_from_color()
dmnsn_CIE_XYZ dmnsn_XYZ_from_color(dmnsn_color color);
@findex dmnsn_xyY_from_color()
dmnsn_CIE_xyY dmnsn_xyY_from_color(dmnsn_color color);
@findex dmnsn_Lab_from_color()
dmnsn_CIE_Lab dmnsn_Lab_from_color(dmnsn_color color,
                                   dmnsn_CIE_XYZ white);
@findex dmnsn_Luv_from_color()
dmnsn_CIE_Luv dmnsn_Luv_from_color(dmnsn_color color,
                                   dmnsn_CIE_XYZ white);
@findex dmnsn_sRGB_from_color()
dmnsn_sRGB    dmnsn_sRGB_from_color(dmnsn_color color);

/* Is this color black? */
@findex dmsnn_color_is_black()
bool dmnsn_color_is_black(dmnsn_color color);

/* Perceptual color manipulation */
@findex dmnsn_color_add()
dmnsn_color dmnsn_color_add(dmnsn_color color1, dmnsn_color color2);
@findex dmnsn_color_mul()
dmnsn_color dmnsn_color_mul(double n, dmnsn_color color);
@findex dmnsn_color_gradient()
dmnsn_color dmnsn_color_gradient(dmnsn_color c1, dmnsn_color c2,
                                 double n);
@findex dmnsn_color_filter()
dmnsn_color dmnsn_color_filter(dmnsn_color color, dmnsn_color filter);
@findex dmnsn_color_illuminate()
dmnsn_color dmnsn_color_illuminate(dmnsn_color light,
                                   dmnsn_color color);

/* Perceptual color difference */
@findex dmnsn_color_difference()
double dmnsn_color_difference(dmnsn_color color1, dmnsn_color color2);
@end example

@cindex color
@cindex CIE XYZ
@cindex CIE xyY
@cindex CIE L*a*b*
@cindex CIE L*u*v*
@cindex sRGB
@cindex RGB
The Dimension Library supports many different representations of color.
The details of each representation are beyond the scope of this manual, but libdimension supports CIE XYZ, xyY, L*a*b*, L*u*v*, and sRGB color.
CIE L*a*b* and L*u*v* are designed to be perceptually uniform, meaning changes in their color coordinates correspond to perceptual changes of equal magnitude.
The @code{dmnsn_color} type is used by libdimension itself to represent colors, internally in the sRGB color space.
The @code{.filter} field gives the color's filtered transparency, which lets same-colored light through, while the @code{.trans} field stores non-filtered transparency.

The @code{dmnsn_color_from_*()} and @code{dmnsn_*_from_color()} functions are used to convert to and from the @code{dmnsn_color} type.
The conversions to @code{dmnsn_color} set the @code{.filter} and @code{.trans} fields to zero, and those fields are ignored by the inverse conversions.
Conversions to and from CIE L*a*b* and L*u*v* colors take an extra parameter, which specifies the absolute color value of the whitepoint the conversions are relative to.
@code{dmnsn_whitepoint} is a good value for this parameter.

@code{dmnsn_color_add()} adds two colors in a perceptually-correct way.
@code{dmnsn_color_mul()} scales the brightness of a color.
@code{dmnsn_color_gradient()} returns the color at point @code{n} on a gradient from @code{c1} at 0 to @code{c2} at 1.
@code{dmnsn_color_filter()} returns the color obtained by filtering @code{color} through @code{filter}.
@code{dmnsn_color_illuminate()} return the color obtained by illuminating @code{color} with @code{light}-colored light.
@code{dmnsn_color_difference()} returns the magnatude of the perceptual difference between two colors.


@node Canvases
@chapter Canvases

@example
@tindex dmnsn_canvas *
typedef struct @{
  /* width, height */
  unsigned int x, y;

  /* An array of dmnsn_canvas_optimizer's - see below */
  dmnsn_array *optimizers;

  /* ... */
@} dmnsn_canvas;

/* Allocate and free a canvas */
@findex dmnsn_new_canvas()
dmnsn_canvas *dmnsn_new_canvas(unsigned int x, unsigned int y);
@findex dmnsn_delete_canvas()
void dmnsn_delete_canvas(dmnsn_canvas *canvas);

/* Pixel accessors */
@findex dmnsn_get_pixel()
dmnsn_color dmnsn_get_pixel(const dmnsn_canvas *canvas,
                            unsigned int x, unsigned int y);
@findex dmnsn_set_pixel()
void dmnsn_set_pixel(dmnsn_canvas *canvas,
                     unsigned int x, unsigned int y,
                     dmnsn_color color);
@end example

@cindex canvas
@cindex rendering target
The target of a rendering operation in the Dimension Library is a canvas object, represented by the type @code{dmnsn_canvas *}.
This type stores the dimensions of the canvas in the @code{->x} and @code{->y} fields.
The pixel at (x,y) can be examined or set by the accessors @code{dmnsn_get_pixel()} and @code{dmnsn_set_pixel()}.

Canvases may be imported from or exported to images.
In the future, canvases will also be able to be treated as object textures, to support images as textures.

@menu
* PNG Import and Export:: Importing and exporting canvases to and from PNG files
* OpenGL:: Drawing and reading canvases to and from OpenGL buffers
* Canvas Optimization:: Optimizing a canvas for a later export
@end menu

@node PNG Import and Export
@section PNG Import and Export

@example
/* Optimize canvas for PNG exporting */
@findex dmnsn_png_optimize_canvas()
int dmnsn_png_optimize_canvas(dmnsn_canvas *canvas);

/* Write canvas to file in PNG format.  Returns 0 on success, nonzero
   on failure */
@findex dmnsn_png_write_canvas()
int dmnsn_png_write_canvas(const dmnsn_canvas *canvas, FILE *file);
@findex dmnsn_png_write_canvas_async()
dmnsn_progress *
dmnsn_png_write_canvas_async(const dmnsn_canvas *canvas, FILE *file);

/* Read a canvas from a PNG file.
Returns NULL on failure. */
@findex dmnsn_png_read_canvas()
dmnsn_canvas *dmnsn_png_read_canvas(FILE *file);
@findex dmnsn_png_read_canvas_async()
dmnsn_progress *dmnsn_png_read_canvas_async(dmnsn_canvas **canvas,
                                            FILE *file);
@end example

@cindex PNG
The Dimension Library supports import and export of canvas to and from PNG files; this is currently the only supported image type.
The interface is simple: @code{dmnsn_png_write_canvas()} writes the canvas in PNG format to the given file, at maximum quality; @code{dmnsn_png_read_canvas()} imports a PNG file to a canvas.
The @code{*_async()} versions work as described in @ref{Asynchronicity}.
If it is known in advance that a canvas will be exported to a PNG file, calling @code{dmnsn_png_optimize_canvas()} on it before it is written to will speed up the export process; see @ref{Canvas Optimization}.

@node OpenGL
@section OpenGL

@example
/* Optimize canvas for GL drawing */
@findex dmnsn_gl_optimize_canvas()
int dmnsn_gl_optimize_canvas(dmnsn_canvas *canvas);

/* Write canvas to GL framebuffer.  Returns 0 on success, nonzero on
   failure. */
@findex dmnsn_gl_write_canvas()
int dmnsn_gl_write_canvas(const dmnsn_canvas *canvas);

/* Read a canvas from a GL framebuffer.
Returns NULL on failure. */
@findex dmnsn_gl_read_canvas()
dmnsn_canvas *dmnsn_gl_read_canvas(unsigned int x0, unsigned int y0,
                                   unsigned int width,
                                   unsigned int height);
@end example

@cindex GL
@cindex OpenGL
Canvases may be written to or read from an OpenGL buffer with the @code{dmnsn_gl_write_canvas()} and @code{dmnsn_gl_read_canvas()} functions, respectively.
Writing uses the @code{glDrawPixels()} GL function, and reading uses the @code{glReadPixels()} function.
@code{dmnsn_gl_read_canvas()} starts reading at (@code{x0}, @code{y0}), and reads a @code{width}*@code{height} sized image.
These operations should be fast (especially if optimized), so no @code{..._async()} versions are supplied.
If it is known in advance that a canvas will be drawn to an OpenGL buffer, calling @code{dmnsn_gl_optimize_canvas()} on it before it is written to will speed up the export process; see @ref{Canvas Optimization}.

@node Canvas Optimization
@section Canvas Optimization

@example
/* Canvas optimizer callback types */
@tindex dmnsn_canvas_optimizer_fn
typedef void dmnsn_canvas_optimizer_fn(dmnsn_canvas *canvas,
                                       dmnsn_canvas_optimizer optimizer,
                                       unsigned int x, unsigned int y);

/* Canvas optimizer */
@tindex dmnsn_canvas_optimizer
typedef struct @{
  dmnsn_canvas_optimizer_fn *optimizer_fn;
  dmnsn_free_fn             *free_fn;
  void *ptr;
@} dmnsn_canvas_optimizer;

/* Set a canvas optimizer */
@findex dmnsn_optimize_canvas()
int dmnsn_optimize_canvas(dmnsn_canvas *canvas,
                          dmnsn_canvas_optimizer optimizer);
@end example

@cindex optimization, canvas
@cindex optimization, export
If a canvas is to be exported to a different format, the export process can be sped up if the pixels are stored in the target format as they are written to a canvas.
This is what canvas optimizers do: they register callbacks that are triggered upon a @code{dmnsn_set_pixel()} call, generally storing the color in the appropriate format for the target (sRGB for PNG, for example) in some other buffer.
Then the exporting process is a breeze, because the canvas doesn't have to be converted to another format.

The @code{dmnsn_canvas_optimizer} type stores a pointer to a callback function to be executed upon calls to @code{dmnsn_set_pixel()} in its @code{.optimizer_fn} field.
This function should match the signature of the @code{dmnsn_canvas_optimizer_fn} type.
Its @code{.ptr} field stores a generic pointer to any type of data the optimizer may wish to store.
This pointer will be provided to its @code{.free_fn} callback when @code{dmnsn_delete_canvas()} is called, and may simply point to the standard library @code{free} function.

To register a new canvas optimizer, the program should first check that the same optimization hasn't already been applied by examining the @code{dmnsn_canvas *}'s @code{->optimizers} array, and testing each @code{dmnsn_canvas_optimizer}'s @code{.optimizer_fn} for equality with the address of the new callback.
If the optimization hasn't yet been applied, the program should call @code{dmnsn_optimize_canvas()}, which returns 0 if it succeeded, and nonzero otherwise.
Note that this function will fail if @code{dmnsn_set_pixel()} has ever been called on the target canvas, since pixels which have already been set would not be known to the optimizer.

@node Objects
@chapter Objects

@example
@tindex dmnsn_object *
typedef struct @{
  /* Surface properties */
  dmnsn_texture *texture;

  /* Transformation matrix */
  dmnsn_matrix trans, trans_inv;

  /* Bounding box */
  dmnsn_vector min, max;

  /* Callback functions */
  dmnsn_object_intersection_fn *intersection_fn;
  dmnsn_object_inside_fn       *inside_fn;
  dmnsn_free_fn                *free_fn;

  /* Generic pointer for object info */
  void *ptr;
@} dmnsn_object;

/* Object callback types */
@tindex dmnsn_object_intersections_fn
typedef dmnsn_intersection *
dmnsn_object_intersection_fn(const dmnsn_object *object,
                             dmnsn_line line);
@tindex dmnsn_object_inside_fn
typedef int dmnsn_object_inside_fn(const dmnsn_object *object,
                                   dmnsn_vector point);

/* Allocate a dummy object */
@findex dmnsn_new_object()
dmnsn_object *dmnsn_new_object();
@findex dmnsn_delete_object()
void dmnsn_delete_object(dmnsn_object *object);
@end example

@cindex object
The Dimension Library renders 3-D objects, represented by the @code{dmnsn_object *} type.
This type has callback functions for determining if and where a ray intersects the object, and whether a point is inside the object.
In the future, many more callbacks will be added.
libdimension comes with a few simple object types like spheres and cubes, or you may create your own by customizing the object callbacks.
The field @code{->ptr} is a void pointer which may be used to store additional information about an object.
The @code{->trans} field is a transformation matrix, transforming the rays which intersect the object, rather than the object itself.
Thus, @code{->trans} should be set to the inverse of the transformations you wish to apply to the object.

@cindex object callbacks
The @code{->intersection_fn} callback should point to a function with the same signature as the @code{dmnsn_object_intersection_fn} type.
It should return a @code{dmnsn_intersection *} corresponding to the closest intersection, or @code{NULL} if the ray does not intersect the object.

The @code{->inside_fn} callback should point to a function matching the signature of the @code{dmnsn_object_inside_fn} type.
It should return 0 if the given @code{point} is outside the object, and nonzero when that point is inside the object.
The callback is free to return any value in the case that the point lies directly on the surface of the object.

@menu
* Spheres:: Spheres
* Cubes:: Cubes
@end menu

@node Spheres
@section Spheres

@example
@findex dmnsn_new_sphere()
dmnsn_object *dmnsn_new_sphere();
@end example

@cindex sphere
The Dimension Library has a few built-in basic shape primitives.
One of them is the sphere; @code{dmnsn_new_sphere()} returns a sphere of radius 1, centered at the origin.
Use the object's transformation matrix to scale, translate, and/or rotate it.

@node Cubes
@section Cubes

@example
@findex dmnsn_new_cube()
dmnsn_object *dmnsn_new_cube();
@end example

@cindex cube
@code{dmnsn_new_cube()} returns a cube, axis-aligned, from (-1, -1, -1) to (1, 1, 1).
Use its transformation matrix to scale, translate, and/or rotate it.


@node Cameras
@chapter Cameras

@example
@tindex dmnsn_camera *
typedef struct @{
  /* Callback functions */
  dmnsn_camera_ray_fn *ray_fn;
  dmnsn_free_fn       *free_fn;

  /* Generic pointer for camera info */
  void *ptr;
@} dmnsn_camera;

/* Camera callback types */
@tindex dmnsn_camera_ray_fn
typedef dmnsn_line dmnsn_camera_ray_fn(const dmnsn_camera *camera,
                                       double x, double y);

@findex dmnsn_new_camera()
dmnsn_camera *dmnsn_new_camera();
@findex dmnsn_delete_camera()
void dmnsn_delete_camera(dmnsn_camera *camera);
@end example

@cindex camera
In order to project a 3-D scene onto a 2-D plane, the Dimension Library uses a generic camera type.
A camera provides the Dimension Library the camera ray corresponding to each pixel in the canvas, by its @code{->ray_fn} callback.

@code{->ray_fn} should point to a function matching the signature of the type @code{dmnsn_camera_ray_fn}, and should return the ray corresponding to the pixel at (@code{x}, @code{y}) in a hypothetical square canvas from (0, 0) to (1, 1).

@menu
* Perspective Cameras:: Simple perspective cameras
@end menu

@node Perspective Cameras
@section Perspective Cameras

@example
@findex dmnsn_new_perspective_camera()
dmnsn_camera *dmnsn_new_perspective_camera();

/* Get or set the transformation matrix */
dmnsn_matrix
dmnsn_get_perspective_camera_trans(const dmnsn_camera *camera);
void dmnsn_set_perspective_camera_trans(dmnsn_camera *camera,
                                        dmnsn_matrix T);
@end example

@cindex perspective
The function @code{dmnsn_new_perspective_camera} creates a perspective camera, situated at the origin, looking toward (0, 0, 1), and aiming at a screen from (-0.5, -0.5) to (0.5, 0.5) on the z = 1 plane.
Camera rays may be transformed by a matrix set by @code{dmnsn_set_perspective_camera_trans()} and retrieved by @code{dmnsn_get_perspective_camera_trans()}.


@node Scenes
@chapter Scenes

@example

enum @{
  DMNSN_RENDER_NONE         = /* ... */,
  DMNSN_RENDER_PIGMENT      = /* ... */,
  DMNSN_RENDER_LIGHTS       = /* ... */,
  DMNSN_RENDER_FINISH       = /* ... */,
  DMNSN_RENDER_TRANSLUCENCY = /* ... */,
  DMNSN_RENDER_REFLECTION   = /* ... */,
  DMNSN_RENDER_FULL         = ~DMNSN_RENDER_NONE
@};

@tindex dmnsn_quality
typedef unsigned int dmnsn_quality;

@tindex dmnsn_scene *
typedef struct @{
  /* World attributes */
  dmnsn_color background;
  dmnsn_texture *default_texture;

  /* Camera */
  dmnsn_camera *camera;

  /* Canvas */
  dmnsn_canvas *canvas;

  /* Objects */
  dmnsn_array *objects;

  /* Lights */
  dmnsn_array *lights;

  /* Rendering quality */
  dmnsn_quality quality;

  /* Recursion limit */
  unsigned int limit;

  /* Number of paralell threads */
  unsigned int nthreads;
@} dmnsn_scene;

@findex dmnsn_new_scene()
dmnsn_scene *dmnsn_new_scene();
@findex dmnsn_delete_scene()
void dmnsn_delete_scene(dmnsn_scene *scene);
@end example

@cindex scene
The @code{dmnsn_scene *} type ties all the components of a 3-D world together.
A scene stores a background color in its @code{->background} field, a @code{dmnsn_array *} of @code{const dmnsn_object *}'s in its @code{->objects} field, a @code{dmnsn_camera *} in its @code{->camera} field, and a @code{dmnsn_canvas *} in its @code{->canvas} field.
Scenes can be rendered, producing an image in their canvas field.

@menu
* Raytracing:: Rendering a scene by raytracing
@end menu

@node Raytracing
@section Raytracing

@example
@findex dmnsn_raytrace_scene()
int dmnsn_raytrace_scene(dmnsn_scene *scene);
@findex dmnsn_raytrace_scene_async()
dmnsn_progress *dmnsn_raytrace_scene_async(dmnsn_scene *scene);
@end example

@cindex raytracing
The @code{dmnsn_raytrace_scene()} function renders a scene by raytracing - casting rays from the camera to objects in its view.
The @code{..._async()} version works as described in @ref{Asynchronicity}.


@node Type Index
@unnumbered Type Index

@printindex tp


@node Function and Constant Index
@unnumbered Function and Constant Index

@printindex fn


@node Concept Index
@unnumbered Concept Index

@printindex cp

@bye