src/rt/pmapdata.h

/* RCSid $Id: pmapdata.h,v 4.22.2.7 2016/02/04 20:21:28 taschreg Exp taschreg $ */

/* 
   =========================================================================
   Photon map types and interface to nearest neighbour lookups in underlying
   point cloud data structure.

   The default data structure is an in-core kd-tree (see pmapkdt.{h,c}).
   This can be overriden with the PMAP_OOC compiletime switch, which enables
   an out-of-core octree (see oococt.{h,c}).
   
   Defining PMAP_FLOAT_FLUX stores photon flux as floats rather than packed
   RGBE for greater precision; this may be necessary when the flux differs
   significantly in individual colour channels, e.g. with highly saturated
   colours.

   Roland Schregle (roland.schregle@{hslu.ch, gmail.com})
   (c) Fraunhofer Institute for Solar Energy Systems,
   (c) Lucerne University of Applied Sciences and Arts,
       supported by the Swiss National Science Foundation (SNSF, #147053)
   =========================================================================
   
   $Id: pmapdata.h,v 4.22.2.7 2016/02/04 20:21:28 taschreg Exp taschreg $
*/


#ifndef PMAPDATA_H
   #define PMAPDATA_H

   #include "ray.h"   
   #include "pmaptype.h"
   #include "lookup.h"
   #include <stdint.h>


   /* Primary photon ray for light source contributions */
   typedef struct {
      int16    srcIdx;              /* Index of emitting light source */
                                    /* !!! REDUCED FROM 32 BITS !!! */
      int32    dir;                 /* Encoded ray direction */
#ifdef PMAP_PRIMARYPOS      
      float    pos [3];             /* Hit point */
#endif      
   } PhotonPrimary;
      
   #define photonSrcIdx(pm, p)      ((pm)->primaries[(p)->primary].srcIdx)


   /* Photon primary ray index type and limit */
   typedef  uint32            PhotonPrimaryIdx;      
   #define  PMAP_MAXPRIMARY   UINT32_MAX

   /* Macros for photon's generating subprocess field */
#ifdef PMAP_OOC         
   #define  PMAP_PROCBITS  7
#else            
   #define  PMAP_PROCBITS  5   
#endif
   #define  PMAP_MAXPROC         (1 << PMAP_PROCBITS)
   #define  PMAP_GETRAYPROC(r)   ((r) -> crtype >> 8)
   #define  PMAP_SETRAYPROC(r,p) ((r) -> crtype |= p << 8)

   /* Tolerance for photon normal check during lookups */
   #define  PMAP_NORM_TOL  0.02
   

   typedef struct {
      float                pos [3];       /* Photon position */
      signed char          norm [3];      /* Surface normal at pos (incident
                                             direction for volume photons) */
      union {
         struct {
#ifndef PMAP_OOC
            unsigned char  discr    : 2;  /* kd-tree discriminator axis */
#endif            
            unsigned char  caustic  : 1;  /* Specularly scattered (=caustic) */
            
            /* Photon's generating subprocess index, used for primary ray
             * index linearisation when building contrib pmaps; note this is
             * reduced for kd-tree to accommodate the discriminator field */
            unsigned char  proc  : PMAP_PROCBITS; 
         };
         
         unsigned char     flags;
      };
      
#ifdef PMAP_FLOAT_FLUX
      COLOR                flux;          
#else
      COLR                 flux;          
#endif
      PhotonPrimaryIdx     primary;       /* Index to primary ray */
   } Photon;


   /* 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


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


   /* Forward declaration */
   struct PhotonMap;
   
   
   /* Define search queue and underlying data struct types */
#ifdef PMAP_OOC
   #include "pmapooc.h"
#else
   #include "pmapkdt.h"
#endif


   typedef struct PhotonMap {
      PhotonMapType  type;             /* See pmaptype.h */
      char           *fileName;        /* Photon map file */
      
      
      /* ================================================================
       * PRE/POST-BUILD STORAGE
       * ================================================================ */
      FILE           *heap;            /* Unsorted photon heap prior to
                                          construction of store */
      Photon         *heapBuf;         /* Write buffer for above */
      unsigned long  heapBufLen,       /* Current & max size of heapBuf */
                     heapBufSize;
      PhotonStorage  store;            /* Photon storage in spacee
                                          subdividing data struct */            
       
      /* ================================================================
       * PHOTON DISTRIBUTION STUFF
       * ================================================================ */
      unsigned long  distribTarget,    /* Num stored specified by user */
                     numPhotons;       /* Num actually stored */
      float          distribRatio;     /* Probability of photon storage */
      COLOR          photonFlux;       /* Average photon flux */
      unsigned short randState [3];    /* Local RNG state */


      /* ================================================================
       * PHOTON LOOKUP STUFF 
       * ================================================================ */
      union {                          /* Flags passed to findPhotons() */
         char        lookupCaustic : 1;
         char        lookupFlags;
      };
      
      PhotonSearchQueue squeue;        /* Search queue for photon lookups */
      unsigned       minGather,        /* Specified min/max photons per */
                     maxGather;        /* density estimate */
                                       
                                       /* NOTE: All distances are SQUARED */
      float          maxDist2,         /* Max search radius */
                     maxDist0,         /* Initial value for above */
                     maxDist2Limit,    /* Hard limit for above */
                     gatherTolerance;  /* Fractional deviation from minGather/
                                          maxGather for short lookup */
      void (*lookup)(struct PhotonMap*, 
                     RAY*, COLOR);     /* Callback for type-specific photon
                                        * lookup (usually density estimate) */                                          

                     
      /* ================================================================
       * BIAS COMPENSATION STUFF
       * ================================================================ */      
      PhotonBiasCompNode   *biasCompHist;    /* Bias compensation history */
      

      /* ================================================================
       * STATISTIX
       * ================================================================ */            
      unsigned long  totalGathered,    /* Total photons gathered */
                     numDensity,       /* Num density estimates */
                     numLookups,       /* Counters for short photon lookups */
                     numShortLookups;
                     
      unsigned       minGathered,      /* Min/max photons actually gathered */
                     maxGathered,      /* per density estimate */
                     shortLookupPct;   /* % of short lookups for stats */                                          
                     
      float          minError,         /* Min/max/rms density estimate error */
                     maxError,
                     rmsError,
                     CoGdist,          /* Avg distance to centre of gravity */
                     maxPos [3],       /* Max & min photon positions */
                     minPos [3];
                     
      FVECT          CoG;              /* Centre of gravity (avg photon pos) */
                     
       
      /* ================================================================
       * PHOTON CONTRIB/COEFF STUFF
       * ================================================================ */
      PhotonPrimary  *primaries,    /* Photon primary array for rendering */
                     lastPrimary;   /* Current primary for photon distrib */
      PhotonPrimaryIdx  numPrimary;    /* Number of primary rays */
      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])

   /* 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)

   /* Mean size of heapfile write buffer, in number of photons */
   #define PMAP_HEAPBUFSIZE   1e6
   
   /* Mean idle time between heap locking attempts, in usec */
   #define PMAP_HEAPBUFSLEEP  2e6
   
   /* Shared memory file for parallelised photon distribution */
#if 0   
   #define PMAP_SHMFNAME      "/mkpmap-%d"
#else
   #define PMAP_SHMFNAME      "mkpmapXXXXXX"
#endif      


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

   int newPhoton (PhotonMap *pmap, const RAY *ray);
   /* Create new photon with ray's direction, intersection point, and flux,
      and append to unsorted photon heap pmap -> heap. The photon is
      accepted with probability pmap -> distribRatio for global density
      control; if the photon is rejected, -1 is returned, else 0.  The flux
      is scaled by ray -> rweight and 1 / pmap -> distribRatio. */

   void initPhotonHeap (PhotonMap *pmap);
   /* Open photon heap file */

   void flushPhotonHeap (PhotonMap *pmap);
   /* Flush photon heap buffa pmap -> heapBuf to heap file pmap -> heap;
    * used by newPhoton() and to finalise heap in distribPhotons(). */

   void buildPhotonMap (PhotonMap *pmap, double *photonFlux,
                        PhotonPrimaryIdx *primaryOfs, unsigned nproc);
   /* Postpress unsorted photon heap pmap -> heap and build underlying data
    * structure pmap -> store.  This is prerequisite to photon lookups with
    * findPhotons(). */
    
   /* PhotonFlux is the flux per photon averaged over RGB; this is
    * multiplied with each photon's flux during the postprocess.  In the
    * case of a contribution photon map, this is an array with a separate
    * flux 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.  */

   /* Photon map construction may be parallelised if nproc > 1, if
    * supported. The heap is destroyed on return.  */
    
   /* PrimaryOfs is an array of index offsets for the primaries in pmap ->
    * primaries generated by each of the nproc subprocesses during contrib
    * photon distribution (see distribPhotonContrib()).  These offsets are
    * used to linearise the photon primary indices in the postprocess.  This
    * linearisation is skipped if primaryOfs == NULL.  */

   void findPhotons (PhotonMap* pmap, const RAY *ray);
   /* Find pmap -> squeue.len 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 search queue starting with the furthest photon at pmap ->
      squeue.node, and pmap -> squeue.tail being the number actually found. */

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

   void getPhoton (PhotonMap *pmap, PhotonIdx idx, Photon *photon);
   /* Retrieve photon referenced by idx from pmap -> store */

   Photon *getNearestPhoton (const PhotonSearchQueue *squeue, PhotonIdx idx);
   /* Retrieve photon from NN search queue after calling findPhotons() */
   
   PhotonIdx firstPhoton (const PhotonMap *pmap);
   /* Index to first photon, to be passed to getPhoton(). Indices to
    * subsequent photons can be optained via increment operator (++) */
    
   void deletePhotons (PhotonMap*);
   /* Free dem mammaries... */

#endif
Revision:	2.10
Committed:	Tue May 17 17:39:47 2016 UTC (8 years ago) by rschregle
Content type:	text/plain
Branch:	MAIN
Changes since 2.9:	+253 -140 lines
Log Message:	Initial import of ooC photon map
#	User	Rev	Content
1	rschregle	2.10	/* RCSid $Id: pmapdata.h,v 4.22.2.7 2016/02/04 20:21:28 taschreg Exp taschreg $ */
2
3	greg	2.1	/*
4	rschregle	2.10	=========================================================================
5			Photon map types and interface to nearest neighbour lookups in underlying
6			point cloud data structure.
7
8			The default data structure is an in-core kd-tree (see pmapkdt.{h,c}).
9			This can be overriden with the PMAP_OOC compiletime switch, which enables
10			an out-of-core octree (see oococt.{h,c}).
11
12			Defining PMAP_FLOAT_FLUX stores photon flux as floats rather than packed
13			RGBE for greater precision; this may be necessary when the flux differs
14			significantly in individual colour channels, e.g. with highly saturated
15			colours.
16	greg	2.1
17			Roland Schregle (roland.schregle@{hslu.ch, gmail.com})
18			(c) Fraunhofer Institute for Solar Energy Systems,
19	rschregle	2.2	(c) Lucerne University of Applied Sciences and Arts,
20	rschregle	2.10	supported by the Swiss National Science Foundation (SNSF, #147053)
21			=========================================================================
22	greg	2.1
23	rschregle	2.10	$Id: pmapdata.h,v 4.22.2.7 2016/02/04 20:21:28 taschreg Exp taschreg $
24	greg	2.1	*/
25
26
27	rschregle	2.10
28	greg	2.1	#ifndef PMAPDATA_H
29			#define PMAPDATA_H
30
31			#include "ray.h"
32			#include "pmaptype.h"
33			#include "lookup.h"
34	rschregle	2.10	#include <stdint.h>
35	greg	2.1
36
37	rschregle	2.10
38	greg	2.1	/* Primary photon ray for light source contributions */
39			typedef struct {
40	rschregle	2.10	int16 srcIdx; /* Index of emitting light source */
41			/* !!! REDUCED FROM 32 BITS !!! */
42			int32 dir; /* Encoded ray direction */
43			#ifdef PMAP_PRIMARYPOS
44			float pos [3]; /* Hit point */
45			#endif
46	greg	2.1	} PhotonPrimary;
47
48	rschregle	2.10	#define photonSrcIdx(pm, p) ((pm)->primaries[(p)->primary].srcIdx)
49
50
51
52			/* Photon primary ray index type and limit */
53			typedef uint32 PhotonPrimaryIdx;
54			#define PMAP_MAXPRIMARY UINT32_MAX
55
56			/* Macros for photon's generating subprocess field */
57			#ifdef PMAP_OOC
58			#define PMAP_PROCBITS 7
59			#else
60			#define PMAP_PROCBITS 5
61			#endif
62			#define PMAP_MAXPROC (1 << PMAP_PROCBITS)
63			#define PMAP_GETRAYPROC(r) ((r) -> crtype >> 8)
64			#define PMAP_SETRAYPROC(r,p) ((r) -> crtype \|= p << 8)
65
66			/* Tolerance for photon normal check during lookups */
67			#define PMAP_NORM_TOL 0.02
68
69	greg	2.1
70
71			typedef struct {
72	rschregle	2.10	float pos [3]; /* Photon position */
73			signed char norm [3]; /* Surface normal at pos (incident
74			direction for volume photons) */
75			union {
76			struct {
77			#ifndef PMAP_OOC
78			unsigned char discr : 2; /* kd-tree discriminator axis */
79			#endif
80			unsigned char caustic : 1; /* Specularly scattered (=caustic) */
81
82			/* Photon's generating subprocess index, used for primary ray
83			* index linearisation when building contrib pmaps; note this is
84			* reduced for kd-tree to accommodate the discriminator field */
85			unsigned char proc : PMAP_PROCBITS;
86			};
87
88			unsigned char flags;
89			};
90
91			#ifdef PMAP_FLOAT_FLUX
92			COLOR flux;
93			#else
94			COLR flux;
95			#endif
96			PhotonPrimaryIdx primary; /* Index to primary ray */
97			} Photon;
98
99	greg	2.1
100
101	rschregle	2.10	/* Define PMAP_FLOAT_FLUX to store photon flux as floats instead of
102			* compact RGBE, which was found to improve accuracy in analytical
103			* validation. */
104			#ifdef PMAP_FLOAT_FLUX
105			#define setPhotonFlux(p,f) copycolor((p) -> flux, f)
106			#define getPhotonFlux(p,f) copycolor(f, (p) -> flux)
107			#else
108			#define setPhotonFlux(p,f) setcolr((p)->flux, (f)[0], (f)[1], (f)[2])
109			#define getPhotonFlux(p,f) colr_color(f, (p) -> flux)
110			#endif
111	greg	2.1
112
113
114			/* Bias compensation history node */
115			typedef struct {
116			COLOR irrad;
117			float weight;
118	rschregle	2.10	} PhotonBiasCompNode;
119
120	greg	2.1
121	rschregle	2.10	/* Forward declaration */
122			struct PhotonMap;
123
124
125			/* Define search queue and underlying data struct types */
126			#ifdef PMAP_OOC
127			#include "pmapooc.h"
128			#else
129			#include "pmapkdt.h"
130			#endif
131	greg	2.1
132
133			typedef struct PhotonMap {
134	rschregle	2.10	PhotonMapType type; /* See pmaptype.h */
135			char fileName; / Photon map file */
136
137
138			/* ================================================================
139			* PRE/POST-BUILD STORAGE
140			* ================================================================ */
141			FILE heap; / Unsorted photon heap prior to
142			construction of store */
143			Photon heapBuf; / Write buffer for above */
144			unsigned long heapBufLen, /* Current & max size of heapBuf */
145			heapBufSize;
146			PhotonStorage store; /* Photon storage in spacee
147			subdividing data struct */
148
149			/* ================================================================
150			* PHOTON DISTRIBUTION STUFF
151			* ================================================================ */
152			unsigned long distribTarget, /* Num stored specified by user */
153			numPhotons; /* Num actually stored */
154			float distribRatio; /* Probability of photon storage */
155			COLOR photonFlux; /* Average photon flux */
156			unsigned short randState [3]; /* Local RNG state */
157
158
159			/* ================================================================
160			* PHOTON LOOKUP STUFF
161			* ================================================================ */
162			union { /* Flags passed to findPhotons() */
163			char lookupCaustic : 1;
164			char lookupFlags;
165			};
166
167			PhotonSearchQueue squeue; /* Search queue for photon lookups */
168			unsigned minGather, /* Specified min/max photons per */
169			maxGather; /* density estimate */
170
171			/* NOTE: All distances are SQUARED */
172			float maxDist2, /* Max search radius */
173			maxDist0, /* Initial value for above */
174			maxDist2Limit, /* Hard limit for above */
175			gatherTolerance; /* Fractional deviation from minGather/
176			maxGather for short lookup */
177			void (lookup)(struct PhotonMap,
178			RAY, COLOR); / Callback for type-specific photon
179			* lookup (usually density estimate) */
180
181
182			/* ================================================================
183			* BIAS COMPENSATION STUFF
184			* ================================================================ */
185			PhotonBiasCompNode biasCompHist; / Bias compensation history */
186
187
188			/* ================================================================
189			* STATISTIX
190			* ================================================================ */
191			unsigned long totalGathered, /* Total photons gathered */
192			numDensity, /* Num density estimates */
193			numLookups, /* Counters for short photon lookups */
194			numShortLookups;
195
196			unsigned minGathered, /* Min/max photons actually gathered */
197			maxGathered, /* per density estimate */
198			shortLookupPct; /* % of short lookups for stats */
199
200			float minError, /* Min/max/rms density estimate error */
201			maxError,
202			rmsError,
203			CoGdist, /* Avg distance to centre of gravity */
204			maxPos [3], /* Max & min photon positions */
205			minPos [3];
206
207			FVECT CoG; /* Centre of gravity (avg photon pos) */
208
209
210			/* ================================================================
211			* PHOTON CONTRIB/COEFF STUFF
212			* ================================================================ */
213			PhotonPrimary primaries, / Photon primary array for rendering */
214			lastPrimary; /* Current primary for photon distrib */
215			PhotonPrimaryIdx numPrimary; /* Number of primary rays */
216			LUTAB srcContrib; / Lookup table for source contribs */
217	greg	2.1	} PhotonMap;
218
219
220
221			/* Photon maps by type (see PhotonMapType) */
222	rschregle	2.10	extern PhotonMap *photonMaps [];
223	greg	2.1
224			/* Macros for specific photon map types */
225	rschregle	2.10	#define globalPmap (photonMaps [PMAP_TYPE_GLOBAL])
226			#define preCompPmap (photonMaps [PMAP_TYPE_PRECOMP])
227			#define causticPmap (photonMaps [PMAP_TYPE_CAUSTIC])
228			#define volumePmap (photonMaps [PMAP_TYPE_VOLUME])
229			#define directPmap (photonMaps [PMAP_TYPE_DIRECT])
230			#define contribPmap (photonMaps [PMAP_TYPE_CONTRIB])
231
232			/* Photon map type tests */
233			#define isGlobalPmap(p) ((p) -> type == PMAP_TYPE_GLOBAL)
234			#define isCausticPmap(p) ((p) -> type == PMAP_TYPE_CAUSTIC)
235			#define isContribPmap(p) ((p) -> type == PMAP_TYPE_CONTRIB)
236			#define isVolumePmap(p) ((p) -> type == PMAP_TYPE_VOLUME)
237	greg	2.1
238	rschregle	2.10	/* Mean size of heapfile write buffer, in number of photons */
239			#define PMAP_HEAPBUFSIZE 1e6
240
241			/* Mean idle time between heap locking attempts, in usec */
242			#define PMAP_HEAPBUFSLEEP 2e6
243
244			/* Shared memory file for parallelised photon distribution */
245			#if 0
246			#define PMAP_SHMFNAME "/mkpmap-%d"
247			#else
248			#define PMAP_SHMFNAME "mkpmapXXXXXX"
249			#endif
250	greg	2.1
251
252			void initPhotonMap (PhotonMap *pmap, PhotonMapType t);
253			/* Initialise empty photon map of specified type */
254
255	rschregle	2.10	int newPhoton (PhotonMap pmap, const RAY ray);
256			/* Create new photon with ray's direction, intersection point, and flux,
257			and append to unsorted photon heap pmap -> heap. The photon is
258			accepted with probability pmap -> distribRatio for global density
259			control; if the photon is rejected, -1 is returned, else 0. The flux
260			is scaled by ray -> rweight and 1 / pmap -> distribRatio. */
261
262			void initPhotonHeap (PhotonMap *pmap);
263			/* Open photon heap file */
264
265			void flushPhotonHeap (PhotonMap *pmap);
266			/* Flush photon heap buffa pmap -> heapBuf to heap file pmap -> heap;
267			* used by newPhoton() and to finalise heap in distribPhotons(). */
268
269			void buildPhotonMap (PhotonMap pmap, double photonFlux,
270			PhotonPrimaryIdx *primaryOfs, unsigned nproc);
271			/* Postpress unsorted photon heap pmap -> heap and build underlying data
272			* structure pmap -> store. This is prerequisite to photon lookups with
273			* findPhotons(). */
274
275			/* PhotonFlux is the flux per photon averaged over RGB; this is
276			* multiplied with each photon's flux during the postprocess. In the
277			* case of a contribution photon map, this is an array with a separate
278			* flux specific to each light source due to non-uniform photon emission;
279			* Otherwise it is referenced as a scalar value. Flux is not scaled if
280			* photonFlux == NULL. */
281
282			/* Photon map construction may be parallelised if nproc > 1, if
283			* supported. The heap is destroyed on return. */
284
285			/* PrimaryOfs is an array of index offsets for the primaries in pmap ->
286			* primaries generated by each of the nproc subprocesses during contrib
287			* photon distribution (see distribPhotonContrib()). These offsets are
288			* used to linearise the photon primary indices in the postprocess. This
289			* linearisation is skipped if primaryOfs == NULL. */
290	greg	2.1
291			void findPhotons (PhotonMap* pmap, const RAY *ray);
292	rschregle	2.10	/* Find pmap -> squeue.len closest photons to ray -> rop with similar
293	greg	2.1	normal. For volume photons ray -> rorg is used and the normal is
294			ignored (being the incident direction in this case). Found photons
295	rschregle	2.10	are placed search queue starting with the furthest photon at pmap ->
296			squeue.node, and pmap -> squeue.tail being the number actually found. */
297	greg	2.1
298	rschregle	2.10	void find1Photon (PhotonMap pmap, const RAY ray, Photon *photon);
299	greg	2.1	/* Finds single closest photon to ray -> rop with similar normal.
300			Returns NULL if none found. */
301
302	rschregle	2.10	void getPhoton (PhotonMap pmap, PhotonIdx idx, Photon photon);
303			/* Retrieve photon referenced by idx from pmap -> store */
304
305			Photon getNearestPhoton (const PhotonSearchQueue squeue, PhotonIdx idx);
306			/* Retrieve photon from NN search queue after calling findPhotons() */
307
308			PhotonIdx firstPhoton (const PhotonMap *pmap);
309			/* Index to first photon, to be passed to getPhoton(). Indices to
310			* subsequent photons can be optained via increment operator (++) */
311
312	greg	2.1	void deletePhotons (PhotonMap*);
313			/* Free dem mammaries... */
314
315			#endif