image_data.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/image_data.H>


namespace Archon
{
  namespace Utilities
  {
    /*
     * The objective for this constructor is to transform the
     * specified set of input parameters into a new set of parameters
     * that will minimize the number of calculations required by the
     * pixel data accessor methods of this class.
     */
    ImageData::ImageData(void *buffer, int numberOfStrips, int pixelsPerStrip,
                         const PixelFormat &pixelFormat,
                         const BufferFormat &bufferFormat,
                         int left, int bottom, int width, int height,
                         const vector<bool> &endianness)
      throw(PixelFormat::UnsupportedWordTypeException,
            PixelFormat::InconsistencyException, invalid_argument):
      buffer(reinterpret_cast<char *>(buffer)),
      rightToLeft(bufferFormat.rightToLeft),
      topToBottom(bufferFormat.topToBottom),
      verticalStrips(bufferFormat.verticalStrips)
    {
      PixelFormat expandedPixelFormat = pixelFormat.getExpandedFormat();

      // Determine pixel format type
      pixelFormatType = expandedPixelFormat.formatType;

      // Determine word type
      wordType = expandedPixelFormat.wordType;
cerr << "ImageData::ImageData: word type: " << wordType << endl;

      // Determine number of bits and bytes per word
      bitsPerWord = expandedPixelFormat.bitsPerWord;
cerr << "ImageData::ImageData: bits per word: " << bitsPerWord << endl;
      bytesPerWord = bitsPerWord / numeric_limits<unsigned char>::digits;
cerr << "ImageData::ImageData: bytes per word: " << bytesPerWord << endl;

      // Determine byte permutation unless the requested endianness is
      // compatible with the native endianess up through the relevant
      // levels.
      {
        int levels = findMostSignificantBit(bytesPerWord);
cerr << "ImageData::ImageData: byte order levels: " << levels << endl;
        if(!compareEndianness(endianness, vector<bool>(), levels))
          bytePermutation = computeBytePermutation(endianness, levels);
if(bytePermutation.empty()) cerr << "ImageData::ImageData: Using native endianess" << endl;
else
{
  cerr << "ImageData::ImageData: byte reorder map:";
  for(int i=0; i<static_cast<int>(bytePermutation.size()); ++i) cerr << " " << bytePermutation[i];
  cerr << endl;
}
      }

      mostSignificantBitsFirst = expandedPixelFormat.mostSignificantBitsFirst;

      // Determine number of channels
      numberOfChannels = expandedPixelFormat.channelLayout.size();

      // Determine bits per pixel
      bitsPerPixel = pixelFormatType == PixelFormat::tight ? expandedPixelFormat.pixelSize : expandedPixelFormat.pixelSize * bitsPerWord;

      // Compute memory field list
      vector<int> memoryMap(pixelFormatType == PixelFormat::direct ? expandedPixelFormat.pixelSize : bitsPerPixel);
      for(int i=0; i<numberOfChannels; ++i) memoryMap[expandedPixelFormat.channelLayout[i].offset] = i;
      if(pixelFormatType == PixelFormat::direct)
      {
        for(int i=0; i<static_cast<int>(memoryMap.size()); ++i)
        {
          int j = memoryMap[i];
          if(j < 0)
          {
            memoryFields.push_back(MemoryField());
            continue;
          }
          memoryFields.push_back(MemoryField(j, expandedPixelFormat.channelLayout[j].width));
        }
      }
      else // packed and tight formats
      {
        int i=0;
        while(i < static_cast<int>(memoryMap.size()))
        {
          int j = -1;
          int w = 0;
          // Check for a gap of unused bit
          while(i+w < static_cast<int>(memoryMap.size()) && memoryMap[i+w] < 0) ++w;
          if(!w) // No gap this time
          {
            j = memoryMap[i];
            w = expandedPixelFormat.channelLayout[j].width;
          }
          memoryFields.push_back(MemoryField(j, w));
          i += w;
        }
      }
cerr << "ImageData::ImageData: pixel fields:";
for(int i=0; i<static_cast<int>(memoryFields.size()); ++i)
{
  cerr << " (" << memoryFields[i].channelIndex << ", " << memoryFields[i].bitWidth << ")";
}
cerr << endl;


      // Determine number of bits between strips (the stride)
      {
        bitsPerStrip = bitsPerPixel * pixelsPerStrip;
        if(bufferFormat.wordAlignStrip)
        {
          long r = bitsPerStrip % bitsPerWord;
          if(r) bitsPerStrip += bitsPerWord-r;
        }
cerr << "ImageData::ImageData: bits per strip: " << bitsPerStrip << endl;
      }


      // Determine the width and height of the frame of interest
      int fullWidth  = verticalStrips ? numberOfStrips : pixelsPerStrip;
      int fullHeight = verticalStrips ? pixelsPerStrip : numberOfStrips;
      interestWidth  = width  ? width  : fullWidth  - left;
      interestHeight = height ? height : fullHeight - bottom;
cerr << "ImageData::ImageData: width  of interest frame: " << interestWidth  << endl;
cerr << "ImageData::ImageData: height of interest frame: " << interestHeight << endl;


      // Determine the offset of the pricipal bit. The principal bit
      // is the bit with the lowest bit-level index of all the bits
      // that are part of pixels that fall withing the selected
      // sub-section of the underlaying pixel buffer. Bit-level
      // indexes increases with significance of pit position.
      {
        int x = rightToLeft ? fullWidth  - interestWidth  - left   : left;
        int y = topToBottom ? fullHeight - interestHeight - bottom : bottom;
        if(verticalStrips) swap(x, y);
        principalBitOffset = x * bitsPerPixel + y * bitsPerStrip;
cerr << "ImageData::ImageData: principal bit offset: " << principalBitOffset << endl;
      }
    }

    template<typename T> inline void
    ImageData::unpackPixelSequenceDirectInteger(const char *data,
                                                long n,
                                                long double *pixels) const
    {
      int m = memoryFields.size();
      const T *p = reinterpret_cast<const T *>(data);
      for(int i=0; i<n; ++i) // For each requested pixel
      {
        for(int j=0; j<m; ++j)
        {
          const ImageData::MemoryField &f = memoryFields[j];
          if(f.channelIndex < 0) continue;
          PixelFormat::MaxInt v = p[j];
          if(mostSignificantBitsFirst) v >>= bitsPerWord-f.bitWidth;
          pixels[f.channelIndex] = static_cast<long double>(v & f.bitMask)/f.bitMask;
        }
        pixels += numberOfChannels;
        p += m;
      }
    }

    template<typename T> inline void
    ImageData::unpackPixelSequenceDirectFloat(const char *data,
                                              long n,
                                              long double *pixels) const
    {
      int m = memoryFields.size();
      const T *p = reinterpret_cast<const T *>(data);
      for(int i=0; i<n; ++i) // For each requested pixel
      {
        for(int j=0; j<m; ++j)
        {
          const ImageData::MemoryField &f = memoryFields[j];
          if(f.channelIndex < 0) continue;
          pixels[f.channelIndex] = (static_cast<long double>(p[j])-f.min)/(f.max-f.min);
        }
        pixels += numberOfChannels;
        p += m;
      }
    }

    void ImageData::decodePixelSequence(const char *data, int bitOffset,
                                        long n, long double *pixels) const
    {
      switch(pixelFormatType)
      {
      case PixelFormat::direct:
        switch(wordType)
        {
        case PixelFormat::std_char:
          unpackPixelSequenceDirectInteger<unsigned char>(data, n, pixels);
          return;

        case PixelFormat::std_short:
          unpackPixelSequenceDirectInteger<unsigned short>(data, n, pixels);
          return;

        case PixelFormat::std_int:
          unpackPixelSequenceDirectInteger<unsigned int>(data, n, pixels);
          return;

        case PixelFormat::std_long:
          unpackPixelSequenceDirectInteger<unsigned long>(data, n, pixels);
          return;

        case PixelFormat::std_max_int:
          unpackPixelSequenceDirectInteger<PixelFormat::MaxInt>(data, n, pixels);
          return;

        case PixelFormat::std_float:
          unpackPixelSequenceDirectFloat<float>(data, n, pixels);
          return;
          
        case PixelFormat::std_double:
          unpackPixelSequenceDirectFloat<double>(data, n, pixels);
          return;

        case PixelFormat::std_long_double:
          unpackPixelSequenceDirectFloat<long double>(data, n, pixels);
          return;

        default: return; // Never
        }

      default: // packed and tight pixel format types
        unpackPixelSequence(data, bitOffset, n, pixels);
      }
    }

    void ImageData::unpackPixelSequence(const char *data, int wordBitOffset,
                                        long n, long double *pixels) const
    {
      vector<MemoryField>::const_iterator field = memoryFields.end()-1;

      // Skip initial unused bit fields
      int bitAdvance = 0;
      for(;;)
      {
        if(field == memoryFields.end())
        {
          if(!--n) return;
          field = memoryFields.begin();
        }
        if(field->channelIndex < 0) bitAdvance += field->bitWidth;
        ++field;
      }
      long wordAdvance;
      wordBitOffset = Math::modulo(wordBitOffset + bitAdvance, bitsPerWord, wordAdvance);
      if(wordAdvance) data += bytesPerWord * wordAdvance;

      // Load the first word from memory
      PixelFormat::MaxInt word = readIntegerWord(data);

      // Prepare for assembly of first channel
      int channelBitWidth = field->bitWidth;
      int channelBitOffset = 0;
      PixelFormat::MaxInt channel = 0;

      // Iterate over channels
      for(;;)
      {
        // Iterate over bit chunk transfers
        for(;;)
        {
          // The number of unparsed bits remaining in the current input word
          int remainingWordBits = bitsPerWord - wordBitOffset;
          int remainingChannelBits = channelBitWidth - channelBitOffset;

          // The number of bits we can transfer as one chunk
          int m = min(remainingWordBits, remainingChannelBits);

          // Transfer m bits from word to channel (special trick to
          // support shifts by N bits where N is the number of bits in
          // PixelFormat::MaxInt)
          PixelFormat::MaxInt mask = (static_cast<PixelFormat::MaxInt>(1)<<m-1<<1) - 1;
          if(mostSignificantBitsFirst) channel |= (word>>remainingWordBits-m & mask) << remainingChannelBits-m;
          else channel |= (word>>wordBitOffset & mask) << channelBitOffset;
          channelBitOffset += m;

          // Is the channel complete
          if(channelBitWidth == channelBitOffset) break;

          // Do we have more unused bits in current word
          if(m < remainingWordBits)
          {
            wordBitOffset += m;
            continue;
          }

          // Advance to next word of the image data
          data += bytesPerWord;
          word = readIntegerWord(data);
          wordBitOffset = 0;
        }

        // Store completed channel
        pixels[field->channelIndex] = static_cast<long double>(channel)/field->bitMask;


        // Skip unused bit fields
        bitAdvance = 0;
        for(;;)
        {
          if(++field == memoryFields.end())
          {
            if(!--n) return;
            field = memoryFields.begin();
          }
          if(field->channelIndex < 0) bitAdvance += field->bitWidth;
        }
        if(bitAdvance)
        {
          wordBitOffset = Math::modulo(wordBitOffset + bitAdvance, bitsPerWord, wordAdvance);
          if(wordAdvance)
          {
            data += bytesPerWord * wordAdvance;

            // Load the next word from memory
            word = readIntegerWord(data);
          }
        }

        // Prepare for assembly of next channel
        channelBitWidth = field->bitWidth;
        channelBitOffset = 0;
        channel = 0;
      }
    }
  }
}

---