--- ray/src/common/tonemap.h 1997/04/21 15:23:42 3.5 +++ ray/src/common/tonemap.h 2005/01/07 20:33:02 3.17 @@ -1,14 +1,18 @@ -/* Copyright (c) 1997 Regents of the University of California */ - -/* SCCSid "$SunId$ LBL" */ - +/* RCSid $Id: tonemap.h,v 3.17 2005/01/07 20:33:02 greg 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 */ @@ -32,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 */ @@ -48,6 +53,9 @@ #define TM_BRTSCALE 128 /* brightness scale factor (integer) */ +#define TM_NOBRT (-1<<15) /* bogus brightness value */ +#define TM_NOLUM (1e-17) /* ridiculously small luminance */ + #define TM_MAXPKG 8 /* maximum number of color formats */ @@ -58,11 +66,13 @@ #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 */ /* basic tone mapping data structure */ -extern struct tmStruct { +typedef struct tmStruct { int flags; /* flags of what to do */ RGBPRIMP monpri; /* monitor RGB primaries */ double mongam; /* monitor gamma value (approx.) */ @@ -71,27 +81,19 @@ extern struct tmStruct { RGBPRIMP inppri; /* current input primaries */ double inpsf; /* current input scalefactor */ 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 */ +} TMstruct; /* conversion package functions */ -#ifdef NOPROTO struct tmPackage { - MEM_PTR (*Init)(); /* initialize private data */ - void (*NewSpace)(); /* new input color space (optional) */ - void (*Free)(); /* free private data */ -}; -#else -struct tmPackage { - MEM_PTR (*Init)(struct tmStruct *tms); - int (*NewSpace)(struct tmStruct *tms); + MEM_PTR (*Init)(TMstruct *tms); + void (*NewSpace)(TMstruct *tms); void (*Free)(MEM_PTR pp); }; -#endif /* our list of conversion packages */ extern struct tmPackage *tmPkg[TM_MAXPKG]; extern int tmNumPkgs; /* number of registered packages */ @@ -100,7 +102,7 @@ extern int tmNumPkgs; /* number of registered packages /**** Useful Macros ****/ /* compute luminance from encoded value */ -#define tmLuminance(li) exp((li)/(double)TM_BRTSCALE) +#define tmLuminance(li) exp((li)*(1./TM_BRTSCALE)) /* does tone mapping need color matrix? */ #define tmNeedMatrix(t) ((t)->monpri != (t)->inppri) @@ -115,33 +117,25 @@ extern int tmNumPkgs; /* number of registered packages /**** Library Function Calls ****/ -#ifdef NOPROTO -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(); - -#else - -extern struct tmStruct * +extern TMstruct * tmInit(int flags, RGBPRIMP monpri, double gamval); /* - Initialize new tone mapping and push it onto stack. + Allocate and initialize new tone mapping. flags - TM_F_* flags indicating what is to be done. monpri - display monitor primaries (Note 1). gamval - display gamma response (can be approximate). - returns - new tmTop, or NULL if insufficient memory. + returns - new tone-mapping pointer, or NULL if no memory. */ extern int -tmSetSpace(RGBPRIMP pri, double sf); +tmSetSpace(TMstruct *tms, RGBPRIMP pri, double sf); /* Set color primaries and scale factor for incoming scanlines. + tms - tone mapping structure pointer. pri - RGB color input primaries (Note 1). sf - scale factor to get to luminance in cd/m^2. @@ -149,42 +143,19 @@ tmSetSpace(RGBPRIMP pri, double sf); */ extern void -tmClearHisto(void); +tmClearHisto(TMstruct *tms); /* Clear histogram for current tone mapping. -*/ -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. + tms - tone mapping structure pointer. */ extern int -tmCvColrs(TMbright *ls, BYTE *cs, COLR *scan, int len); +tmAddHisto(TMstruct *tms, TMbright *ls, int len, int wt); /* - 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. + tms - tone mapping structure pointer. ls - encoded luminance values. len - number of luminance values. wt - integer weight to use for each value (usually 1 or -1). @@ -193,10 +164,29 @@ tmAddHisto(TMbright *ls, int len, int wt); */ extern int -tmComputeMapping(double gamval, double Lddyn, double Ldmax); +tmFixedMapping(TMstruct *tms, double expmult, double gamval); /* - Compute tone mapping function. + 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. + + tms - tone mapping structure pointer. + 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(TMstruct *tms, double gamval, double Lddyn, double Ldmax); +/* + 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. + + tms - tone mapping structure pointer. gamval - display gamma response (0. for default). Lddyn - the display's dynamic range (0. for default). Ldmax - maximum display luminance in cd/m^2 (0. for default). @@ -205,10 +195,11 @@ tmComputeMapping(double gamval, double Lddyn, double L */ extern int -tmMapPixels(BYTE *ps, TMbright *ls, BYTE *cs, int len); +tmMapPixels(TMstruct *tms, BYTE *ps, TMbright *ls, BYTE *cs, int len); /* Apply tone mapping function to pixel values. + tms - tone mapping structure pointer. ps - returned pixel values (Note 2). ls - encoded luminance values. cs - encoded chrominance values (Note 2). @@ -217,8 +208,66 @@ tmMapPixels(BYTE *ps, TMbright *ls, BYTE *cs, int len) returns - 0 on success, TM_E_* on failure. */ +extern TMstruct * +tmDup(TMstruct *orig); +/* + Duplicate the given tone mapping into a new struct. + + orig - tone mapping structure to duplicate. + returns - pointer to new struct, or NULL on error. +*/ + +extern void +tmDone(TMstruct *tms); +/* + Free data associated with the given tone mapping structure. + + tms - tone mapping structure to free. +*/ + extern int -tmLoadPicture(TMbright **lpp, BYTE **cpp, int *xp, int *yp, +tmCvColors(TMstruct *tms, TMbright *ls, BYTE *cs, COLOR *scan, int len); +/* + Convert RGB/XYZ float scanline to encoded luminance and chrominance. + + tms - tone mapping structure pointer. + 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(TMstruct *tms, TMbright *ls, float *scan, int len); +/* + Convert gray float scanline to encoded luminance. + + tms - tone mapping structure pointer. + ls - returned encoded luminance values. + scan - input scanline. + len - scanline length. + + returns - 0 on success, TM_E_* on error. +*/ + +extern int +tmCvColrs(TMstruct *tms, TMbright *ls, BYTE *cs, COLR *scan, int len); +/* + Convert RGBE/XYZE scanline to encoded luminance and chrominance. + + tms - tone mapping structure pointer. + 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(TMstruct *tms, TMbright **lpp, BYTE **cpp, int *xp, int *yp, char *fname, FILE *fp); /* Load Radiance picture and convert to tone mapping representation. @@ -226,7 +275,8 @@ tmLoadPicture(TMbright **lpp, BYTE **cpp, int *xp, int 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. + tms - tone mapping structure pointer. + 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. @@ -241,14 +291,13 @@ tmMapPicture(BYTE **psp, int *xp, int *yp, int flags, char *fname, FILE *fp); /* Load and apply tone mapping to Radiance picture. - Stack is restored to its original state upon return. 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). @@ -261,57 +310,36 @@ 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(TMstruct *tms, 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. + tms - tone mapping structure pointer. + 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(TMstruct *tms, 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. + tms - tone mapping structure pointer. + 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: @@ -382,3 +410,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_ */ +