/* 
   =========================================================================
   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 bit fields can be redistributed if more precision is required at the
   expense of fewer bins.
   
   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 are therefore normalised against a given normalisation
   factor (e.g. 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_MANTMAX  (1 << (RGBE_CONTRIB_MANTBITS - 1))
   /* Absolute overflow limit for mantissa (sign flips if exceeded) */
   #define RGBE_CONTRIB_MANTOVF  ((RGBE_CONTRIB_MANTMAX << 1) - 1)   
   #define RGBE_CONTRIB_MIN      (1.0 / (1L << (1 << RGBE_CONTRIB_EXPBITS)))
   #define RGBE_CONTRIB_MAX      1.0
   #define RGBE_CONTRIB_BINMAX   ((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], double norm [3], unsigned bin
   );
   /* Normalise signed float RGB contributions against abs(norm), and encode
    * to RGBE with associated bin. Issues warning if abs(norm) < abs(rgb). */
   
   unsigned RGBEContribDec (
      RGBEContrib rgbeCont, double norm [3], double rgb [3]
   );
   /* Decode RGBE contribution, returning signed floating point contributions 
    * in array rgb after denormalisation against abs(norm), and the associated 
    * bin as return value. */
#endif