ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/common/bsdf.h
Revision: 2.31
Committed: Sat Jun 7 05:09:45 2025 UTC (4 days, 10 hours ago) by greg
Content type: text/plain
Branch: MAIN
CVS Tags: HEAD
Changes since 2.30: +2 -3 lines
Log Message:
refactor: Put some declarations into "paths.h" and included in "platform.h"

File Contents

# User Rev Content
1 greg 2.31 /* RCSid $Id: bsdf.h,v 2.30 2021/12/13 21:05:00 greg Exp $ */
2 greg 2.4 /*
3     * bsdf.h
4     *
5     * Declarations for bidirectional scattering distribution functions.
6     *
7     * A material is oriented in right-hand coordinate system with X-axis
8     * in the surface plane pointed to the right as seen from the front.
9     * This means the Y-axis is "up" and the Z-axis is the surface normal.
10     *
11 greg 2.8 * Note that we reverse the identification of "front" and "back" from
12     * the conventions used in WINDOW 6. "Front" in our library points
13     * in the +Z direction, towards the interior of the space rather
14     * than the exterior.
15     *
16 greg 2.13 * BSDF incident & exiting vectors are always oriented away from surface.
17 greg 2.4 *
18     * Created by Greg Ward on 1/10/11.
19     *
20     */
21    
22     #ifndef _BSDF_H_
23     #define _BSDF_H_
24    
25 greg 2.31 #include "platform.h"
26 greg 2.4 #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 greg 2.22 /* English strings corresponding to ennumerated errors */
58 greg 2.4 extern const char *SDerrorEnglish[];
59    
60 greg 2.22 /* Pointer to error list in preferred language */
61     extern const char **SDerrorList;
62    
63     /* Additional information on last error (generally in English) */
64 greg 2.4 extern char SDerrorDetail[];
65    
66     /* Holder for BSDF value and spectral color */
67     typedef struct {
68     double cieY; /* photopic BSDF (Y) value */
69     C_COLOR spec; /* spectral and (x,y) color */
70     } SDValue;
71    
72     /* Cached, encoded, cumulative distribution for one incident (solid) angle */
73 greg 2.16 #define SD_CDIST_BASE(styp) double cTotal; \
74     struct styp *next
75 greg 2.4 typedef struct SDCDst_s {
76 greg 2.16 SD_CDIST_BASE(SDCDst_s); /* base fields first */
77 greg 2.4 /* ...encoded distribution extends struct */
78     } SDCDst;
79    
80 greg 2.19 extern const SDCDst SDemptyCD; /* empty distribution */
81    
82 greg 2.4 /* Forward declaration of BSDF component */
83     typedef struct SDComp_s SDComponent;
84    
85     /* Methods needed to handle BSDF components (nothing is optional) */
86 schorsch 2.25 typedef struct {
87 greg 2.4 /* return non-diffuse BSDF */
88 greg 2.29 int (*getBSDFs)(float coef[SDmaxCh], const FVECT inVec,
89     const FVECT outVec, SDComponent *sdc);
90 greg 2.4 /* query non-diffuse PSA for vector */
91 greg 2.11 SDError (*queryProjSA)(double *psa, const FVECT v1,
92     const RREAL *v2, int qflags,
93 greg 2.12 SDComponent *sdc);
94 greg 2.4 /* get cumulative distribution */
95     const SDCDst *(*getCDist)(const FVECT inVec, SDComponent *sdc);
96     /* sample cumulative distribution */
97 greg 2.12 SDError (*sampCDist)(FVECT ioVec, double randX,
98 greg 2.4 const SDCDst *cdp);
99     /* free a spectral BSDF component */
100     void (*freeSC)(void *dist);
101     } SDFunc;
102    
103     /* Structure to hold a spectral BSDF component (typedef SDComponent above) */
104     struct SDComp_s {
105     C_COLOR cspec[SDmaxCh]; /* component spectral bases */
106 greg 2.26 const SDFunc *func; /* methods for this component */
107 greg 2.4 void *dist; /* loaded distribution data */
108     SDCDst *cdList; /* cumulative distribution cache */
109     };
110    
111     /* Container for non-diffuse BSDF components */
112     typedef struct {
113     double minProjSA; /* minimum projected solid angle */
114     double maxHemi; /* maximum directional hemispherical */
115     int ncomp; /* number of separate components */
116     SDComponent comp[1]; /* BSDF components (extends struct) */
117     } SDSpectralDF;
118    
119     /* Loaded BSDF data */
120     typedef struct {
121 greg 2.13 char name[SDnameLn]; /* BSDF name (usu. derived from file) */
122 greg 2.18 char matn[SDnameLn]; /* material name */
123     char makr[SDnameLn]; /* manufacturer */
124 greg 2.4 char *mgf; /* geometric description (if any) */
125 greg 2.23 double dim[3]; /* width, height, thickness (meters) */
126 greg 2.4 SDValue rLambFront; /* diffuse front reflectance */
127     SDValue rLambBack; /* diffuse rear reflectance */
128 greg 2.28 SDValue tLambFront; /* diffuse front transmittance */
129     SDValue tLambBack; /* diffuse back transmittance */
130 greg 2.19 SDSpectralDF *rf, *rb; /* non-diffuse BRDF components */
131     SDSpectralDF *tf, *tb; /* non-diffuse BTDF components */
132 greg 2.4 } SDData;
133    
134     /* List of loaded BSDFs */
135     extern struct SDCache_s {
136     SDData bsdf; /* BSDF data */
137     unsigned refcnt; /* how many callers are using us? */
138     struct SDCache_s /* next in cache list */
139     *next;
140     } *SDcacheList; /* Global BSDF cache */
141    
142 greg 2.14 /* BSDF cache retention policies */
143     #define SDretainNone 0 /* free unreferenced BSDF data */
144     #define SDretainBSDFs 1 /* keep loaded BSDFs in memory */
145 greg 2.4 #define SDretainAll 2 /* also keep cumulative cache data */
146    
147 greg 2.13 extern int SDretainSet; /* =SDretainNone by default */
148 greg 2.27 extern unsigned long SDmaxCache; /* =0 (unlimited) by default */
149 greg 2.4
150     /*****************************************************************
151     * The following routines are less commonly used by applications.
152     */
153    
154 greg 2.6 #define SDisLoaded(sd) ((sd)->rLambFront.spec.flags != 0)
155 greg 2.4
156 greg 2.22 /* Report an error to the indicated stream */
157     extern SDError SDreportError(SDError ec, FILE *fp);
158 greg 2.4
159     /* Shorten file path to useable BSDF name, removing suffix */
160     extern void SDclipName(char res[SDnameLn], const char *fname);
161    
162     /* Allocate new spectral distribution function */
163     extern SDSpectralDF *SDnewSpectralDF(int nc);
164    
165 greg 2.17 /* Add component(s) to spectral distribution function */
166     extern SDSpectralDF *SDaddComponent(SDSpectralDF *odf, int nadd);
167    
168 greg 2.4 /* Free a spectral distribution function */
169     extern void SDfreeSpectralDF(SDSpectralDF *df);
170    
171 greg 2.10 /* Initialize an unused BSDF struct and assign name (calls SDclipName) */
172     extern void SDclearBSDF(SDData *sd, const char *fname);
173 greg 2.4
174     /* Load a BSDF struct from the given file (keeps name unchanged) */
175     extern SDError SDloadFile(SDData *sd, const char *fname);
176    
177     /* Free data associated with BSDF struct */
178     extern void SDfreeBSDF(SDData *sd);
179    
180     /* Find writeable BSDF by name, or allocate new cache entry if absent */
181     extern SDData *SDgetCache(const char *bname);
182    
183     /* Free cached cumulative distributions for BSDF component */
184     extern void SDfreeCumulativeCache(SDSpectralDF *df);
185    
186     /* Sample an individual BSDF component */
187 greg 2.12 extern SDError SDsampComponent(SDValue *sv, FVECT ioVec,
188     double randX, SDComponent *sdc);
189 greg 2.4
190     /* Convert 1-dimensional random variable to N-dimensional */
191     extern void SDmultiSamp(double t[], int n, double randX);
192    
193     /*****************************************************************
194     * The calls below are the ones most applications require.
195     * All directions are assumed to be unit vectors.
196     */
197    
198     /* Get BSDF from cache (or load and cache it on first call) */
199 greg 2.22 /* Report any problems to stderr, return NULL on failure */
200 greg 2.4 extern const SDData *SDcacheFile(const char *fname);
201    
202 greg 2.13 /* Free a BSDF from our cache (clear all if sd==NULL) */
203 greg 2.4 extern void SDfreeCache(const SDData *sd);
204    
205 greg 2.11 /* Query projected solid angle resolution for non-diffuse BSDF direction(s) */
206     extern SDError SDsizeBSDF(double *projSA, const FVECT v1,
207     const RREAL *v2, int qflags,
208     const SDData *sd);
209 greg 2.4
210     /* Return BSDF for the given incident and scattered ray vectors */
211 greg 2.29 extern SDError SDevalBSDF(SDValue *sv, const FVECT inVec,
212     const FVECT outVec, const SDData *sd);
213 greg 2.4
214     /* Compute directional hemispherical scattering at given incident angle */
215     extern double SDdirectHemi(const FVECT inVec,
216     int sflags, const SDData *sd);
217    
218     /* Sample BSDF direction based on the given random variable */
219 greg 2.12 extern SDError SDsampBSDF(SDValue *sv, FVECT ioVec, double randX,
220 greg 2.4 int sflags, const SDData *sd);
221    
222     /*****************************************************************
223     * Vector math for getting between world and local BSDF coordinates.
224     * Directions may be passed unnormalized to these routines.
225     */
226    
227 greg 2.13 /* Compute World->BSDF transform from surface normal and BSDF up vector */
228 greg 2.4 extern SDError SDcompXform(RREAL vMtx[3][3], const FVECT sNrm,
229     const FVECT uVec);
230    
231     /* Compute inverse transform */
232     extern SDError SDinvXform(RREAL iMtx[3][3], RREAL vMtx[3][3]);
233    
234     /* Transform and normalize direction (column) vector */
235     extern SDError SDmapDir(FVECT resVec, RREAL vMtx[3][3],
236     const FVECT inpVec);
237    
238 greg 2.13 /* Application-specific BSDF loading routine (not part of our library) */
239 greg 2.5 extern SDData *loadBSDF(char *name);
240    
241 greg 2.13 /* Application-specific BSDF error translator (not part of our library) */
242 greg 2.5 extern char *transSDError(SDError ec);
243    
244 greg 2.4 #ifdef __cplusplus
245     }
246     #endif
247     #endif /* ! _BSDF_H_ */