ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/rt/raycalls.c
Revision: 2.1
Committed: Sat Feb 22 02:07:29 2003 UTC (21 years, 2 months ago) by greg
Content type: text/plain
Branch: MAIN
Log Message:
Changes and check-in for 3.5 release
Includes new source files and modifications not recorded for many years
See ray/doc/notes/ReleaseNotes for notes between 3.1 and 3.5 release

File Contents

# User Rev Content
1 greg 2.1 #ifndef lint
2     static const char RCSid[] = "$Id$";
3     #endif
4     /*
5     * raycalls.c - interface for running Radiance rendering as a library
6     *
7     * External symbols declared in ray.h
8     */
9    
10     /* ====================================================================
11     * The Radiance Software License, Version 1.0
12     *
13     * Copyright (c) 1990 - 2002 The Regents of the University of California,
14     * through Lawrence Berkeley National Laboratory. All rights reserved.
15     *
16     * Redistribution and use in source and binary forms, with or without
17     * modification, are permitted provided that the following conditions
18     * are met:
19     *
20     * 1. Redistributions of source code must retain the above copyright
21     * notice, this list of conditions and the following disclaimer.
22     *
23     * 2. Redistributions in binary form must reproduce the above copyright
24     * notice, this list of conditions and the following disclaimer in
25     * the documentation and/or other materials provided with the
26     * distribution.
27     *
28     * 3. The end-user documentation included with the redistribution,
29     * if any, must include the following acknowledgment:
30     * "This product includes Radiance software
31     * (http://radsite.lbl.gov/)
32     * developed by the Lawrence Berkeley National Laboratory
33     * (http://www.lbl.gov/)."
34     * Alternately, this acknowledgment may appear in the software itself,
35     * if and wherever such third-party acknowledgments normally appear.
36     *
37     * 4. The names "Radiance," "Lawrence Berkeley National Laboratory"
38     * and "The Regents of the University of California" must
39     * not be used to endorse or promote products derived from this
40     * software without prior written permission. For written
41     * permission, please contact [email protected].
42     *
43     * 5. Products derived from this software may not be called "Radiance",
44     * nor may "Radiance" appear in their name, without prior written
45     * permission of Lawrence Berkeley National Laboratory.
46     *
47     * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
48     * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
49     * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
50     * DISCLAIMED. IN NO EVENT SHALL Lawrence Berkeley National Laboratory OR
51     * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
52     * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
53     * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
54     * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
55     * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
56     * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
57     * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
58     * SUCH DAMAGE.
59     * ====================================================================
60     *
61     * This software consists of voluntary contributions made by many
62     * individuals on behalf of Lawrence Berkeley National Laboratory. For more
63     * information on Lawrence Berkeley National Laboratory, please see
64     * <http://www.lbl.gov/>.
65     */
66    
67     /*
68     * These routines are designed to aid the programmer who wishes
69     * to call Radiance as a library. Unfortunately, the system was
70     * not originally intended to be run this way, and there are some
71     * awkward limitations to contend with. The most irritating
72     * perhaps is that the global variables and functions do not have
73     * a prefix, and the symbols are a bit generic. This results in a
74     * serious invasion of the calling application's name-space, and
75     * you may need to rename either some Radiance routines or some
76     * of your routines to avoid conflicts. Another limitation is
77     * that the global variables are not gathered together into any
78     * sort of context, so it is impossible to simultaneously run
79     * this library on multiple scenes or in multiple threads.
80     * You get one scene and one thread, and if you want more, you
81     * will have to go with the process model used by the programs
82     * gen/mkillum, hd/rholo, and px/pinterp. Finally, unrecoverable
83     * errors result in a call to the application-defined function
84     * quit(). The usual thing to do is to call exit().
85     * You might want to do something else instead, like
86     * call setjmp()/longjmp() to bring you back to the calling
87     * function for recovery. You may also wish to define your own
88     * wputs(s) and eputs(s) functions to output warning and error
89     * messages, respectively.
90     *
91     * With those caveats, we have attempted to make the interface
92     * as simple as we can. Global variables and their defaults
93     * are defined below, and including "ray.h" declares these
94     * along with all the routines you are likely to need. First,
95     * assign the global variable progname to your argv[0], then
96     * change the rendering parameters as you like. If you have a set
97     * of option arguments you are working from, the getrenderopt(ac,av)
98     * call should be very useful. Before tracing any rays, you
99     * must read in the octree with a call to ray_init(oct).
100     * Passing NULL for the file name causes ray_init() to read
101     * the octree from the standard input -- rarely a good idea.
102     * However, one may read an octree from a program (such as
103     * oconv) by preceding a shell command by a '!' character.
104     *
105     * To trace a ray, define a RAY object myRay and assign:
106     *
107     * myRay.rorg = ( ray origin point )
108     * myRay.rdir = ( normalized ray direction )
109     * myRay.rmax = ( maximum length, or zero for no limit )
110     *
111     * If you are rendering from a VIEW structure, this can be
112     * accomplished with a single call for the ray at (x,y):
113     *
114     * myRay.rmax = viewray(myRay.rorg, myRay.rdir, &myView, x, y);
115     *
116     * Then, trace the primary ray with:
117     *
118     * ray_trace(&myRay);
119     *
120     * The resulting contents of myRay should provide you with
121     * more than enough information about what the ray hit,
122     * the computed value, etc. For further clues of how to
123     * compute irradiance, how to get callbacks on the evaluated
124     * ray tree, etc., see the contents of rtrace.c. See
125     * also the rpmain.c, rtmain.c, and rvmain.c modules
126     * to learn more how rendering options are processed.
127     *
128     * When you are done, you may call ray_done(1) to clean
129     * up memory used by Radiance. It doesn't free everything,
130     * but it makes a valiant effort. If you call ray_done(0),
131     * it leaves data that is likely to be reused, including
132     * loaded data files and fonts. The library may be
133     * restarted at any point by calling ray_init() on a new
134     * octree.
135     *
136     * The call ray_save(rp) allocates and returns a buffer
137     * with the current global parameter settings, which may be
138     * restored at any time with a call to ray_restore(rp).
139     * This buffer contains no linked information, and thus
140     * may be passed between processes using write() and
141     * read() calls, so long as byte order is maintained.
142     * Calling ray_restore(NULL) restores the original
143     * default parameters, which is also retrievable with
144     * the call ray_defaults(rp). (These should be the
145     * same as the defaults for rtrace.)
146     */
147    
148     #include "ray.h"
149    
150     #include "source.h"
151    
152     #include "ambient.h"
153    
154     #include "otypes.h"
155    
156     #include "random.h"
157    
158     #include "data.h"
159    
160     #include "font.h"
161    
162     char *progname = "unknown_app"; /* caller sets to argv[0] */
163    
164     char *octname; /* octree name we are given */
165    
166     char *shm_boundary = NULL; /* boundary of shared memory */
167    
168     CUBE thescene; /* our scene */
169     OBJECT nsceneobjs; /* number of objects in our scene */
170    
171     int dimlist[MAXDIM]; /* sampling dimensions */
172     int ndims = 0; /* number of sampling dimensions */
173     int samplendx = 0; /* index for this sample */
174    
175     void (*trace)() = NULL; /* trace call */
176    
177     extern void ambnotify();
178     void (*addobjnotify[])() = {ambnotify, NULL};
179    
180     int do_irrad = 0; /* compute irradiance? */
181    
182     double dstrsrc = 0.0; /* square source distribution */
183     double shadthresh = .05; /* shadow threshold */
184     double shadcert = .5; /* shadow certainty */
185     int directrelay = 2; /* number of source relays */
186     int vspretest = 512; /* virtual source pretest density */
187     int directvis = 1; /* sources visible? */
188     double srcsizerat = .2; /* maximum ratio source size/dist. */
189    
190     COLOR cextinction = BLKCOLOR; /* global extinction coefficient */
191     COLOR salbedo = BLKCOLOR; /* global scattering albedo */
192     double seccg = 0.; /* global scattering eccentricity */
193     double ssampdist = 0.; /* scatter sampling distance */
194    
195     double specthresh = .15; /* specular sampling threshold */
196     double specjitter = 1.; /* specular sampling jitter */
197    
198     int backvis = 1; /* back face visibility */
199    
200     int maxdepth = 6; /* maximum recursion depth */
201     double minweight = 4e-3; /* minimum ray weight */
202    
203     char *ambfile = NULL; /* ambient file name */
204     COLOR ambval = BLKCOLOR; /* ambient value */
205     int ambvwt = 0; /* initial weight for ambient value */
206     double ambacc = 0.2; /* ambient accuracy */
207     int ambres = 128; /* ambient resolution */
208     int ambdiv = 512; /* ambient divisions */
209     int ambssamp = 0; /* ambient super-samples */
210     int ambounce = 0; /* ambient bounces */
211     char *amblist[AMBLLEN+1]; /* ambient include/exclude list */
212     int ambincl = -1; /* include == 1, exclude == 0 */
213    
214    
215     void
216     ray_init(otnm) /* initialize ray-tracing calculation */
217     char *otnm;
218     {
219     if (nobjects > 0) /* free old scene data */
220     ray_done(0);
221     /* initialize object types */
222     if (ofun[OBJ_SPHERE].funp == o_default)
223     initotypes();
224     /* initialize urand */
225     if (urperm == NULL)
226     initurand(2048);
227     /* read scene octree */
228     readoct(octname = otnm, ~(IO_FILES|IO_INFO), &thescene, NULL);
229     nsceneobjs = nobjects;
230     /* find and mark sources */
231     marksources();
232     /* initialize ambient calculation */
233     setambient();
234     /* ready to go... */
235     }
236    
237    
238     void
239     ray_trace(RAY *r) /* trace a primary ray */
240     {
241     rayorigin(r, NULL, PRIMARY, 1.0);
242     samplendx++;
243     rayvalue(r); /* assumes origin and direction are set */
244     }
245    
246    
247     void
248     ray_done(freall) /* free ray-tracing data */
249     int freall;
250     {
251     retainfonts = 1;
252     ambdone();
253     ambnotify(OVOID);
254     freesources();
255     freeobjects(0, nobjects);
256     donesets();
257     octdone();
258     thescene.cutree = EMPTY;
259     octname = NULL;
260     if (freall) {
261     retainfonts = 0;
262     freefont(NULL);
263     freedata(NULL);
264     initurand(0);
265     }
266     if (nobjects > 0) {
267     sprintf(errmsg, "%d objects left after call to ray_done()",
268     nobjects);
269     error(WARNING, errmsg);
270     }
271     }
272    
273    
274     void
275     ray_save(rp) /* save current parameter settings */
276     RAYPARAMS *rp;
277     {
278     int i, ndx;
279    
280     if (rp == NULL)
281     return;
282     rp->do_irrad = do_irrad;
283     rp->dstrsrc = dstrsrc;
284     rp->shadthresh = shadthresh;
285     rp->shadcert = shadcert;
286     rp->directrelay = directrelay;
287     rp->vspretest = vspretest;
288     rp->directvis = directvis;
289     rp->srcsizerat = srcsizerat;
290     copycolor(rp->cextinction, cextinction);
291     copycolor(rp->salbedo, salbedo);
292     rp->seccg = seccg;
293     rp->ssampdist = ssampdist;
294     rp->specthresh = specthresh;
295     rp->specjitter = specjitter;
296     rp->backvis = backvis;
297     rp->maxdepth = maxdepth;
298     rp->minweight = minweight;
299     copycolor(rp->ambval, ambval);
300     bzero(rp->ambfile, sizeof(rp->ambfile));
301     if (ambfile != NULL)
302     strncpy(rp->ambfile, ambfile, sizeof(rp->ambfile)-1);
303     rp->ambvwt = ambvwt;
304     rp->ambacc = ambacc;
305     rp->ambres = ambres;
306     rp->ambdiv = ambdiv;
307     rp->ambssamp = ambssamp;
308     rp->ambounce = ambounce;
309     rp->ambincl = ambincl;
310     bzero(rp->amblval, sizeof(rp->amblval));
311     ndx = 0;
312     for (i = 0; i < AMBLLEN && amblist[i] != NULL; i++) {
313     int len = strlen(amblist[i]);
314     if (ndx+len >= sizeof(rp->amblval))
315     break;
316     strcpy(rp->amblval+ndx, amblist[i]);
317     ndx += len+1;
318     }
319     while (i <= AMBLLEN)
320     rp->amblndx[i++] = -1;
321     }
322    
323    
324     void
325     ray_restore(rp) /* restore parameter settings */
326     RAYPARAMS *rp;
327     {
328     register int i;
329    
330     if (rp == NULL) { /* restore defaults */
331     RAYPARAMS dflt;
332     ray_defaults(&dflt);
333     ray_restore(&dflt);
334     return;
335     }
336     /* restore saved settings */
337     do_irrad = rp->do_irrad;
338     dstrsrc = rp->dstrsrc;
339     shadthresh = rp->shadthresh;
340     shadcert = rp->shadcert;
341     directrelay = rp->directrelay;
342     vspretest = rp->vspretest;
343     directvis = rp->directvis;
344     srcsizerat = rp->srcsizerat;
345     copycolor(cextinction, rp->cextinction);
346     copycolor(salbedo, rp->salbedo);
347     seccg = rp->seccg;
348     ssampdist = rp->ssampdist;
349     specthresh = rp->specthresh;
350     specjitter = rp->specjitter;
351     backvis = rp->backvis;
352     maxdepth = rp->maxdepth;
353     minweight = rp->minweight;
354     copycolor(ambval, rp->ambval);
355     ambvwt = rp->ambvwt;
356     ambdiv = rp->ambdiv;
357     ambssamp = rp->ambssamp;
358     ambounce = rp->ambounce;
359     for (i = 0; rp->amblndx[i] >= 0; i++)
360     amblist[i] = rp->amblval + rp->amblndx[i];
361     while (i <= AMBLLEN)
362     amblist[i++] = NULL;
363     ambincl = rp->ambincl;
364     /* update ambient calculation */
365     ambnotify(OVOID);
366     if (thescene.cutree != EMPTY) {
367     int newamb = (ambfile == NULL) ? rp->ambfile[0] :
368     strcmp(ambfile, rp->ambfile) ;
369    
370     if (amblist[0] != NULL)
371     for (i = 0; i < nobjects; i++)
372     ambnotify(i);
373    
374     ambfile = (rp->ambfile[0]) ? rp->ambfile : (char *)NULL;
375     if (newamb) {
376     ambres = rp->ambres;
377     ambacc = rp->ambacc;
378     setambient();
379     } else {
380     setambres(rp->ambres);
381     setambacc(rp->ambacc);
382     }
383     } else {
384     ambfile = (rp->ambfile[0]) ? rp->ambfile : (char *)NULL;
385     ambres = rp->ambres;
386     ambacc = rp->ambacc;
387     }
388     }
389    
390    
391     void
392     ray_defaults(rp) /* get default parameter values */
393     RAYPARAMS *rp;
394     {
395     int i;
396    
397     if (rp == NULL)
398     return;
399    
400     rp->do_irrad = 0;
401     rp->dstrsrc = 0.0;
402     rp->shadthresh = .05;
403     rp->shadcert = .5;
404     rp->directrelay = 2;
405     rp->vspretest = 512;
406     rp->directvis = 1;
407     rp->srcsizerat = .2;
408     setcolor(rp->cextinction, 0., 0., 0.);
409     setcolor(rp->salbedo, 0., 0., 0.);
410     rp->seccg = 0.;
411     rp->ssampdist = 0.;
412     rp->specthresh = .15;
413     rp->specjitter = 1.;
414     rp->backvis = 1;
415     rp->maxdepth = 6;
416     rp->minweight = 4e-3;
417     setcolor(rp->ambval, 0., 0., 0.);
418     bzero(rp->ambfile, sizeof(rp->ambfile));
419     rp->ambvwt = 0;
420     rp->ambres = 128;
421     rp->ambacc = 0.2;
422     rp->ambdiv = 512;
423     rp->ambssamp = 0;
424     rp->ambounce = 0;
425     rp->ambincl = -1;
426     bzero(rp->amblval, sizeof(rp->amblval));
427     for (i = AMBLLEN+1; i--; )
428     rp->amblndx[i] = -1;
429     }