ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/common/bsdf.h
Revision: 2.9
Committed: Wed Feb 23 21:58:31 2011 UTC (13 years, 2 months ago) by greg
Content type: text/plain
Branch: MAIN
Changes since 2.8: +3 -3 lines
Log Message:
Fixed issue with coordinate orientation for front transmission

File Contents

# User Rev Content
1 greg 2.9 /* RCSid $Id: bsdf.h,v 2.8 2011/02/21 22:50:37 greg Exp $ */
2 greg 2.4 /*
3     * bsdf.h
4     *
5     * Declarations for bidirectional scattering distribution functions.
6     * Assumes <stdio.h> already included.
7     *
8     * A material is oriented in right-hand coordinate system with X-axis
9     * in the surface plane pointed to the right as seen from the front.
10     * This means the Y-axis is "up" and the Z-axis is the surface normal.
11     *
12 greg 2.8 * Note that we reverse the identification of "front" and "back" from
13     * the conventions used in WINDOW 6. "Front" in our library points
14     * in the +Z direction, towards the interior of the space rather
15     * than the exterior.
16     *
17 greg 2.4 * BSDF vectors always oriented away from surface, even when "incident."
18     *
19     * Created by Greg Ward on 1/10/11.
20     *
21     */
22    
23     #ifndef _BSDF_H_
24     #define _BSDF_H_
25    
26     #include "fvect.h"
27     #include "ccolor.h"
28    
29     #ifdef __cplusplus
30     extern "C" {
31     #endif
32    
33     #define SDnameLn 128 /* maximum BSDF name length */
34     #define SDmaxCh 3 /* maximum # spectral channels */
35    
36 greg 2.9 /* Component flags for SDsampBSDF() and SDdirectHemi() */
37 greg 2.4 #define SDsampR 0x1 /* include reflection */
38     #define SDsampT 0x2 /* include transmission */
39     #define SDsampS 0x3 /* include scattering (R+T) */
40     #define SDsampSp 0x4 /* include non-diffuse portion */
41     #define SDsampDf 0x8 /* include diffuse portion */
42     #define SDsampSpR 0x5 /* include non-diffuse reflection */
43     #define SDsampSpT 0x6 /* include non-diffuse transmission */
44     #define SDsampSpS 0x7 /* include non-diffuse scattering */
45     #define SDsampAll 0xF /* include everything */
46    
47 greg 2.9 /* Projected solid angle query flags for SDsizeBSDF() */
48 greg 2.7 #define SDqueryVal 0x0 /* query single value */
49     #define SDqueryMin 0x1 /* query minimum proj. solid angle */
50     #define SDqueryMax 0x2 /* query maximum proj. solid angle */
51 greg 2.4
52     /* Error codes: normal return, out of memory, file i/o, file format, bad argument,
53     bad data, unsupported feature, internal error, unknown error */
54     typedef enum {SDEnone=0, SDEmemory, SDEfile, SDEformat, SDEargument,
55     SDEdata, SDEsupport, SDEinternal, SDEunknown} SDError;
56    
57     /* English ASCII strings corresponding to ennumerated errors */
58     extern const char *SDerrorEnglish[];
59    
60     /* Additional information on last error (ASCII English) */
61     extern char SDerrorDetail[];
62    
63     /* Holder for BSDF value and spectral color */
64     typedef struct {
65     double cieY; /* photopic BSDF (Y) value */
66     C_COLOR spec; /* spectral and (x,y) color */
67     } SDValue;
68    
69     /* Cached, encoded, cumulative distribution for one incident (solid) angle */
70     #define SD_CDIST_BASE double cTotal; \
71     struct SDCDst_s *next
72     typedef struct SDCDst_s {
73     SD_CDIST_BASE; /* base fields first */
74     /* ...encoded distribution extends struct */
75     } SDCDst;
76    
77     /* Forward declaration of BSDF component */
78     typedef struct SDComp_s SDComponent;
79    
80     /* Methods needed to handle BSDF components (nothing is optional) */
81     typedef const struct {
82     /* return non-diffuse BSDF */
83     int (*getBSDFs)(float coef[SDmaxCh], const FVECT outVec,
84     const FVECT inVec, const void *dist);
85     /* query non-diffuse PSA for vector */
86     SDError (*queryProjSA)(double *psa, const FVECT vec,
87     int qflags, const void *dist);
88     /* get cumulative distribution */
89     const SDCDst *(*getCDist)(const FVECT inVec, SDComponent *sdc);
90     /* sample cumulative distribution */
91     SDError (*sampCDist)(FVECT outVec, double randX,
92     const SDCDst *cdp);
93     /* free a spectral BSDF component */
94     void (*freeSC)(void *dist);
95     } SDFunc;
96    
97     /* Structure to hold a spectral BSDF component (typedef SDComponent above) */
98     struct SDComp_s {
99     C_COLOR cspec[SDmaxCh]; /* component spectral bases */
100     SDFunc *func; /* methods for this component */
101     void *dist; /* loaded distribution data */
102     SDCDst *cdList; /* cumulative distribution cache */
103     };
104    
105     /* Container for non-diffuse BSDF components */
106     typedef struct {
107     double minProjSA; /* minimum projected solid angle */
108     double maxHemi; /* maximum directional hemispherical */
109     int ncomp; /* number of separate components */
110     SDComponent comp[1]; /* BSDF components (extends struct) */
111     } SDSpectralDF;
112    
113     /* Loaded BSDF data */
114     typedef struct {
115     char name[SDnameLn]; /* BSDF name (derived from file) */
116     char *mgf; /* geometric description (if any) */
117     float dim[3]; /* width, height, thickness (meters) */
118     SDValue rLambFront; /* diffuse front reflectance */
119     SDValue rLambBack; /* diffuse rear reflectance */
120     SDValue tLamb; /* diffuse transmission */
121     SDSpectralDF *rf, *rb, *tf; /* non-diffuse BSDF components */
122     } SDData;
123    
124     /* List of loaded BSDFs */
125     extern struct SDCache_s {
126     SDData bsdf; /* BSDF data */
127     unsigned refcnt; /* how many callers are using us? */
128     struct SDCache_s /* next in cache list */
129     *next;
130     } *SDcacheList; /* Global BSDF cache */
131    
132     /* BSDF cache retention preference */
133     #define SDretainNone 0 /* free unreferenced data (default) */
134     #define SDretainBSDFs 1 /* keep loaded BSDFs in cache */
135     #define SDretainAll 2 /* also keep cumulative cache data */
136    
137     extern int SDretainSet; /* set to SDretainNone by default */
138    
139     /*****************************************************************
140     * The following routines are less commonly used by applications.
141     */
142    
143 greg 2.6 #define SDisLoaded(sd) ((sd)->rLambFront.spec.flags != 0)
144 greg 2.4
145     /* Report an error to the indicated stream (in English) */
146     extern SDError SDreportEnglish(SDError ec, FILE *fp);
147    
148     /* Shorten file path to useable BSDF name, removing suffix */
149     extern void SDclipName(char res[SDnameLn], const char *fname);
150    
151     /* Allocate new spectral distribution function */
152     extern SDSpectralDF *SDnewSpectralDF(int nc);
153    
154     /* Free a spectral distribution function */
155     extern void SDfreeSpectralDF(SDSpectralDF *df);
156    
157     /* Initialize an unused BSDF struct (clears to zeroes) */
158     extern void SDclearBSDF(SDData *sd);
159    
160     /* Load a BSDF struct from the given file (keeps name unchanged) */
161     extern SDError SDloadFile(SDData *sd, const char *fname);
162    
163     /* Free data associated with BSDF struct */
164     extern void SDfreeBSDF(SDData *sd);
165    
166     /* Find writeable BSDF by name, or allocate new cache entry if absent */
167     extern SDData *SDgetCache(const char *bname);
168    
169     /* Free cached cumulative distributions for BSDF component */
170     extern void SDfreeCumulativeCache(SDSpectralDF *df);
171    
172     /* Sample an individual BSDF component */
173     extern SDError SDsampComponent(SDValue *sv, FVECT outVec,
174     const FVECT inVec, double randX,
175     SDComponent *sdc);
176    
177     /* Convert 1-dimensional random variable to N-dimensional */
178     extern void SDmultiSamp(double t[], int n, double randX);
179    
180     /* Map a [0,1]^2 square to a unit radius disk */
181     void SDsquare2disk(double ds[2], double seedx, double seedy);
182    
183     /* Map point on unit disk to a unit square in [0,1]^2 range */
184     void SDdisk2square(double sq[2], double diskx, double disky);
185    
186     /*****************************************************************
187     * The calls below are the ones most applications require.
188     * All directions are assumed to be unit vectors.
189     */
190    
191     /* Get BSDF from cache (or load and cache it on first call) */
192     /* Report any problems to stderr and return NULL on failure */
193     extern const SDData *SDcacheFile(const char *fname);
194    
195     /* Free a BSDF from our cache (clear all if NULL) */
196     extern void SDfreeCache(const SDData *sd);
197    
198     /* Query projected solid angle resolution for non-diffuse BSDF direction */
199     extern SDError SDsizeBSDF(double *projSA, const FVECT vec,
200     int qflags, const SDData *sd);
201    
202     /* Return BSDF for the given incident and scattered ray vectors */
203     extern SDError SDevalBSDF(SDValue *sv, const FVECT outVec,
204     const FVECT inVec, const SDData *sd);
205    
206     /* Compute directional hemispherical scattering at given incident angle */
207     extern double SDdirectHemi(const FVECT inVec,
208     int sflags, const SDData *sd);
209    
210     /* Sample BSDF direction based on the given random variable */
211     extern SDError SDsampBSDF(SDValue *sv, FVECT outVec,
212     const FVECT inVec, double randX,
213     int sflags, const SDData *sd);
214    
215     /*****************************************************************
216     * Vector math for getting between world and local BSDF coordinates.
217     * Directions may be passed unnormalized to these routines.
218     */
219    
220     /* Compute World->BSDF transform from surface normal and up (Y) vector */
221     extern SDError SDcompXform(RREAL vMtx[3][3], const FVECT sNrm,
222     const FVECT uVec);
223    
224     /* Compute inverse transform */
225     extern SDError SDinvXform(RREAL iMtx[3][3], RREAL vMtx[3][3]);
226    
227     /* Transform and normalize direction (column) vector */
228     extern SDError SDmapDir(FVECT resVec, RREAL vMtx[3][3],
229     const FVECT inpVec);
230    
231 greg 2.5 /* System-specific BSDF loading routine (not part of our library) */
232     extern SDData *loadBSDF(char *name);
233    
234     /* System-specific BSDF error translator (not part of our library) */
235     extern char *transSDError(SDError ec);
236    
237 greg 2.4 /*################################################################*/
238     /*######### DEPRECATED DEFINITIONS AWAITING PERMANENT REMOVAL #######*/
239 greg 2.1 /*
240     * Header for BSDF i/o and access routines
241     */
242 greg 2.2
243 greg 2.4 #include "mat4.h"
244 greg 2.1 /* up directions */
245     typedef enum {
246     UDzneg=-3,
247     UDyneg=-2,
248     UDxneg=-1,
249     UDunknown=0,
250     UDxpos=1,
251     UDypos=2,
252     UDzpos=3
253     } UpDir;
254     /* BSDF coordinate calculation routines */
255     /* vectors always point away from surface */
256 greg 2.4
257     typedef int b_vecf2(FVECT v, int n, void *cd);
258     typedef int b_ndxf2(FVECT v, void *cd);
259     typedef double b_radf2(int n, void *cd);
260 greg 2.1
261     /* Bidirectional Scattering Distribution Function */
262     struct BSDF_data {
263     int ninc; /* number of incoming directions */
264     int nout; /* number of outgoing directions */
265 greg 2.3 float dim[3]; /* width, height, thickness (meters) */
266     char *mgf; /* geometric description (if any) */
267 greg 2.1 void *ib_priv; /* input basis private data */
268 greg 2.4 b_vecf2 *ib_vec; /* get input vector from index */
269     b_ndxf2 *ib_ndx; /* get input index from vector */
270     b_radf2 *ib_ohm; /* get input radius for index */
271 greg 2.1 void *ob_priv; /* output basis private data */
272 greg 2.4 b_vecf2 *ob_vec; /* get output vector from index */
273     b_ndxf2 *ob_ndx; /* get output index from vector */
274     b_radf2 *ob_ohm; /* get output radius for index */
275 greg 2.1 float *bsdf; /* scattering distribution data */
276     }; /* bidirectional scattering distrib. func. */
277    
278     #define getBSDF_incvec(v,b,i) (*(b)->ib_vec)(v,i,(b)->ib_priv)
279     #define getBSDF_incndx(b,v) (*(b)->ib_ndx)(v,(b)->ib_priv)
280     #define getBSDF_incohm(b,i) (*(b)->ib_ohm)(i,(b)->ib_priv)
281     #define getBSDF_outvec(v,b,o) (*(b)->ob_vec)(v,o,(b)->ob_priv)
282     #define getBSDF_outndx(b,v) (*(b)->ob_ndx)(v,(b)->ob_priv)
283     #define getBSDF_outohm(b,o) (*(b)->ob_ohm)(o,(b)->ob_priv)
284     #define BSDF_value(b,i,o) (b)->bsdf[(o)*(b)->ninc + (i)]
285    
286     extern struct BSDF_data *load_BSDF(char *fname);
287     extern void free_BSDF(struct BSDF_data *b);
288     extern int r_BSDF_incvec(FVECT v, struct BSDF_data *b, int i,
289     double rv, MAT4 xm);
290     extern int r_BSDF_outvec(FVECT v, struct BSDF_data *b, int o,
291     double rv, MAT4 xm);
292 greg 2.3 extern int getBSDF_xfm(MAT4 xm, FVECT nrm, UpDir ud, char *xfbuf);
293 greg 2.2
294 greg 2.4 /*######### END DEPRECATED DEFINITIONS #######*/
295     /*################################################################*/
296    
297     #ifdef __cplusplus
298     }
299     #endif
300     #endif /* ! _BSDF_H_ */