src/common/bsdf.h

/* RCSid $Id: bsdf.h,v 2.30 2021/12/13 21:05:00 greg Exp $ */
/*
 *  bsdf.h
 *  
 *  Declarations for bidirectional scattering distribution functions.
 *
 *  A material is oriented in right-hand coordinate system with X-axis
 *      in the surface plane pointed to the right as seen from the front.
 *      This means the Y-axis is "up" and the Z-axis is the surface normal.
 *
 *  Note that we reverse the identification of "front" and "back" from
 *      the conventions used in WINDOW 6.  "Front" in our library points
 *      in the +Z direction, towards the interior of the space rather
 *      than the exterior.
 *
 *  BSDF incident & exiting vectors are always oriented away from surface.
 *
 *  Created by Greg Ward on 1/10/11.
 *
 */

#ifndef _BSDF_H_
#define _BSDF_H_

#include "platform.h"
#include "fvect.h"
#include "ccolor.h"

#ifdef __cplusplus
extern "C" {
#endif

#define SDnameLn        128             /* maximum BSDF name length */
#define SDmaxCh         3               /* maximum # spectral channels */

/* Component flags for SDsampBSDF() and SDdirectHemi() */
#define SDsampR         0x1             /* include reflection */
#define SDsampT         0x2             /* include transmission */
#define SDsampS         0x3             /* include scattering (R+T) */
#define SDsampSp        0x4             /* include non-diffuse portion */
#define SDsampDf        0x8             /* include diffuse portion */
#define SDsampSpR       0x5             /* include non-diffuse reflection */
#define SDsampSpT       0x6             /* include non-diffuse transmission */
#define SDsampSpS       0x7             /* include non-diffuse scattering */
#define SDsampAll       0xF             /* include everything */

/* Projected solid angle query flags for SDsizeBSDF() */
#define SDqueryVal      0x0             /* query single value */
#define SDqueryMin      0x1             /* query minimum proj. solid angle */
#define SDqueryMax      0x2             /* query maximum proj. solid angle */

/* Error codes: normal return, out of memory, file i/o, file format, bad argument,
                 bad data, unsupported feature, internal error, unknown error */
typedef enum {SDEnone=0, SDEmemory, SDEfile, SDEformat, SDEargument,
                SDEdata, SDEsupport, SDEinternal, SDEunknown} SDError;

/* English strings corresponding to ennumerated errors */
extern const char       *SDerrorEnglish[];

/* Pointer to error list in preferred language */
extern const char       **SDerrorList;

/* Additional information on last error (generally in English) */
extern char             SDerrorDetail[];

/* Holder for BSDF value and spectral color */
typedef struct {
        double          cieY;           /* photopic BSDF (Y) value */
        C_COLOR         spec;           /* spectral and (x,y) color */
} SDValue;

/* Cached, encoded, cumulative distribution for one incident (solid) angle */
#define SD_CDIST_BASE(styp)     double          cTotal; \
                                struct styp     *next
typedef struct SDCDst_s {
        SD_CDIST_BASE(SDCDst_s);        /* base fields first */
        /* ...encoded distribution extends struct */
} SDCDst;

extern const SDCDst     SDemptyCD;      /* empty distribution */

/* Forward declaration of BSDF component */
typedef struct SDComp_s SDComponent;

/* Methods needed to handle BSDF components (nothing is optional) */
typedef struct {
                                        /* return non-diffuse BSDF */
        int             (*getBSDFs)(float coef[SDmaxCh], const FVECT inVec,
                                    const FVECT outVec, SDComponent *sdc);
                                        /* query non-diffuse PSA for vector */
        SDError         (*queryProjSA)(double *psa, const FVECT v1,
                                                const RREAL *v2, int qflags,
                                                SDComponent *sdc);
                                        /* get cumulative distribution */
        const SDCDst    *(*getCDist)(const FVECT inVec, SDComponent *sdc);
                                        /* sample cumulative distribution */
        SDError         (*sampCDist)(FVECT ioVec, double randX,
                                                const SDCDst *cdp);
                                        /* free a spectral BSDF component */
        void            (*freeSC)(void *dist);
} SDFunc;

/* Structure to hold a spectral BSDF component (typedef SDComponent above) */
struct SDComp_s {
        C_COLOR         cspec[SDmaxCh]; /* component spectral bases */
        const SDFunc    *func;          /* methods for this component */
        void            *dist;          /* loaded distribution data */
        SDCDst          *cdList;        /* cumulative distribution cache */
};

/* Container for non-diffuse BSDF components */
typedef struct {
        double          minProjSA;      /* minimum projected solid angle */
        double          maxHemi;        /* maximum directional hemispherical */
        int             ncomp;          /* number of separate components */
        SDComponent     comp[1];        /* BSDF components (extends struct) */
} SDSpectralDF;

/* Loaded BSDF data */
typedef struct {
        char            name[SDnameLn]; /* BSDF name (usu. derived from file) */
        char            matn[SDnameLn]; /* material name */
        char            makr[SDnameLn]; /* manufacturer */
        char            *mgf;           /* geometric description (if any) */
        double          dim[3];         /* width, height, thickness (meters) */
        SDValue         rLambFront;     /* diffuse front reflectance */
        SDValue         rLambBack;      /* diffuse rear reflectance */
        SDValue         tLambFront;     /* diffuse front transmittance */
        SDValue         tLambBack;      /* diffuse back transmittance */
        SDSpectralDF    *rf, *rb;       /* non-diffuse BRDF components */
        SDSpectralDF    *tf, *tb;       /* non-diffuse BTDF components */
} SDData;

/* List of loaded BSDFs */
extern struct SDCache_s {
        SDData          bsdf;           /* BSDF data */
        unsigned        refcnt;         /* how many callers are using us? */
        struct SDCache_s                /* next in cache list */
                        *next;
} *SDcacheList;         /* Global BSDF cache */

/* BSDF cache retention policies */
#define SDretainNone    0               /* free unreferenced BSDF data */
#define SDretainBSDFs   1               /* keep loaded BSDFs in memory */
#define SDretainAll     2               /* also keep cumulative cache data */

extern int              SDretainSet;    /* =SDretainNone by default */
extern unsigned long    SDmaxCache;     /* =0 (unlimited) by default */

/*****************************************************************
 * The following routines are less commonly used by applications.
 */

#define SDisLoaded(sd)  ((sd)->rLambFront.spec.flags != 0)

/* Report an error to the indicated stream */
extern SDError          SDreportError(SDError ec, FILE *fp);

/* Shorten file path to useable BSDF name, removing suffix */
extern void             SDclipName(char res[SDnameLn], const char *fname);

/* Allocate new spectral distribution function */
extern SDSpectralDF     *SDnewSpectralDF(int nc);

/* Add component(s) to spectral distribution function */
extern SDSpectralDF     *SDaddComponent(SDSpectralDF *odf, int nadd);

/* Free a spectral distribution function */
extern void             SDfreeSpectralDF(SDSpectralDF *df);

/* Initialize an unused BSDF struct and assign name (calls SDclipName) */
extern void             SDclearBSDF(SDData *sd, const char *fname);

/* Load a BSDF struct from the given file (keeps name unchanged) */
extern SDError          SDloadFile(SDData *sd, const char *fname);

/* Free data associated with BSDF struct */
extern void             SDfreeBSDF(SDData *sd);

/* Find writeable BSDF by name, or allocate new cache entry if absent */
extern SDData           *SDgetCache(const char *bname);

/* Free cached cumulative distributions for BSDF component */
extern void             SDfreeCumulativeCache(SDSpectralDF *df);

/* Sample an individual BSDF component */
extern SDError          SDsampComponent(SDValue *sv, FVECT ioVec,
                                        double randX, SDComponent *sdc);

/* Convert 1-dimensional random variable to N-dimensional */
extern void             SDmultiSamp(double t[], int n, double randX);

/*****************************************************************
 * The calls below are the ones most applications require.
 * All directions are assumed to be unit vectors.
 */

/* Get BSDF from cache (or load and cache it on first call) */
/* Report any problems to stderr, return NULL on failure */
extern const SDData     *SDcacheFile(const char *fname);

/* Free a BSDF from our cache (clear all if sd==NULL) */
extern void             SDfreeCache(const SDData *sd);

/* Query projected solid angle resolution for non-diffuse BSDF direction(s) */
extern SDError          SDsizeBSDF(double *projSA, const FVECT v1,
                                        const RREAL *v2, int qflags,
                                        const SDData *sd);

/* Return BSDF for the given incident and scattered ray vectors */
extern SDError          SDevalBSDF(SDValue *sv, const FVECT inVec,
                                        const FVECT outVec, const SDData *sd);

/* Compute directional hemispherical scattering at given incident angle */
extern double           SDdirectHemi(const FVECT inVec,
                                        int sflags, const SDData *sd);

/* Sample BSDF direction based on the given random variable */
extern SDError          SDsampBSDF(SDValue *sv, FVECT ioVec, double randX,
                                        int sflags, const SDData *sd);

/*****************************************************************
 * Vector math for getting between world and local BSDF coordinates.
 * Directions may be passed unnormalized to these routines.
 */

/* Compute World->BSDF transform from surface normal and BSDF up vector */
extern SDError          SDcompXform(RREAL vMtx[3][3], const FVECT sNrm,
                                        const FVECT uVec);

/* Compute inverse transform */
extern SDError          SDinvXform(RREAL iMtx[3][3], RREAL vMtx[3][3]);

/* Transform and normalize direction (column) vector */
extern SDError          SDmapDir(FVECT resVec, RREAL vMtx[3][3],
                                        const FVECT inpVec);

/* Application-specific BSDF loading routine (not part of our library) */
extern SDData           *loadBSDF(char *name);

/* Application-specific BSDF error translator (not part of our library) */
extern char             *transSDError(SDError ec);

#ifdef __cplusplus
}
#endif
#endif  /* ! _BSDF_H_ */
Revision:	2.31
Committed:	Sat Jun 7 05:09:45 2025 UTC (6 days, 20 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"
#	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_ */