pixel_format.C

/*
 * This file is part of the "Archon" framework.
 * (http://files3d.sourceforge.net)
 *
 * Copyright © 2006 by Kristian Spangsege and Brian Kristiansen.
 *
 * Permission to use, copy, modify, and distribute this software and
 * its documentation under the terms of the GNU General Public License is
 * hereby granted. No representations are made about the suitability of
 * this software for any purpose. It is provided "as is" without express
 * or implied warranty. See the GNU General Public License
 * (http://www.gnu.org/copyleft/gpl.html) for more details.
 *
 * The characters in this file are ISO8859-1 encoded.
 *
 * The documentation in this file is in "Doxygen" style
 * (http://www.doxygen.org).
 */

#include <map>

#include <archon/util/text.H>
#include <archon/util/pixel_format.H>


namespace Archon
{
  namespace Utilities
  {
    namespace
    {
      struct WordTypeDescriptor
      {
        PixelFormat::WordType type;
        string tag;
        int width; 
        bool isFloat;

        WordTypeDescriptor() {}

        WordTypeDescriptor(PixelFormat::WordType type, string tag, int width,
                           bool isFloat):
          type(type), tag(tag), width(width), isFloat(isFloat) {}
      };

      struct WordTypeRegistry
      {
        map<PixelFormat::WordType, WordTypeDescriptor> typeMap;
        map<string, WordTypeDescriptor> tagMap;
        map<int,    WordTypeDescriptor> intWidthMap;   
        map<int,    WordTypeDescriptor> floatWidthMap; 

        template<typename T> void addDescriptor(PixelFormat::WordType type, string tag)
        {
          int width = sizeof(T) * numeric_limits<unsigned char>::digits;
          bool isFloat = !numeric_limits<T>::is_integer;
          WordTypeDescriptor d(type, tag, width, isFloat);
          typeMap[type] = tagMap[tag] = d;
          if(isFloat) floatWidthMap[width] = d;
          else intWidthMap[width] = d;
        }

        WordTypeRegistry()
        {
          addDescriptor<unsigned char>       (PixelFormat::std_char,        "char");
          addDescriptor<unsigned short>      (PixelFormat::std_short,       "short");
          addDescriptor<unsigned int>        (PixelFormat::std_int,         "int");
          addDescriptor<unsigned long>       (PixelFormat::std_long,        "long");
          addDescriptor<PixelFormat::MaxInt> (PixelFormat::std_max_int,     "max_int");
          addDescriptor<float>               (PixelFormat::std_float,       "float");
          addDescriptor<double>              (PixelFormat::std_double,      "double");
          addDescriptor<long double>         (PixelFormat::std_long_double, "long_double");
        }
      };

      const WordTypeRegistry &getWordTypeRegistry()
      {
        static WordTypeRegistry registry;
        return registry;
      }

      const WordTypeDescriptor &getWordTypeDescriptor(PixelFormat::WordType type)
      {
        return getWordTypeRegistry().typeMap.find(type)->second;
      }
    }

    PixelFormat PixelFormat::getExpandedFormat()
      const throw(UnsupportedWordTypeException, InconsistencyException)
    {
cerr << "PixelFormat::getExpandedFormat: ---------------" << endl;
      PixelFormat complete;
      complete.formatType = formatType;
      complete.mostSignificantBitsFirst = mostSignificantBitsFirst;


      // Determine word type
      WordTypeDescriptor wordTypeDescriptor;
      if(wordType == custom_int)
      {
        map<int, WordTypeDescriptor>::const_iterator i =
          getWordTypeRegistry().intWidthMap.find(bitsPerWord);
        if(i == getWordTypeRegistry().intWidthMap.end())
          ARCHON_THROW(UnsupportedWordTypeException);
        wordTypeDescriptor = i->second;
      }
      else if(wordType == custom_float)
      {
        map<int, WordTypeDescriptor>::const_iterator i =
          getWordTypeRegistry().floatWidthMap.find(bitsPerWord);
        if(i == getWordTypeRegistry().floatWidthMap.end())
          ARCHON_THROW(UnsupportedWordTypeException);
        wordTypeDescriptor = i->second;
      }
      else
      {
        wordTypeDescriptor = getWordTypeDescriptor(wordType);
        if(bitsPerWord && wordTypeDescriptor.width != bitsPerWord)
          ARCHON_THROW1(InconsistencyException, "Conflicting bits per word ("+
                        Text::toString(bitsPerWord)+") specified for standard "
                        "word type ("+wordTypeDescriptor.tag+")");
      }
      complete.wordType = wordTypeDescriptor.type;
      complete.bitsPerWord = wordTypeDescriptor.width;
      if(wordTypeDescriptor.isFloat && formatType != direct)
        ARCHON_THROW1(InconsistencyException, "Only direct formats can be "
                      "used with floating point word types");
cerr << "PixelFormat::getExpandedFormat: wordType: " << wordTypeDescriptor.tag << endl;
cerr << "PixelFormat::getExpandedFormat: bitsPerWord: " << complete.bitsPerWord << endl;

      // Determine the number of channels
      int numberOfChannels;
      switch(colorScheme)
      {
      case luminance:
        numberOfChannels = hasAlphaChannel ? 2 : 1;
        break;

      case rgb:
      case hsv:
        numberOfChannels = hasAlphaChannel ? 4 : 3;
        break;

      default:
        numberOfChannels = 0;
      }
      if(numberOfChannels)
      {
        if(channelLayout.size() &&
           numberOfChannels != static_cast<int>(channelLayout.size()))
          ARCHON_THROW1(InconsistencyException, "Mismatching number of "
                        "channels in channel layout and color scheme");
      }
      else numberOfChannels =
        channelLayout.size() ? channelLayout.size() :
        pixelSize ? pixelSize : hasAlphaChannel ? 2 : 1;


      // Determine number of bits/words per pixel
      if(pixelSize) complete.pixelSize = pixelSize;
      else switch(formatType)
      {
      case direct:
        // One word per channel
        complete.pixelSize = numberOfChannels;
        break;

      case packed:
      case tight:
        int bitsPerPixel;
        if(channelLayout.empty()) bitsPerPixel = numberOfChannels; // Assume one bit per channel
        else
        {
          int maxOffsetIndex = -1;
          int minWidth = 0;
          for(int i=0; i<static_cast<int>(channelLayout.size()); ++i)
          {
            const Channel &c = channelLayout[i];
            if(maxOffsetIndex < 0 || channelLayout[maxOffsetIndex].offset < c.offset) maxOffsetIndex = i;
            if(!minWidth || c.width < minWidth) minWidth = c.width;
          }
          const Channel &c = channelLayout[maxOffsetIndex];
          bitsPerPixel = c.offset + (c.width ? c.width : minWidth ? minWidth : 1);
        }
        complete.pixelSize = formatType == packed ?
          (numberOfChannels - 1) / complete.bitsPerWord + 1 : numberOfChannels;
        break;
      }
cerr << "PixelFormat::getExpandedFormat: pixelSize: " << complete.pixelSize << " " << (complete.formatType == tight ? "bits" : "words") << endl;


      // Determine channel layout
      if(channelLayout.empty())
      {
        complete.channelLayout.resize(numberOfChannels);
        switch(formatType)
        {
        case direct:
          if(complete.pixelSize < numberOfChannels)
            ARCHON_THROW1(InconsistencyException, "Words per pixel less than number of channels for direct format");
          for(int i=0; i<numberOfChannels; ++i)
          {
            Channel &c = complete.channelLayout[i];
            c.offset = i;
            c.width  = complete.bitsPerWord;
          }
          break;

        case packed:
          if(complete.pixelSize*complete.bitsPerWord < numberOfChannels)
            ARCHON_THROW1(InconsistencyException, "Bits per pixel less than number of channels for packed format");
          {
            int o = 0;
            int w = complete.pixelSize*complete.bitsPerWord / numberOfChannels;
            for(int i=0; i<numberOfChannels; ++i)
            {
              Channel &c = complete.channelLayout[i];
              c.offset = o;
              c.width  = w;
              o += w;
            }
          }
          break;

        case tight:
          if(complete.pixelSize < numberOfChannels)
            ARCHON_THROW1(InconsistencyException, "Bits per pixel less than number of channels for tight format");
          {
            int o = 0;
            int w = complete.pixelSize / numberOfChannels;
            for(int i=0; i<numberOfChannels; ++i)
            {
              Channel &c = complete.channelLayout[i];
              c.offset = o;
              c.width  = w;
              o += w;
            }
          }
          break;
        }
      }
      else
      {
        vector<int> v(formatType == packed ? complete.pixelSize*complete.bitsPerWord : complete.pixelSize, -1);
        for(int i=0; i<numberOfChannels; ++i)
        {
          int o = channelLayout[i].offset;
          if(o < 0 || static_cast<int>(v.size()) <= o) ARCHON_THROW1(InconsistencyException, "Channel "+Text::toString(i)+" offset escapes pixel boundary");
          int &w = v[o];
          if(w != -1) ARCHON_THROW1(InconsistencyException, "Multiple channels at offset "+Text::toString(o));
          w = i;
        }
        complete.channelLayout = channelLayout;
        int maxIntBits = sizeof(MaxInt)*numeric_limits<unsigned char>::digits;
        for(int i=0; i<numberOfChannels; ++i)
        {
          Channel &c = complete.channelLayout[i];
          int &w = c.width;
          if(w < 0) ARCHON_THROW1(InconsistencyException, "Channel "+Text::toString(i)+" width negative");
          if(maxIntBits < w) ARCHON_THROW1(InconsistencyException, "Channel "+Text::toString(i)+" too wide for your CPU architecture");
          if(w && wordTypeDescriptor.isFloat && w != bitsPerWord) ARCHON_THROW1(InconsistencyException, "Channel "+Text::toString(i)+" width differs from word width for floating point channel");
          switch(formatType)
          {
          case direct:
            // Allow one word per channel
            if(!w) w = complete.bitsPerWord;
            else if(complete.bitsPerWord < w) ARCHON_THROW1(InconsistencyException, "Channel "+Text::toString(i)+" wider than word type for direct format");
            break;

          case packed:
          case tight:
            // Allow all bits up to next channel
            int j = c.offset+1;
            while(j < static_cast<int>(v.size()) && v[j] == -1) ++j;
            int maxWidth = j - c.offset;
            if(maxIntBits < maxWidth) maxWidth = maxIntBits;
            if(!w) w = maxWidth;
            else if(maxWidth <= w)
            {
              if(j == static_cast<int>(v.size()))
                ARCHON_THROW1(InconsistencyException, "Channel "+Text::toString(i)+" too wide - extends beyond pixel boundary");
              else ARCHON_THROW1(InconsistencyException, "Channel "+
                                 Text::toString(i)+" too wide - overlaps "
                                 "next channel ("+Text::toString(v[j])+")");
            }
            break;
          }
        }
      }
cerr << "PixelFormat::getExpandedFormat: channelLayout:";
for(int i=0; i<static_cast<int>(complete.channelLayout.size()); ++i)
{
  cerr << " (" << complete.channelLayout[i].offset << ", " << complete.channelLayout[i].width << ")";
}
cerr << endl;


      // Determine color scheme
      if(colorScheme == implied)
      {
        switch(numberOfChannels)
        {
        case 1:
          complete.colorScheme     = luminance;
          complete.hasAlphaChannel = false;
          break;

        case 2:
          complete.colorScheme     = luminance;
          complete.hasAlphaChannel = true;
          break;

        case 3:
          complete.colorScheme     = rgb;
          complete.hasAlphaChannel = false;
          break;

        case 4:
          complete.colorScheme     = rgb;
          complete.hasAlphaChannel = true;
          break;

        default:
          complete.colorScheme     = custom;
          complete.hasAlphaChannel = false;
          break;
        }
      }
      else
      {
        complete.colorScheme     = colorScheme;
        complete.hasAlphaChannel = hasAlphaChannel;
      }
cerr << "PixelFormat::getExpandedFormat: colorScheme: " << (complete.colorScheme == luminance ? "luminance" :
                                                            complete.colorScheme == rgb ? "rgb" :
                                                            complete.colorScheme == hsv ? "hsv" :
                                                            complete.colorScheme == custom ? "custom" : "implied") << endl;
cerr << "PixelFormat::getExpandedFormat: hasAlphaChannel: " << complete.hasAlphaChannel << endl;


      return complete;
    }


    PixelFormat PixelFormat::getReducedFormat() const
      throw(UnsupportedWordTypeException, InconsistencyException)
    {
      PixelFormat expanded = getExpandedFormat();
      PixelFormat reduced = expanded;

      // Remove channel widths  if equal to inferred
      for(int i=0; i<static_cast<int>(reduced.channelLayout.size()); ++i)
      {
        PixelFormat f = reduced;
        f.channelLayout[i].width = 0;
        if(f.getExpandedFormat() == expanded) reduced = f;
      }

      // Remove channel layout if equal to inferred
      {
        PixelFormat f = reduced;
        f.channelLayout.clear();
        if(f.getExpandedFormat() == expanded) reduced = f;
      }

      // Remove color-schema if equal to inferred
      {
        PixelFormat f = reduced;
        f.colorScheme = implied;
        f.hasAlphaChannel = false;
        if(f.getExpandedFormat() == expanded) reduced = f;
      }

      // Remove pixel size if equal to inferred
      {
        PixelFormat f = reduced;
        f.pixelSize = 0;
        if(f.getExpandedFormat() == expanded) reduced = f;
      }

      // Translate to custom word type for portability
      reduced.wordType = getWordTypeDescriptor(expanded.wordType).isFloat ?
        custom_float : custom_int;

      return reduced;
    }


    string PixelFormat::toString() const
    {
      PixelFormat expanded = getExpandedFormat();
      PixelFormat reduced = expanded.getReducedFormat();
      string s = expanded.formatType == packed ? "packed" :
        expanded.formatType == tight ? "tight" : "direct";

      s += "_";
      s += reduced.wordType == custom_int ? "int" +
        Text::toString(expanded.bitsPerWord) :
        reduced.wordType == custom_float ? "float" +
        Text::toString(expanded.bitsPerWord) :
        getWordTypeDescriptor(reduced.wordType).tag;

      s += "_";
      if(reduced.channelLayout.empty() && reduced.colorScheme == custom)
      {
        // For straight layouts of custom channels
        s += Text::toString(reduced.pixelSize);
        if(expanded.hasAlphaChannel) s += "a";
      }
      else
      {
        vector<int> channelMap(expanded.formatType == packed ?
                               expanded.pixelSize*expanded.bitsPerWord :
                               expanded.pixelSize, -1);
        for(int i=0; i<static_cast<int>(expanded.channelLayout.size()); ++i)
          channelMap[expanded.channelLayout[i].offset] = i;

        vector<string> colorMap;
        switch(expanded.colorScheme)
        {
        case implied: // Never
          break;

        case custom:
          {
            int n = expanded.channelLayout.size();
            if(expanded.hasAlphaChannel) --n;
            for(int i=0; i<n; ++i) colorMap.push_back(Text::toString(i+1)+"c");
          }
          break;

        case luminance:
          colorMap.push_back("l");
          break;

        case rgb:
          colorMap.push_back("r");
          colorMap.push_back("g");
          colorMap.push_back("b");
          break;

        case hsv:
          colorMap.push_back("h");
          colorMap.push_back("s");
          colorMap.push_back("v");
          break;
        }
        colorMap.push_back("a");


        // Can we use the condensed channel layout
        bool condensedLayout = expanded.colorScheme != custom;
        if(condensedLayout)
        {
          // Detect precense of unused fields
          if(expanded.formatType == direct)
          {
            for(int i=0; i<static_cast<int>(channelMap.size()); ++i) if(channelMap[i] < 0)
            {
              condensedLayout = false;
              break;
            }
          }
          else // Packed and tight formats
          {
            int i=0;
            while(i < static_cast<int>(channelMap.size()))
            {
              int gapSize = 0;
              while(i+gapSize < static_cast<int>(channelMap.size()) && channelMap[i+gapSize] < 0) ++gapSize;
              if(gapSize)
              {
                // Do not output a small explicit final gaps for packed formats since pixels word-align anyway
                if(i == static_cast<int>(channelMap.size()) && gapSize < expanded.bitsPerWord && expanded.formatType == packed) break;

                condensedLayout = false;
                break;
              }

              i += expanded.channelLayout[channelMap[i]].width;;
            }
          }
        }


        // Generate channel layout
        if(expanded.formatType == direct)
        {
          for(int i=0; i<static_cast<int>(channelMap.size()); ++i)
          {
            if(i && !condensedLayout) s += "_";
            int j = channelMap[i];
            s += j < 0 ? "z" : colorMap[j];
            if(reduced.channelLayout.size())
            {
              int w = reduced.channelLayout[j].width;
              if(w) s+= Text::toString(w);
            }
          }
        }
        else // Packed and tight formats
        {
          int i=0;
          while(i < static_cast<int>(channelMap.size()))
          {
            // Is there a gap of unused bit here
            int w = 0;
            while(i+w < static_cast<int>(channelMap.size()) && channelMap[i+w] < 0) ++w;
            if(w)
            {
              // Do not output a small explicit final gaps for packed formats since pixels word-align anyway
              if(i == static_cast<int>(channelMap.size()) && w < expanded.bitsPerWord && expanded.formatType == packed) break;

              if(i && !condensedLayout) s += "_";
              s += Text::toString(w);
            }
            else // No gap this time
            {
              if(i && !condensedLayout) s += "_";
              int j = channelMap[i];
              w = expanded.channelLayout[j].width;
              s += colorMap[j] + Text::toString(w);
            }
            i += w;
          }
        }
      }

      if(mostSignificantBitsFirst) s += "_msb";
      return s;
    }
  }
}

---