ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/common/tonemap.h
Revision: 3.7
Committed: Mon Nov 17 13:54:35 1997 UTC (26 years, 5 months ago) by gregl
Content type: text/plain
Branch: MAIN
Changes since 3.6: +5 -2 lines
Log Message:
changed behavior so that tmClearHisto() and tmAddHisto() do not
void computed tone mapping, even if brightness limits are exceeded

File Contents

# User Rev Content
1 greg 3.1 /* Copyright (c) 1997 Regents of the University of California */
2    
3     /* SCCSid "$SunId$ LBL" */
4    
5     /*
6     * Header file for tone mapping functions.
7     */
8     /* required non-system header files */
9     #include "color.h"
10    
11 greg 3.4
12 greg 3.1 /**** Argument Macros ****/
13     /* Flags of what to do */
14     #define TM_F_HCONTR 01 /* human contrast sensitivity */
15     #define TM_F_MESOPIC 02 /* mesopic color sensitivity */
16     #define TM_F_LINEAR 04 /* linear brightness mapping */
17     #define TM_F_ACUITY 010 /* acuity adjustment */
18     #define TM_F_VEIL 020 /* veiling glare */
19     #define TM_F_CWEIGHT 040 /* center weighting */
20     #define TM_F_FOVEAL 0100 /* use foveal sample size */
21     #define TM_F_BW 0200 /* luminance only */
22 greg 3.2 #define TM_F_NOSTDERR 0400 /* don't report errors to stderr */
23 greg 3.1 /* combined modes */
24     #define TM_F_CAMERA 0
25     #define TM_F_HUMAN (TM_F_HCONTR|TM_F_MESOPIC|TM_F_VEIL|\
26     TM_F_ACUITY|TM_F_FOVEAL)
27     #define TM_F_UNIMPL (TM_F_CWEIGHT|TM_F_VEIL|TM_F_ACUITY|TM_F_FOVEAL)
28    
29     /* special pointer values */
30     #define TM_XYZPRIM (RGBPRIMP)NULL /* indicate XYZ primaries (Note 1) */
31     #define TM_NOCHROM (BYTE *)NULL /* indicate no chrominance */
32     #define TM_NOCHROMP (BYTE **)NULL /* indicate no chrominances */
33     #define TM_GETFILE (FILE *)NULL /* indicate file must be opened */
34    
35     /**** Error Return Values ****/
36    
37     #define TM_E_OK 0 /* normal return status */
38     #define TM_E_NOMEM 1 /* out of memory */
39     #define TM_E_ILLEGAL 2 /* illegal argument value */
40     #define TM_E_TMINVAL 3 /* no valid tone mapping */
41     #define TM_E_TMFAIL 4 /* cannot compute tone mapping */
42     #define TM_E_BADFILE 5 /* cannot open or understand file */
43 greg 3.4 #define TM_E_CODERR1 6 /* code consistency error 1 */
44     #define TM_E_CODERR2 7 /* code consistency error 2 */
45 greg 3.1
46 greg 3.4
47 greg 3.1 /**** Conversion Constants and Table Sizes ****/
48    
49     #define TM_BRTSCALE 128 /* brightness scale factor (integer) */
50    
51 greg 3.4 #define TM_MAXPKG 8 /* maximum number of color formats */
52 greg 3.1
53    
54 greg 3.4 /**** Global Data Types and Structures ****/
55    
56     #ifndef MEM_PTR
57     #define MEM_PTR void *
58     #endif
59    
60 greg 3.1 extern char *tmErrorMessage[]; /* error messages */
61 gregl 3.6 extern int tmLastError; /* last error incurred by library */
62     extern char *tmLastFunction; /* error-generating function name */
63 greg 3.1
64     typedef short TMbright; /* encoded luminance type */
65    
66     /* basic tone mapping data structure */
67     extern struct tmStruct {
68     int flags; /* flags of what to do */
69     RGBPRIMP monpri; /* monitor RGB primaries */
70     double mongam; /* monitor gamma value (approx.) */
71     COLOR clf; /* computed luminance coefficients */
72 greg 3.4 int cdiv[3]; /* computed color divisors */
73 greg 3.1 RGBPRIMP inppri; /* current input primaries */
74     double inpsf; /* current input scalefactor */
75     COLORMAT cmat; /* color conversion matrix */
76 gregl 3.7 TMbright hbrmin, hbrmax; /* histogram brightness limits */
77 greg 3.1 int *histo; /* input histogram */
78 gregl 3.7 TMbright mbrmin, mbrmax; /* mapped brightness limits */
79 greg 3.1 unsigned short *lumap; /* computed luminance map */
80     struct tmStruct *tmprev; /* previous tone mapping */
81 greg 3.4 MEM_PTR pd[TM_MAXPKG]; /* pointers to private data */
82 greg 3.1 } *tmTop; /* current tone mapping stack */
83 greg 3.4
84     /* conversion package functions */
85     #ifdef NOPROTO
86     struct tmPackage {
87     MEM_PTR (*Init)(); /* initialize private data */
88     void (*NewSpace)(); /* new input color space (optional) */
89     void (*Free)(); /* free private data */
90     };
91     #else
92     struct tmPackage {
93     MEM_PTR (*Init)(struct tmStruct *tms);
94     int (*NewSpace)(struct tmStruct *tms);
95     void (*Free)(MEM_PTR pp);
96     };
97     #endif
98     /* our list of conversion packages */
99     extern struct tmPackage *tmPkg[TM_MAXPKG];
100     extern int tmNumPkgs; /* number of registered packages */
101    
102    
103 greg 3.1 /**** Useful Macros ****/
104    
105 greg 3.4 /* compute luminance from encoded value */
106 greg 3.1 #define tmLuminance(li) exp((li)/(double)TM_BRTSCALE)
107    
108 greg 3.4 /* does tone mapping need color matrix? */
109     #define tmNeedMatrix(t) ((t)->monpri != (t)->inppri)
110    
111     /* register a conversion package */
112     #define tmRegPkg(pf) ( tmNumPkgs >= TM_MAXPKG ? -1 : \
113     (tmPkg[tmNumPkgs] = (pf), tmNumPkgs++) )
114    
115     /* get the specific package's data */
116     #define tmPkgData(t,i) ((t)->pd[i]!=NULL ? (t)->pd[i] : (*tmPkg[i]->Init)(t))
117    
118    
119 greg 3.1 /**** Library Function Calls ****/
120    
121 greg 3.4 #ifdef NOPROTO
122 greg 3.1
123 greg 3.3 extern struct tmStruct *tmInit(), *tmPop(), *tmDup();
124 greg 3.1 extern void tmClearHisto(), tmDone();
125     extern int tmSetSpace(), tmCvColors(), tmCvColrs();
126     extern int tmAddHisto(), tmComputeMapping(), tmMapPixels();
127     extern int tmLoadPicture(), tmMapPicture(), tmPull(), tmPush();
128    
129     #else
130    
131     extern struct tmStruct *
132     tmInit(int flags, RGBPRIMP monpri, double gamval);
133     /*
134     Initialize new tone mapping and push it onto stack.
135    
136     flags - TM_F_* flags indicating what is to be done.
137     monpri - display monitor primaries (Note 1).
138     gamval - display gamma response (can be approximate).
139    
140     returns - new tmTop, or NULL if insufficient memory.
141     */
142    
143     extern int
144     tmSetSpace(RGBPRIMP pri, double sf);
145     /*
146     Set color primaries and scale factor for incoming scanlines.
147    
148     pri - RGB color input primaries (Note 1).
149     sf - scale factor to get to luminance in cd/m^2.
150    
151     returns - 0 on success, TM_E_* code on failure.
152     */
153    
154     extern void
155     tmClearHisto(void);
156     /*
157     Clear histogram for current tone mapping.
158     */
159    
160     extern int
161     tmCvColors(TMbright *ls, BYTE *cs, COLOR *scan, int len);
162     /*
163     Convert RGB/XYZ float scanline to encoded luminance and chrominance.
164    
165     ls - returned encoded luminance values.
166     cs - returned encoded chrominance values (Note 2).
167     scan - input scanline.
168     len - scanline length.
169    
170     returns - 0 on success, TM_E_* on error.
171     */
172    
173     extern int
174     tmCvColrs(TMbright *ls, BYTE *cs, COLR *scan, int len);
175     /*
176     Convert RGBE/XYZE scanline to encoded luminance and chrominance.
177    
178     ls - returned encoded luminance values.
179     cs - returned encoded chrominance values (Note 2).
180     scan - input scanline.
181     len - scanline length.
182    
183     returns - 0 on success, TM_E_* on error.
184     */
185    
186     extern int
187     tmAddHisto(TMbright *ls, int len, int wt);
188     /*
189     Add brightness values to current histogram.
190    
191     ls - encoded luminance values.
192     len - number of luminance values.
193     wt - integer weight to use for each value (usually 1 or -1).
194    
195     returns - 0 on success, TM_E_* on error.
196     */
197    
198     extern int
199     tmComputeMapping(double gamval, double Lddyn, double Ldmax);
200     /*
201 gregl 3.7 Compute tone mapping function. This mapping will be used
202     in subsequent calls to tmMapPixels() until a new tone mapping
203     is computed. I.e., calls to tmAddHisto() have no immediate effect.
204 greg 3.1
205     gamval - display gamma response (0. for default).
206     Lddyn - the display's dynamic range (0. for default).
207     Ldmax - maximum display luminance in cd/m^2 (0. for default).
208    
209     returns - 0 on success, TM_E_* on failure.
210     */
211    
212     extern int
213     tmMapPixels(BYTE *ps, TMbright *ls, BYTE *cs, int len);
214     /*
215     Apply tone mapping function to pixel values.
216    
217     ps - returned pixel values (Note 2).
218     ls - encoded luminance values.
219     cs - encoded chrominance values (Note 2).
220     len - number of pixels.
221    
222     returns - 0 on success, TM_E_* on failure.
223     */
224    
225     extern int
226     tmLoadPicture(TMbright **lpp, BYTE **cpp, int *xp, int *yp,
227     char *fname, FILE *fp);
228     /*
229     Load Radiance picture and convert to tone mapping representation.
230 greg 3.5 Memory for the luminance and chroma arrays is allocated using
231     malloc(3), and should be freed with free(3) when no longer needed.
232 greg 3.3 Calls tmSetSpace() to calibrate input color space.
233 greg 3.1
234     lpp - returned array of encoded luminances, English ordering.
235     cpp - returned array of encoded chrominances (Note 2).
236     xp, yp - returned picture dimensions.
237     fname - picture file name.
238     fp - pointer to open file (Note 3).
239    
240     returns - 0 on success, TM_E_* on failure.
241     */
242    
243     extern int
244     tmMapPicture(BYTE **psp, int *xp, int *yp, int flags,
245     RGBPRIMP monpri, double gamval, double Lddyn, double Ldmax,
246     char *fname, FILE *fp);
247     /*
248     Load and apply tone mapping to Radiance picture.
249     Stack is restored to its original state upon return.
250     If fp is TM_GETFILE and (flags&TM_F_UNIMPL)!=0, tmMapPicture()
251     calls pcond to perform the actual conversion, which takes
252     longer but gives access to all the TM_F_* features.
253 greg 3.5 Memory for the final pixel array is allocated using malloc(3),
254     and should be freed with free(3) when it is no longer needed.
255 greg 3.1
256     psp - returned array of tone mapped pixels, English ordering.
257     xp, yp - returned picture dimensions.
258     flags - TM_F_* flags indicating what is to be done.
259     monpri - display monitor primaries (Note 1).
260     gamval - display gamma response.
261     Lddyn - the display's dynamic range (0. for default).
262     Ldmax - maximum display luminance in cd/m^2 (0. for default).
263     fname - picture file name.
264     fp - pointer to open file (Note 3).
265    
266     returns - 0 on success, TM_E_* on failure.
267     */
268    
269     extern struct tmStruct *
270     tmPop(void);
271     /*
272     Pops current tone mapping from stack.
273    
274     returns - pointer to tone mapping structure, or NULL if none.
275     */
276    
277     extern int
278     tmPull(struct tmStruct *tms);
279     /*
280     Pull tone mapping from anywhere in stack.
281    
282     tms - tone mapping structure to find.
283    
284     returns - 1 if found in stack, 0 otherwise.
285     */
286    
287     extern int
288     tmPush(struct tmStruct *tms);
289     /*
290     Make tone mapping active by (pulling it and) pushing it to the top.
291    
292     tms - initialized tone mapping structure.
293    
294     returns - 0 on success, TM_E_* if tms is invalid.
295     */
296    
297 greg 3.3 extern struct tmStruct *
298     tmDup(void);
299     /*
300     Duplicate the current tone mapping into a new structure on the stack.
301    
302     returns - pointer to new top, or NULL on error.
303     */
304    
305 greg 3.1 extern void
306     tmDone(struct tmStruct *tms);
307     /*
308     Free data associated with the given tone mapping structure.
309     Calls tmPull() first to remove it from the stack if present.
310     The calls tmDone(tmPop()), tmDone(tmTop) and tmDone(NULL)
311     all have the same effect, which is to remove and free
312     the current tone mapping.
313    
314     tms - tone mapping structure to free.
315     */
316    
317     #endif
318 greg 3.4
319    
320 greg 3.1 /**** Notes ****/
321     /*
322     General:
323    
324     The usual sequence after calling tmInit() is to convert some
325     pixel values to chroma and luminance encodings, which can
326     be passed to tmAddHisto() to put into the tone mapping histogram.
327     This histogram is then used along with the display parameters
328 greg 3.5 by tmComputeMapping() to compute the luminance mapping function.
329 greg 3.1 (Colors are tone-mapped as they are converted if TM_F_MESOPIC
330     is set.) The encoded chroma and luminance values may then be
331     passed to tmMapPixels() to apply the computed tone mapping in
332     a second pass.
333    
334     Especially for RGBE colors in the same color space as the
335     target display, the conversion to chroma and luminance values
336     is fast enough that it may be recomputed on the second pass
337     if memory is at a premium. (Since the chroma values are only
338     used during final mapping, setting the cs parameter to TM_NOCHROM
339     on the first pass will save time.) Another memory saving option
340     if third and subsequent passes are not needed is to use the
341 greg 3.3 same array to store the mapped pixels as used to store
342 greg 3.1 the encoded chroma values. This way, only two extra bytes
343     for storing encoded luminances are required per pixel. This
344     is the method employed by tmMapPicture(), for example.
345     */
346     /*
347     Note 1:
348    
349     All RGBPRIMP values should be pointers to static structures.
350     I.e., the same pointer should be used for the same primaries,
351     and those primaries should not change from one call to the next.
352     This is because the routines use the pointer value to identify
353     computed conversion matrices, so the matrices do not have to be
354     rebuilt each time. If you are using the standard primaries,
355     use the standard primary pointer, stdprims.
356    
357     To indicate a set of input primaries are actually CIE XYZ,
358     the TM_XYZPRIM macro may be passed. If the input primaries
359     are unknown, it is wisest to pass tmTop->monpri to tmSetSpace().
360     By default, the input primaries equal the monitor primaries
361     and the scalefactor is set to WHTEFFICACY in tmInit().
362     */
363     /*
364     Note 2:
365    
366     Chrominance is optional in most of these routines, whether
367     TM_F_BW is set or not. Passing a value of TM_NOCHROM (or
368     TM_NOCHROMP for picture reading) indicates that returned
369     color values are not desired.
370    
371     If TM_NOCHROM is passed to a mapping routine expecting chroma
372     input, it will do without it and return luminance channel
373     rather than RGB pixel values. Otherwise, the array for
374     returned pixel values may be the same array used to pass
375     encoded chrominances if no other mappings are desired.
376     */
377     /*
378     Note 3:
379    
380     Picture files may either be opened by the calling routine or by
381     the library function. If opened by the calling routine, the
382     pointer to the stream is passed, which may be a pipe or other
383     non-seekable input as it is only read once. It must be
384     positioned at the beginning when the function is called, and it
385     will be positioned at the end on return. It will not be closed.
386     If the passed stream pointer is TM_GETFILE, then the library
387     function will open the file, read its contents and close it
388     before returning, whether or not an error was encountered.
389     */