src/rt/pmapdata.h

/* 
   ==================================================================
   Photon map data structures and kd-tree handling   

   Roland Schregle (roland.schregle@{hslu.ch, gmail.com})
   (c) Fraunhofer Institute for Solar Energy Systems,
       Lucerne University of Applied Sciences & Arts   
   ==================================================================
   
   $Id: pmapdata.h,v 4.20 2015/01/30 19:08:50 taschreg Exp taschreg $
*/


#ifndef PMAPDATA_H
   #define PMAPDATA_H

   #include "ray.h"   
   #include "pmaptype.h"
   #include "lookup.h"


   /* Define PMAP_FLOAT_FLUX to store photon flux as floats instead of
    * compact RGBE, which was found to improve accuracy in analytical
    * validation. */
   #ifdef PMAP_FLOAT_FLUX
      #define setPhotonFlux(p,f) copycolor((p) -> flux, f)
      #define getPhotonFlux(p,f) copycolor(f, (p) -> flux)
   #else
      #define setPhotonFlux(p,f) setcolr((p)->flux, (f)[0], (f)[1], (f)[2])
      #define getPhotonFlux(p,f) colr_color(f, (p) -> flux)
   #endif


   /* Primary photon ray for light source contributions */
   typedef struct {
      short srcIdx;               /* Index of emitting light source */
      float dir [3], org [3];     /* Incident dir & origin on source */
   } PhotonPrimary;
      
   #define photonSrcIdx(pm, p) ((pm) -> primary [(p) -> primary].srcIdx)

   
   typedef struct {
      float pos [3];                 /* Photon position */
      signed char norm [3];          /* Surface normal at pos (incident
                                        direction for volume photons) */
      char flags;                    /* Bit 0-1: kd-tree discriminator axis,
                                        Bit 2:   caustic photon */
      #ifdef PMAP_FLOAT_FLUX
         COLOR flux;
      #else
         COLR flux;                  /* Photon flux */
      #endif

      unsigned primary;              /* Index to primary ray */
   } Photon;
   
   /* Photon flag bitmasks and manipulation macros */
   #define PMAP_DISCR_BIT 3
   #define PMAP_CAUST_BIT 4
   #define photonDiscr(p)       ((p).flags & PMAP_DISCR_BIT)
   #define setPhotonDiscr(p, d) ((p).flags = ((p).flags & ~PMAP_DISCR_BIT) | \
                                              ((d) & PMAP_DISCR_BIT))

   /* Photon map type tests */
   #define isGlobalPmap(p)    ((p) -> type == PMAP_TYPE_GLOBAL)
   #define isCausticPmap(p)   ((p) -> type == PMAP_TYPE_CAUSTIC)
   #define isContribPmap(p)   ((p) -> type == PMAP_TYPE_CONTRIB)
   #define isVolumePmap(p)    ((p) -> type == PMAP_TYPE_VOLUME)

   
   /* Queue node for photon lookups */
   typedef struct {                  
      Photon *photon;
      float dist;
   } PhotonSQNode;

   /* Bias compensation history node */
   typedef struct {                  
      COLOR irrad;
      float weight;
   } PhotonBCNode;


   struct PhotonMap;                 /* Forward declarations */

   typedef struct PhotonMap {
      PhotonMapType type;            /* See pmaptype.h */
      char *fileName;                /* Photon map file */
      Photon *heap;                  /* Photon k-d tree as linear array */
      PhotonSQNode *squeue;          /* Search queue */
      PhotonBCNode *biasCompHist;    /* Bias compensation history */      
      char lookupFlags;              /* Flags passed to findPhotons() */
      
      unsigned long distribTarget,   /* Num stored specified by user */
                    heapSize,
                    heapSizeInc, 
                    heapEnd,         /* Num actually stored in heap */
                    numDensity,      /* Num density estimates */
                    totalGathered,   /* Total photons gathered */
                    numLookups,      /* Counters for short photon lookups */
                    numShortLookups;
                    
      unsigned minGather,            /* Specified min/max photons per */
               maxGather,            /* density estimate */
               squeueSize,
               squeueEnd,
               minGathered,          /* Min/max photons actually gathered */
               maxGathered,          /* per density estimate */
               shortLookupPct;       /* Percentage of short lookups (for
                                        statistics output */
               
                                     /* NOTE: All distances are SQUARED */
      float maxDist,                 /* Max search radius during NN search */
            maxDist0,                /* Initial value for above */
            maxDistLimit,            /* Hard limit for above */
            CoGdist,                 /* Avg distance to centre of gravity */
            maxPos [3], minPos [3],  /* Max & min photon positions */
            distribRatio,            /* Probability of photon storage */
            gatherTolerance,         /* Fractional deviation from minGather/
                                        maxGather for short lookup */
            minError, maxError,      /* Min/max/rms density estimate error */
            rmsError;
            
      FVECT CoG;                     /* Centre of gravity (avg photon pos) */
      COLOR photonFlux;              /* Average photon flux */
      unsigned short randState [3];  /* Local RNG state */
      
      void (*lookup)(struct PhotonMap*, RAY*, COLOR);   
                                     /* Callback for type-specific photon
                                      * lookup (usually density estimate) */

      PhotonPrimary *primary;        /* Primary photon rays & associated
                                        counters */
      unsigned primarySize, primaryEnd;
               
      LUTAB *srcContrib;             /* lookup table for source contribs */
   } PhotonMap;


   /* Photon maps by type (see PhotonMapType) */
   extern PhotonMap *photonMaps [];

   /* Macros for specific photon map types */
   #define globalPmap            (photonMaps [PMAP_TYPE_GLOBAL])
   #define preCompPmap           (photonMaps [PMAP_TYPE_PRECOMP])
   #define causticPmap           (photonMaps [PMAP_TYPE_CAUSTIC])
   #define volumePmap            (photonMaps [PMAP_TYPE_VOLUME])
   #define directPmap            (photonMaps [PMAP_TYPE_DIRECT])
   #define contribPmap           (photonMaps [PMAP_TYPE_CONTRIB])


   void initPhotonMap (PhotonMap *pmap, PhotonMapType t);
   /* Initialise empty photon map of specified type */

   const PhotonPrimary* addPhotonPrimary (PhotonMap *pmap, const RAY *ray);
   /* Add primary ray for emitted photon and save light source index, origin
    * on source, and emitted direction; used by contrib photons */

   const Photon* addPhoton (PhotonMap *pmap, const RAY *ray);
   /* Create new photon with ray's direction, intersection point, and flux,
      and add to photon map subject to acceptance probability pmap ->
      distribRatio for global density control; if the photon is rejected,
      NULL is returned. The flux is scaled by ray -> rweight and
      1 / pmap -> distribRatio. */

   void balancePhotons (PhotonMap *pmap, double *photonFlux);
   /* Build a balanced kd-tree as heap to guarantee logarithmic search
    * times. This must be called prior to performing photon search with
    * findPhotons(). 
    * PhotonFlux is the flux scaling factor per photon averaged over RGB. In
    * the case of a contribution photon map, this is an array with a
    * separate factor specific to each light source due to non-uniform
    * photon emission; Otherwise it is referenced as a scalar value. Flux is
    * not scaled if photonFlux == NULL. */

   void buildHeap (Photon *heap, unsigned long *heapIdx,
                   unsigned long *heapXdi, const float min [3], 
                   const float max [3], unsigned long left, 
                   unsigned long right, unsigned long root);
   /* Recursive part of balancePhotons(..); builds heap from subarray
    * defined by indices left and right. */
      
   void findPhotons (PhotonMap* pmap, const RAY *ray);
   /* Find pmap -> squeueSize closest photons to ray -> rop with similar 
      normal. For volume photons ray -> rorg is used and the normal is 
      ignored (being the incident direction in this case). Found photons 
      are placed in pmap -> squeue, with pmap -> squeueEnd being the number
      actually found. */

   Photon *find1Photon (PhotonMap *pmap, const RAY *ray);
   /* Finds single closest photon to ray -> rop with similar normal. 
      Returns NULL if none found. */

   void deletePhotons (PhotonMap*);
   /* Free dem mammaries... */

#endif
Revision:	2.1
Committed:	Tue Feb 24 19:39:26 2015 UTC (10 years, 2 months ago) by greg
Content type:	text/plain
Branch:	MAIN
Log Message:	Initial check-in of photon map addition by Roland Schregle
#	User	Rev	Content
1	greg	2.1	/*
2			==================================================================
3			Photon map data structures and kd-tree handling
4
5			Roland Schregle (roland.schregle@{hslu.ch, gmail.com})
6			(c) Fraunhofer Institute for Solar Energy Systems,
7			Lucerne University of Applied Sciences & Arts
8			==================================================================
9
10			$Id: pmapdata.h,v 4.20 2015/01/30 19:08:50 taschreg Exp taschreg $
11			*/
12
13
14			#ifndef PMAPDATA_H
15			#define PMAPDATA_H
16
17			#include "ray.h"
18			#include "pmaptype.h"
19			#include "lookup.h"
20
21
22			/* Define PMAP_FLOAT_FLUX to store photon flux as floats instead of
23			* compact RGBE, which was found to improve accuracy in analytical
24			* validation. */
25			#ifdef PMAP_FLOAT_FLUX
26			#define setPhotonFlux(p,f) copycolor((p) -> flux, f)
27			#define getPhotonFlux(p,f) copycolor(f, (p) -> flux)
28			#else
29			#define setPhotonFlux(p,f) setcolr((p)->flux, (f)[0], (f)[1], (f)[2])
30			#define getPhotonFlux(p,f) colr_color(f, (p) -> flux)
31			#endif
32
33
34			/* Primary photon ray for light source contributions */
35			typedef struct {
36			short srcIdx; /* Index of emitting light source */
37			float dir [3], org [3]; /* Incident dir & origin on source */
38			} PhotonPrimary;
39
40			#define photonSrcIdx(pm, p) ((pm) -> primary [(p) -> primary].srcIdx)
41
42
43			typedef struct {
44			float pos [3]; /* Photon position */
45			signed char norm [3]; /* Surface normal at pos (incident
46			direction for volume photons) */
47			char flags; /* Bit 0-1: kd-tree discriminator axis,
48			Bit 2: caustic photon */
49			#ifdef PMAP_FLOAT_FLUX
50			COLOR flux;
51			#else
52			COLR flux; /* Photon flux */
53			#endif
54
55			unsigned primary; /* Index to primary ray */
56			} Photon;
57
58			/* Photon flag bitmasks and manipulation macros */
59			#define PMAP_DISCR_BIT 3
60			#define PMAP_CAUST_BIT 4
61			#define photonDiscr(p) ((p).flags & PMAP_DISCR_BIT)
62			#define setPhotonDiscr(p, d) ((p).flags = ((p).flags & ~PMAP_DISCR_BIT) \| \
63			((d) & PMAP_DISCR_BIT))
64
65			/* Photon map type tests */
66			#define isGlobalPmap(p) ((p) -> type == PMAP_TYPE_GLOBAL)
67			#define isCausticPmap(p) ((p) -> type == PMAP_TYPE_CAUSTIC)
68			#define isContribPmap(p) ((p) -> type == PMAP_TYPE_CONTRIB)
69			#define isVolumePmap(p) ((p) -> type == PMAP_TYPE_VOLUME)
70
71
72			/* Queue node for photon lookups */
73			typedef struct {
74			Photon *photon;
75			float dist;
76			} PhotonSQNode;
77
78			/* Bias compensation history node */
79			typedef struct {
80			COLOR irrad;
81			float weight;
82			} PhotonBCNode;
83
84
85			struct PhotonMap; /* Forward declarations */
86
87			typedef struct PhotonMap {
88			PhotonMapType type; /* See pmaptype.h */
89			char fileName; / Photon map file */
90			Photon heap; / Photon k-d tree as linear array */
91			PhotonSQNode squeue; / Search queue */
92			PhotonBCNode biasCompHist; / Bias compensation history */
93			char lookupFlags; /* Flags passed to findPhotons() */
94
95			unsigned long distribTarget, /* Num stored specified by user */
96			heapSize,
97			heapSizeInc,
98			heapEnd, /* Num actually stored in heap */
99			numDensity, /* Num density estimates */
100			totalGathered, /* Total photons gathered */
101			numLookups, /* Counters for short photon lookups */
102			numShortLookups;
103
104			unsigned minGather, /* Specified min/max photons per */
105			maxGather, /* density estimate */
106			squeueSize,
107			squeueEnd,
108			minGathered, /* Min/max photons actually gathered */
109			maxGathered, /* per density estimate */
110			shortLookupPct; /* Percentage of short lookups (for
111			statistics output */
112
113			/* NOTE: All distances are SQUARED */
114			float maxDist, /* Max search radius during NN search */
115			maxDist0, /* Initial value for above */
116			maxDistLimit, /* Hard limit for above */
117			CoGdist, /* Avg distance to centre of gravity */
118			maxPos [3], minPos [3], /* Max & min photon positions */
119			distribRatio, /* Probability of photon storage */
120			gatherTolerance, /* Fractional deviation from minGather/
121			maxGather for short lookup */
122			minError, maxError, /* Min/max/rms density estimate error */
123			rmsError;
124
125			FVECT CoG; /* Centre of gravity (avg photon pos) */
126			COLOR photonFlux; /* Average photon flux */
127			unsigned short randState [3]; /* Local RNG state */
128
129			void (lookup)(struct PhotonMap, RAY*, COLOR);
130			/* Callback for type-specific photon
131			* lookup (usually density estimate) */
132
133			PhotonPrimary primary; / Primary photon rays & associated
134			counters */
135			unsigned primarySize, primaryEnd;
136
137			LUTAB srcContrib; / lookup table for source contribs */
138			} PhotonMap;
139
140
141
142			/* Photon maps by type (see PhotonMapType) */
143			extern PhotonMap *photonMaps [];
144
145			/* Macros for specific photon map types */
146			#define globalPmap (photonMaps [PMAP_TYPE_GLOBAL])
147			#define preCompPmap (photonMaps [PMAP_TYPE_PRECOMP])
148			#define causticPmap (photonMaps [PMAP_TYPE_CAUSTIC])
149			#define volumePmap (photonMaps [PMAP_TYPE_VOLUME])
150			#define directPmap (photonMaps [PMAP_TYPE_DIRECT])
151			#define contribPmap (photonMaps [PMAP_TYPE_CONTRIB])
152
153
154
155			void initPhotonMap (PhotonMap *pmap, PhotonMapType t);
156			/* Initialise empty photon map of specified type */
157
158			const PhotonPrimary* addPhotonPrimary (PhotonMap pmap, const RAY ray);
159			/* Add primary ray for emitted photon and save light source index, origin
160			* on source, and emitted direction; used by contrib photons */
161
162			const Photon* addPhoton (PhotonMap pmap, const RAY ray);
163			/* Create new photon with ray's direction, intersection point, and flux,
164			and add to photon map subject to acceptance probability pmap ->
165			distribRatio for global density control; if the photon is rejected,
166			NULL is returned. The flux is scaled by ray -> rweight and
167			1 / pmap -> distribRatio. */
168
169			void balancePhotons (PhotonMap pmap, double photonFlux);
170			/* Build a balanced kd-tree as heap to guarantee logarithmic search
171			* times. This must be called prior to performing photon search with
172			* findPhotons().
173			* PhotonFlux is the flux scaling factor per photon averaged over RGB. In
174			* the case of a contribution photon map, this is an array with a
175			* separate factor specific to each light source due to non-uniform
176			* photon emission; Otherwise it is referenced as a scalar value. Flux is
177			* not scaled if photonFlux == NULL. */
178
179			void buildHeap (Photon heap, unsigned long heapIdx,
180			unsigned long *heapXdi, const float min [3],
181			const float max [3], unsigned long left,
182			unsigned long right, unsigned long root);
183			/* Recursive part of balancePhotons(..); builds heap from subarray
184			* defined by indices left and right. */
185
186			void findPhotons (PhotonMap* pmap, const RAY *ray);
187			/* Find pmap -> squeueSize closest photons to ray -> rop with similar
188			normal. For volume photons ray -> rorg is used and the normal is
189			ignored (being the incident direction in this case). Found photons
190			are placed in pmap -> squeue, with pmap -> squeueEnd being the number
191			actually found. */
192
193			Photon find1Photon (PhotonMap pmap, const RAY *ray);
194			/* Finds single closest photon to ray -> rop with similar normal.
195			Returns NULL if none found. */
196
197			void deletePhotons (PhotonMap*);
198			/* Free dem mammaries... */
199
200			#endif