ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/common/tonemap.h
Revision: 3.26
Committed: Fri May 20 02:06:38 2011 UTC (12 years, 10 months ago) by greg
Content type: text/plain
Branch: MAIN
CVS Tags: rad5R2, rad4R2P2, rad5R0, rad5R1, rad4R2, rad4R1, rad4R2P1, rad5R3
Changes since 3.25: +9 -9 lines
Log Message:
Changed every instance of BYTE to uby8 to avoid conflicts

File Contents

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