/* 
   =========================================================================
   RGBE representation of binned contributions consisting of:
      - three 5-bit mantissas for each RGB colour channel
      - a common 5-bit exponent
      - and a 12-bit bin number for the contribution
   = 32 bits.
   
   The floating point RGB contributions are assumed to be SIGNED and lie in
   the range [-1, 1], with values in the interval [-RGBE_CONTRIB_MIN,
   RGBE_CONTRIB_MIN] clamped to 0, since these cannot be resolved.  The
   encoded values should therefore be normalised (e.g.  divided by their
   absolute maximum) in order to maximise the useful range.

   Roland Schregle (roland.schregle@{hslu.ch, gmail.com})
   (c) Lucerne University of Applied Sciences and Arts,
       supported by the Swiss National Science Foundation 
       (SNSF #179067, "Light Fields for Spatio-Temporal Glare Assessment")
   =========================================================================
   
   $Id$
*/


#ifndef _RGBE_CONTRIB_H
   #define _RGBE_CONTRIB_H
   
   #include <stdint.h>
   
   
   /* RGBE Mantissa / exponent / bin bits and their encoding ranges
      (NOTE: The binary shifts can overflow if the number of bits is
      increased; in this case the much slower pow(2, ..) can be used.  */
   #define RGBE_CONTRIB_MANTBITS 5
   #define RGBE_CONTRIB_EXPBITS  5
   #define RGBE_CONTRIB_BINBITS  12
   
   /* Signed maximum for mantissa */
   #define RGBE_CONTRIB_MAXMANT  (1 << (RGBE_CONTRIB_MANTBITS - 1))
   /* Absolute overflow limit for mantissa (sign flips if exceeded) */
   #define RGBE_CONTRIB_MANTOVF  ((RGBE_CONTRIB_MAXMANT << 1) - 1)   
   #define RGBE_CONTRIB_MIN      (1.0 / (1L << (1 << RGBE_CONTRIB_EXPBITS)))
   #define RGBE_CONTRIB_MAX      1.0
   #define RGBE_CONTRIB_MAXBIN   ((1U << RGBE_CONTRIB_BINBITS) - 1)
   

   typedef union {
      struct {
         /* Compressed RGBE representation of binned contributions,
          * consisting of a 4-bit mantissa + sign per RGB, a common 5-bit
          * exponent, and a 12-bit bin number.  */
         unsigned red: RGBE_CONTRIB_MANTBITS,
                  grn: RGBE_CONTRIB_MANTBITS,
                  blu: RGBE_CONTRIB_MANTBITS,
                  exp: RGBE_CONTRIB_EXPBITS,
                  bin: RGBE_CONTRIB_BINBITS;
      };
      
      uint32_t rgbeBin;
   } RGBEContrib;
   
   
   RGBEContrib RGBEContribEnc (double rgb [3], unsigned bin);
   /* Encode signed float RGB contributions with associated bin to RGBE */
   
   unsigned RGBEContribDec (RGBEContrib rgbeCont, double rgb [3]);
   /* Decode rgbeCont, returning signed floating point contributions in
    * array rgb, and the associated bin as return value */
#endif