/* 
   =========================================================================
   mRGBE (miniRGBE): reduced RGBE encoding of normalised RGB floats plus
   associated integer payload data.  By default, this encoding consists of:
   
      - three signed 5-bit mantissas for each RGB colour channel,
      - a common 5-bit exponent,
      - and an associated 12-bit integer datum.
      
   However, this allocation can be modified within a 32-bit envelope if more
   precision is required by modifying mRGBE_MANTBITS, mRGBE_EXPBITS and
   mRGBE_DATABITS.
      
   The encoded float RGB tuples are assumed to lie in the range [-1, 1],
   with values in the interval [-mRGBE_MIN, mRGBE_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 _mRGBE_H
   #define _mRGBE_H
   
   #include <stdint.h>
   
   
   /* Mantissa / exponent / payload data bits and their encoding ranges.
      NOTE: binary shifts can overflow if the number of bits is increased;
      in this case shifts must either be promoted to 64 bits (possibly at
      the expense of portability), or replaced by much slower pow(2, ..) */
   #define mRGBE_MANTBITS 5
   #define mRGBE_EXPBITS  5
   #define mRGBE_DATABITS 12
   
   /* Signed maximum for mantissa */
   #define mRGBE_MANTMAX  (1 << (mRGBE_MANTBITS - 1))
   /* Absolute overflow limit for mantissa (sign flips if exceeded) */
   #define mRGBE_MANTOVF  ((mRGBE_MANTMAX << 1) - 1)   
   #define mRGBE_MIN      (1.0 / (1L << (1 << mRGBE_EXPBITS)))
   #define mRGBE_MAX      1.0
   #define mRGBE_DATAMAX  ((1U << mRGBE_DATABITS) - 1)
   

   typedef union {
      struct {
         /* (mini)RGBE representation consisting of a 4-bit mantissa + sign
          * per RGB, a common 5-bit exponent, and a 12-bit payload data */
         unsigned red: mRGBE_MANTBITS,
                  grn: mRGBE_MANTBITS,
                  blu: mRGBE_MANTBITS,
                  exp: mRGBE_EXPBITS,
                  dat: mRGBE_DATABITS;
      };
      
      uint32_t all;
   } mRGBE;
   
   
   mRGBE mRGBEencode (double rgb [3], double norm [3], unsigned data);
   /* Normalise signed float RGB tuple by abs(norm), and encode to mRGBE
    * with associated data.  Issues warning if abs(norm) < abs(rgb).  */
   
   unsigned mRGBEdecode (mRGBE mrgbe, double norm [3], double rgb [3]);
   /* Decode mRGBE, returning signed float RGB tuple in array rgb after
    * denormalisation against abs(norm).  The associated payload data is
    * decoded as return value.  */
#endif