--- ray/src/common/tonemap.h 1997/04/16 20:28:07 3.3 +++ ray/src/common/tonemap.h 2003/07/14 22:23:59 3.16 @@ -1,13 +1,18 @@ -/* Copyright (c) 1997 Regents of the University of California */ - -/* SCCSid "$SunId$ LBL" */ - +/* RCSid $Id: tonemap.h,v 3.16 2003/07/14 22:23:59 schorsch Exp $ */ /* * Header file for tone mapping functions. + * + * Include after "color.h" */ - /* required non-system header files */ -#include "color.h" +#ifndef _RAD_TONEMAP_H_ +#define _RAD_TONEMAP_H_ +#include "tifftypes.h" + +#ifdef __cplusplus +extern "C" { +#endif + /**** Argument Macros ****/ /* Flags of what to do */ #define TM_F_HCONTR 01 /* human contrast sensitivity */ @@ -31,6 +36,7 @@ #define TM_NOCHROMP (BYTE **)NULL /* indicate no chrominances */ #define TM_GETFILE (FILE *)NULL /* indicate file must be opened */ + /**** Error Return Values ****/ #define TM_E_OK 0 /* normal return status */ @@ -39,16 +45,29 @@ #define TM_E_TMINVAL 3 /* no valid tone mapping */ #define TM_E_TMFAIL 4 /* cannot compute tone mapping */ #define TM_E_BADFILE 5 /* cannot open or understand file */ +#define TM_E_CODERR1 6 /* code consistency error 1 */ +#define TM_E_CODERR2 7 /* code consistency error 2 */ + /**** Conversion Constants and Table Sizes ****/ #define TM_BRTSCALE 128 /* brightness scale factor (integer) */ -#define TM_GAMTSZ 1024 /* gamma lookup table size */ +#define TM_NOBRT (-1<<15) /* bogus brightness value */ +#define TM_NOLUM (1e-17) /* ridiculously small luminance */ -/**** Global Data Structures ****/ +#define TM_MAXPKG 8 /* maximum number of color formats */ + +/**** Global Data Types and Structures ****/ + +#ifndef MEM_PTR +#define MEM_PTR void * +#endif + extern char *tmErrorMessage[]; /* error messages */ +extern int tmLastError; /* last error incurred by library */ +extern char *tmLastFunction; /* error-generating function name */ typedef short TMbright; /* encoded luminance type */ @@ -57,35 +76,49 @@ extern struct tmStruct { int flags; /* flags of what to do */ RGBPRIMP monpri; /* monitor RGB primaries */ double mongam; /* monitor gamma value (approx.) */ - BYTE gamb[TM_GAMTSZ];/* gamma lookup table from mongam */ COLOR clf; /* computed luminance coefficients */ - COLR clfb; /* normalized version of clf */ + int cdiv[3]; /* computed color divisors */ RGBPRIMP inppri; /* current input primaries */ double inpsf; /* current input scalefactor */ - TMbright inpsfb; /* encoded version of inpsf */ COLORMAT cmat; /* color conversion matrix */ - TMbright brmin, brmax; /* input brightness limits */ + TMbright hbrmin, hbrmax; /* histogram brightness limits */ int *histo; /* input histogram */ + TMbright mbrmin, mbrmax; /* mapped brightness limits */ unsigned short *lumap; /* computed luminance map */ struct tmStruct *tmprev; /* previous tone mapping */ + MEM_PTR pd[TM_MAXPKG]; /* pointers to private data */ } *tmTop; /* current tone mapping stack */ - + + /* conversion package functions */ +struct tmPackage { + MEM_PTR (*Init)(struct tmStruct *tms); + void (*NewSpace)(struct tmStruct *tms); + void (*Free)(MEM_PTR pp); +}; + /* our list of conversion packages */ +extern struct tmPackage *tmPkg[TM_MAXPKG]; +extern int tmNumPkgs; /* number of registered packages */ + + /**** Useful Macros ****/ -#define tmLuminance(li) exp((li)/(double)TM_BRTSCALE) + /* compute luminance from encoded value */ +#define tmLuminance(li) exp((li)*(1./TM_BRTSCALE)) -/**** Library Function Calls ****/ + /* does tone mapping need color matrix? */ +#define tmNeedMatrix(t) ((t)->monpri != (t)->inppri) -#ifdef NOPROTO + /* register a conversion package */ +#define tmRegPkg(pf) ( tmNumPkgs >= TM_MAXPKG ? -1 : \ + (tmPkg[tmNumPkgs] = (pf), tmNumPkgs++) ) -extern struct tmStruct *tmInit(), *tmPop(), *tmDup(); -extern void tmClearHisto(), tmDone(); -extern int tmSetSpace(), tmCvColors(), tmCvColrs(); -extern int tmAddHisto(), tmComputeMapping(), tmMapPixels(); -extern int tmLoadPicture(), tmMapPicture(), tmPull(), tmPush(); + /* get the specific package's data */ +#define tmPkgData(t,i) ((t)->pd[i]!=NULL ? (t)->pd[i] : (*tmPkg[i]->Init)(t)) -#else +/**** Library Function Calls ****/ + + extern struct tmStruct * tmInit(int flags, RGBPRIMP monpri, double gamval); /* @@ -116,32 +149,6 @@ tmClearHisto(void); */ extern int -tmCvColors(TMbright *ls, BYTE *cs, COLOR *scan, int len); -/* - Convert RGB/XYZ float scanline to encoded luminance and chrominance. - - ls - returned encoded luminance values. - cs - returned encoded chrominance values (Note 2). - scan - input scanline. - len - scanline length. - - returns - 0 on success, TM_E_* on error. -*/ - -extern int -tmCvColrs(TMbright *ls, BYTE *cs, COLR *scan, int len); -/* - Convert RGBE/XYZE scanline to encoded luminance and chrominance. - - ls - returned encoded luminance values. - cs - returned encoded chrominance values (Note 2). - scan - input scanline. - len - scanline length. - - returns - 0 on success, TM_E_* on error. -*/ - -extern int tmAddHisto(TMbright *ls, int len, int wt); /* Add brightness values to current histogram. @@ -154,9 +161,26 @@ tmAddHisto(TMbright *ls, int len, int wt); */ extern int +tmFixedMapping(double expmult, double gamval); +/* + Assign a fixed, linear tone-mapping using the given multiplier, + which is the ratio of maximum output to uncalibrated input. + This mapping will be used in subsequent calls to tmMapPixels() + until a new tone mapping is computed. + Only the min. and max. values are used from the histogram. + + expmult - the fixed exposure multiplier to use. + gamval - display gamma response (0. for default). + returns - 0 on success, TM_E_* on error. +*/ + +extern int tmComputeMapping(double gamval, double Lddyn, double Ldmax); /* - Compute tone mapping function. + Compute tone mapping function from the current histogram. + This mapping will be used in subsequent calls to tmMapPixels() + until a new tone mapping is computed. + I.e., calls to tmAddHisto() have no immediate effect. gamval - display gamma response (0. for default). Lddyn - the display's dynamic range (0. for default). @@ -178,14 +202,102 @@ tmMapPixels(BYTE *ps, TMbright *ls, BYTE *cs, int len) returns - 0 on success, TM_E_* on failure. */ +extern struct tmStruct * +tmPop(void); +/* + Pops current tone mapping from stack. + + returns - pointer to tone mapping structure, or NULL if none. +*/ + extern int +tmPull(struct tmStruct *tms); +/* + Pull tone mapping from anywhere in stack. + + tms - tone mapping structure to find. + + returns - 1 if found in stack, 0 otherwise. +*/ + +extern int +tmPush(struct tmStruct *tms); +/* + Make tone mapping active by (pulling it and) pushing it to the top. + + tms - initialized tone mapping structure. + + returns - 0 on success, TM_E_* if tms is invalid. +*/ + +extern struct tmStruct * +tmDup(void); +/* + Duplicate the current tone mapping into a new structure on the stack. + + returns - pointer to new top, or NULL on error. +*/ + +extern void +tmDone(struct tmStruct *tms); +/* + Free data associated with the given tone mapping structure. + Calls tmPull() first to remove it from the stack if present. + The calls tmDone(tmPop()), tmDone(tmTop) and tmDone(NULL) + all have the same effect, which is to remove and free + the current tone mapping. + + tms - tone mapping structure to free. +*/ + +extern int +tmCvColors(TMbright *ls, BYTE *cs, COLOR *scan, int len); +/* + Convert RGB/XYZ float scanline to encoded luminance and chrominance. + + ls - returned encoded luminance values. + cs - returned encoded chrominance values (Note 2). + scan - input scanline. + len - scanline length. + + returns - 0 on success, TM_E_* on error. +*/ + +extern int +tmCvGrays(TMbright *ls, float *scan, int len); +/* + Convert gray float scanline to encoded luminance. + + ls - returned encoded luminance values. + scan - input scanline. + len - scanline length. + + returns - 0 on success, TM_E_* on error. +*/ + +extern int +tmCvColrs(TMbright *ls, BYTE *cs, COLR *scan, int len); +/* + Convert RGBE/XYZE scanline to encoded luminance and chrominance. + + ls - returned encoded luminance values. + cs - returned encoded chrominance values (Note 2). + scan - input scanline. + len - scanline length. + + returns - 0 on success, TM_E_* on error. +*/ + +extern int tmLoadPicture(TMbright **lpp, BYTE **cpp, int *xp, int *yp, char *fname, FILE *fp); /* Load Radiance picture and convert to tone mapping representation. + Memory for the luminance and chroma arrays is allocated using + malloc(3), and should be freed with free(3) when no longer needed. Calls tmSetSpace() to calibrate input color space. - lpp - returned array of encoded luminances, English ordering. + lpp - returned array of encoded luminances, picture ordering. cpp - returned array of encoded chrominances (Note 2). xp, yp - returned picture dimensions. fname - picture file name. @@ -204,8 +316,10 @@ tmMapPicture(BYTE **psp, int *xp, int *yp, int flags, If fp is TM_GETFILE and (flags&TM_F_UNIMPL)!=0, tmMapPicture() calls pcond to perform the actual conversion, which takes longer but gives access to all the TM_F_* features. + Memory for the final pixel array is allocated using malloc(3), + and should be freed with free(3) when it is no longer needed. - psp - returned array of tone mapped pixels, English ordering. + psp - returned array of tone mapped pixels, picture ordering. xp, yp - returned picture dimensions. flags - TM_F_* flags indicating what is to be done. monpri - display monitor primaries (Note 1). @@ -218,56 +332,33 @@ tmMapPicture(BYTE **psp, int *xp, int *yp, int flags, returns - 0 on success, TM_E_* on failure. */ -extern struct tmStruct * -tmPop(void); -/* - Pops current tone mapping from stack. - - returns - pointer to tone mapping structure, or NULL if none. -*/ - extern int -tmPull(struct tmStruct *tms); +tmCvRGB48(TMbright *ls, BYTE *cs, uint16 (*scan)[3], int len, double gv); /* - Pull tone mapping from anywhere in stack. + Convert 48-bit RGB scanline to encoded luminance and chrominance. - tms - tone mapping structure to find. + ls - returned encoded luminance values. + cs - returned encoded chrominance values (Note 2). + scan - input scanline. + len - scanline length. + gv - input gamma value. - returns - 1 if found in stack, 0 otherwise. + returns - 0 on success, TM_E_* on error. */ extern int -tmPush(struct tmStruct *tms); +tmCvGray16(TMbright *ls, uint16 *scan, int len, double gv); /* - Make tone mapping active by (pulling it and) pushing it to the top. + Convert 16-bit gray scanline to encoded luminance. - tms - initialized tone mapping structure. + ls - returned encoded luminance values. + scan - input scanline. + len - scanline length. + gv - input gamma value. - returns - 0 on success, TM_E_* if tms is invalid. + returns - 0 on success, TM_E_* on error. */ -extern struct tmStruct * -tmDup(void); -/* - Duplicate the current tone mapping into a new structure on the stack. - - returns - pointer to new top, or NULL on error. -*/ - -extern void -tmDone(struct tmStruct *tms); -/* - Free data associated with the given tone mapping structure. - Calls tmPull() first to remove it from the stack if present. - The calls tmDone(tmPop()), tmDone(tmTop) and tmDone(NULL) - all have the same effect, which is to remove and free - the current tone mapping. - - tms - tone mapping structure to free. -*/ - -#endif - /**** Notes ****/ /* General: @@ -276,7 +367,7 @@ tmDone(struct tmStruct *tms); pixel values to chroma and luminance encodings, which can be passed to tmAddHisto() to put into the tone mapping histogram. This histogram is then used along with the display parameters - by tmComputMapping() to compute the luminance mapping function. + by tmComputeMapping() to compute the luminance mapping function. (Colors are tone-mapped as they are converted if TM_F_MESOPIC is set.) The encoded chroma and luminance values may then be passed to tmMapPixels() to apply the computed tone mapping in @@ -338,3 +429,9 @@ tmDone(struct tmStruct *tms); function will open the file, read its contents and close it before returning, whether or not an error was encountered. */ + +#ifdef __cplusplus +} +#endif +#endif /* _RAD_TONEMAP_H_ */ +