/*****************************************************************************/

// Copyright 2006-2008 Adobe Systems Incorporated

// All Rights Reserved.

//

// NOTICE:  Adobe permits you to use, modify, and distribute this file in

// accordance with the terms of the Adobe license agreement accompanying it.

/*****************************************************************************/

/* $Id: //mondo/dng_sdk_1_4/dng_sdk/source/dng_pixel_buffer.h#1 $ */ 

/* $DateTime: 2012/05/30 13:28:51 $ */

/* $Change: 832332 $ */

/* $Author: tknoll $ */

/** \file

 * Support for holding buffers of sample data.

 */

/*****************************************************************************/

#ifndef __dng_pixel_buffer__

#define __dng_pixel_buffer__

/*****************************************************************************/

#include "dng_assertions.h"

#include "dng_rect.h"

#include "dng_safe_arithmetic.h"

#include "dng_tag_types.h"

/*****************************************************************************/

/// Compute best set of step values for a given source and destination area and stride.

void OptimizeOrder (const void *&sPtr,

          void *&dPtr,

          uint32 sPixelSize,

          uint32 dPixelSize,

          uint32 &count0,

          uint32 &count1,

          uint32 &count2,

          int32 &sStep0,

          int32 &sStep1,

          int32 &sStep2,

          int32 &dStep0,

          int32 &dStep1,

          int32 &dStep2);

void OptimizeOrder (const void *&sPtr,

          uint32 sPixelSize,

          uint32 &count0,

          uint32 &count1,

          uint32 &count2,

          int32 &sStep0,

          int32 &sStep1,

          int32 &sStep2);

void OptimizeOrder (void *&dPtr,

          uint32 dPixelSize,

          uint32 &count0,

          uint32 &count1,

          uint32 &count2,

          int32 &dStep0,

          int32 &dStep1,

          int32 &dStep2);

/*****************************************************************************/

#define qDebugPixelType 0

#if qDebugPixelType

#define ASSERT_PIXEL_TYPE(typeVal) CheckPixelType (typeVal)

#else

#define ASSERT_PIXEL_TYPE(typeVal) DNG_ASSERT (fPixelType == typeVal, "Pixel type access mismatch")

#endif

/*****************************************************************************/

/// \brief Holds a buffer of pixel data with "pixel geometry" metadata.

///

/// The pixel geometry describes the layout in terms of how many planes, rows and columns

/// plus the steps (in bytes) between each column, row and plane.

class dng_pixel_buffer

  {

  public:

    // Area this buffer holds.

    dng_rect fArea;

    // Range of planes this buffer holds.

    uint32 fPlane;

    uint32 fPlanes;

    // Steps between pixels.

    int32 fRowStep;

    int32 fColStep;

    int32 fPlaneStep;

    // Basic pixel type (TIFF tag type code).

    uint32 fPixelType;

    // Size of pixel type in bytes.

    uint32 fPixelSize;

    // Pointer to buffer's data.

    void *fData;

    // Do we have write-access to this data?

    bool fDirty;

  private:

    void * InternalPixel (int32 row,

                int32 col,

                    uint32 plane = 0) const

      {

      // Ensure pixel to be accessed lies inside valid area.

      if (row < fArea.t || row >= fArea.b ||

        col < fArea.l || col >= fArea.r ||

        plane < fPlane || (plane - fPlane) >= fPlanes)

        {

        ThrowProgramError ("Out-of-range pixel access");

        }

      // Compute offset of pixel.

      const int64 rowOffset = SafeInt64Mult(fRowStep,

        static_cast<int64> (row) - static_cast<int64> (fArea.t));

      const int64 colOffset = SafeInt64Mult(fColStep,

        static_cast<int64> (col) - static_cast<int64> (fArea.l));

      const int64 planeOffset = SafeInt64Mult(fPlaneStep,

        static_cast<int64> (plane - fPlane));

      const int64 offset = SafeInt64Mult(static_cast<int64>(fPixelSize),

        SafeInt64Add(SafeInt64Add(rowOffset, colOffset), planeOffset));

      // Add offset to buffer base address.

      return static_cast<void *> (static_cast<uint8 *> (fData) + offset);

      }

    #if qDebugPixelType

    void CheckPixelType (uint32 pixelType) const;

    #endif

  public:

    dng_pixel_buffer ();

    /// Note: This constructor is for internal use only and should not be

    /// considered part of the DNG SDK API.

    ///

    /// Initialize the pixel buffer according to the given parameters (see

    /// below). May throw an error if arithmetic overflow occurs when

    /// computing the row, column or plane step, or if an invalid value was

    /// passed for planarConfiguration.

    ///

    /// \param size Area covered by the pixel buffer

    /// \param plane Index of the first plane

    /// \param planes Number of planes

    /// \param pixelType Pixel data type (one of the values defined in

    ///        dng_tag_types.h)

    /// \param planarConfiguration Layout of the pixel planes in memory: One

    ///        of pcInterleaved, pcPlanar, or pcRowInterleaved (defined in

    ///        dng_tag_values.h)

    /// \param data Pointer to the pixel data

    dng_pixel_buffer (const dng_rect &area, uint32 plane, uint32 planes,

              uint32 pixelType, uint32 planarConfiguration,

              void *data);

    dng_pixel_buffer (const dng_pixel_buffer &buffer);

    dng_pixel_buffer & operator= (const dng_pixel_buffer &buffer);

    virtual ~dng_pixel_buffer ();

    /// Get the range of pixel values.

    /// \retval Range of value a pixel can take. (Meaning [0, max] for unsigned case. Signed case is biased so [-32768, max - 32768].)

    uint32 PixelRange () const;

    /// Get extent of pixels in buffer

    /// \retval Rectangle giving valid extent of buffer.

    const dng_rect & Area () const

      {

      return fArea;

      }

    /// Number of planes of image data.

    /// \retval Number of planes held in buffer.

    uint32 Planes () const

      {

      return fPlanes;

      }

    /// Step, in pixels not bytes, between rows of data in buffer.

    /// \retval row step in pixels. May be negative.

    int32 RowStep () const

      {

      return fRowStep;

      }

    /// Step, in pixels not bytes, between planes of data in buffer.

    /// \retval plane step in pixels. May be negative.

    int32 PlaneStep () const

      {

      return fPlaneStep;

      }

    /// Get read-only untyped (void *) pointer to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as void *.

    const void * ConstPixel (int32 row,

                   int32 col,

                   uint32 plane = 0) const

      {

      return InternalPixel (row, col, plane);

      }

    /// Get a writable untyped (void *) pointer to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as void *.

    void * DirtyPixel (int32 row,

                 int32 col,

                 uint32 plane = 0)

      {

      DNG_ASSERT (fDirty, "Dirty access to const pixel buffer");

      return InternalPixel (row, col, plane);

      }

    /// Get read-only uint8 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as uint8 *.

    const uint8 * ConstPixel_uint8 (int32 row,

                    int32 col,

                    uint32 plane = 0) const

      {

      ASSERT_PIXEL_TYPE (ttByte);

      return (const uint8 *) ConstPixel (row, col, plane);

      }

    /// Get a writable uint8 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as uint8 *.

    uint8 * DirtyPixel_uint8 (int32 row,

                  int32 col,

                  uint32 plane = 0)

      {

      ASSERT_PIXEL_TYPE (ttByte);

      return (uint8 *) DirtyPixel (row, col, plane);

      }

    /// Get read-only int8 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as int8 *.

    const int8 * ConstPixel_int8 (int32 row,

                    int32 col,

                    uint32 plane = 0) const

      {

      ASSERT_PIXEL_TYPE (ttSByte);

      return (const int8 *) ConstPixel (row, col, plane);

      }

    /// Get a writable int8 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as int8 *.

    int8 * DirtyPixel_int8 (int32 row,

                int32 col,

                uint32 plane = 0)

      {

      ASSERT_PIXEL_TYPE (ttSByte);

      return (int8 *) DirtyPixel (row, col, plane);

      }

    /// Get read-only uint16 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as uint16 *.

    const uint16 * ConstPixel_uint16 (int32 row,

                      int32 col,

                      uint32 plane = 0) const

      {

      ASSERT_PIXEL_TYPE (ttShort);

      return (const uint16 *) ConstPixel (row, col, plane);

      }

    /// Get a writable uint16 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as uint16 *.

    uint16 * DirtyPixel_uint16 (int32 row,

                    int32 col,

                    uint32 plane = 0)

      {

      ASSERT_PIXEL_TYPE (ttShort);

      return (uint16 *) DirtyPixel (row, col, plane);

      }

    /// Get read-only int16 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as int16 *.

    const int16 * ConstPixel_int16 (int32 row,

                    int32 col,

                    uint32 plane = 0) const

      {

      ASSERT_PIXEL_TYPE (ttSShort);

      return (const int16 *) ConstPixel (row, col, plane);

      }

    /// Get a writable int16 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as int16 *.

    int16 * DirtyPixel_int16 (int32 row,

                  int32 col,

                  uint32 plane = 0)

      {

      ASSERT_PIXEL_TYPE (ttSShort);

      return (int16 *) DirtyPixel (row, col, plane);

      }

    /// Get read-only uint32 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as uint32 *.

    const uint32 * ConstPixel_uint32 (int32 row,

                      int32 col,

                      uint32 plane = 0) const

      {

      ASSERT_PIXEL_TYPE (ttLong);

      return (const uint32 *) ConstPixel (row, col, plane);

      }

    /// Get a writable uint32 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as uint32 *.

    uint32 * DirtyPixel_uint32 (int32 row,

                    int32 col,

                    uint32 plane = 0)

      {

      ASSERT_PIXEL_TYPE (ttLong);

      return (uint32 *) DirtyPixel (row, col, plane);

      }

    /// Get read-only int32 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as int32 *.

    const int32 * ConstPixel_int32 (int32 row,

                    int32 col,

                    uint32 plane = 0) const

      {

      ASSERT_PIXEL_TYPE (ttSLong);

      return (const int32 *) ConstPixel (row, col, plane);

      }

    /// Get a writable int32 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as int32 *.

    int32 * DirtyPixel_int32 (int32 row,

                  int32 col,

                  uint32 plane = 0)

      {

      ASSERT_PIXEL_TYPE (ttSLong);

      return (int32 *) DirtyPixel (row, col, plane);

      }

    /// Get read-only real32 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as real32 *.

    const real32 * ConstPixel_real32 (int32 row,

                      int32 col,

                      uint32 plane = 0) const

      {

      ASSERT_PIXEL_TYPE (ttFloat);

      return (const real32 *) ConstPixel (row, col, plane);

      }

    /// Get a writable real32 * to pixel data starting at a specific pixel in the buffer.

    /// \param row Start row for buffer pointer.

    /// \param col Start column for buffer pointer.

    /// \param plane Start plane for buffer pointer.

    /// \retval Pointer to pixel data as real32 *.

    real32 * DirtyPixel_real32 (int32 row,

                  int32 col,

                  uint32 plane = 0)

      {

      ASSERT_PIXEL_TYPE (ttFloat);

      return (real32 *) DirtyPixel (row, col, plane);

      }

    /// Initialize a rectangular area of pixel buffer to a constant.

    /// \param area Rectangle of pixel buffer to set.

    /// \param plane Plane to start filling on.

    /// \param planes Number of planes to fill.

    /// \param value Constant value to set pixels to.

    void SetConstant (const dng_rect &area,

                uint32 plane,

                uint32 planes,

                uint32 value);

    /// Initialize a rectangular area of pixel buffer to a constant unsigned 8-bit value.

    /// \param area Rectangle of pixel buffer to set.

    /// \param plane Plane to start filling on.

    /// \param planes Number of planes to fill.

    /// \param value Constant uint8 value to set pixels to.

    void SetConstant_uint8 (const dng_rect &area,

                uint32 plane,

                uint32 planes,

                uint8 value)

      {

      DNG_ASSERT (fPixelType == ttByte, "Mismatched pixel type");

      SetConstant (area, plane, planes, (uint32) value);

      }

    /// Initialize a rectangular area of pixel buffer to a constant unsigned 16-bit value.

    /// \param area Rectangle of pixel buffer to set.

    /// \param plane Plane to start filling on.

    /// \param planes Number of planes to fill.

    /// \param value Constant uint16 value to set pixels to.

    void SetConstant_uint16 (const dng_rect &area,

                 uint32 plane,

                 uint32 planes,

                 uint16 value)

      {

      DNG_ASSERT (fPixelType == ttShort, "Mismatched pixel type");

      SetConstant (area, plane, planes, (uint32) value);

      }

    /// Initialize a rectangular area of pixel buffer to a constant signed 16-bit value.

    /// \param area Rectangle of pixel buffer to set.

    /// \param plane Plane to start filling on.

    /// \param planes Number of planes to fill.

    /// \param value Constant int16 value to set pixels to.

    void SetConstant_int16 (const dng_rect &area,

                uint32 plane,

                uint32 planes,

                int16 value)

      {

      DNG_ASSERT (fPixelType == ttSShort, "Mismatched pixel type");

      SetConstant (area, plane, planes, (uint32) (uint16) value);

      }

    /// Initialize a rectangular area of pixel buffer to a constant unsigned 32-bit value.

    /// \param area Rectangle of pixel buffer to set.

    /// \param plane Plane to start filling on.

    /// \param planes Number of planes to fill.

    /// \param value Constant uint32 value to set pixels to.

    void SetConstant_uint32 (const dng_rect &area,

                 uint32 plane,

                 uint32 planes,

                 uint32 value)

      {

      DNG_ASSERT (fPixelType == ttLong, "Mismatched pixel type");

      SetConstant (area, plane, planes, value);

      }

    /// Initialize a rectangular area of pixel buffer to a constant real 32-bit value.

    /// \param area Rectangle of pixel buffer to set.

    /// \param plane Plane to start filling on.

    /// \param planes Number of planes to fill.

    /// \param value Constant real32 value to set pixels to.

    void SetConstant_real32 (const dng_rect &area,

                 uint32 plane,

                 uint32 planes,

                 real32 value)

      {

      DNG_ASSERT (fPixelType == ttFloat, "Mismatched pixel type");

      union

        {

        uint32 i;

        real32 f;

        } x;

      x.f = value;

      SetConstant (area, plane, planes, x.i);

      }

    /// Initialize a rectangular area of pixel buffer to zeros.

    /// \param area Rectangle of pixel buffer to zero.

    /// \param area Area to zero

    /// \param plane Plane to start filling on.

    /// \param planes Number of planes to fill.

    void SetZero (const dng_rect &area,

            uint32 plane,

            uint32 planes);

    /// Copy image data from an area of one pixel buffer to same area of another.

    /// \param src Buffer to copy from.

    /// \param area Rectangle of pixel buffer to copy.

    /// \param srcPlane Plane to start copy in src.

    /// \param dstPlane Plane to start copy in dst.

    /// \param planes Number of planes to copy.

    void CopyArea (const dng_pixel_buffer &src,

             const dng_rect &area,

             uint32 srcPlane,

             uint32 dstPlane,

             uint32 planes);

    /// Copy image data from an area of one pixel buffer to same area of another.

    /// \param src Buffer to copy from.

    /// \param area Rectangle of pixel buffer to copy.

    /// \param plane Plane to start copy in src and this.

    /// \param planes Number of planes to copy.

    void CopyArea (const dng_pixel_buffer &src,

             const dng_rect &area,

             uint32 plane,

             uint32 planes)

      {

      CopyArea (src, area, plane, plane, planes);

      }

    /// Calculate the offset phase of destination rectangle relative to source rectangle.

    /// Phase is based on a 0,0 origin and the notion of repeating srcArea across dstArea.

    /// It is the number of pixels into srcArea to start repeating from when tiling dstArea.

    /// \retval dng_point containing horizontal and vertical phase.

    static dng_point RepeatPhase (const dng_rect &srcArea,

                        const dng_rect &dstArea);

    /// Repeat the image data in srcArea across dstArea.

    /// (Generally used for padding operations.)

    /// \param srcArea Area to repeat from.

    /// \param dstArea Area to fill with data from srcArea.

    void RepeatArea (const dng_rect &srcArea,

             const dng_rect &dstArea);

    /// Replicates a sub-area of a buffer to fill the entire buffer.

    void RepeatSubArea (const dng_rect subArea,

                uint32 repeatV = 1,

                uint32 repeatH = 1);

    /// Apply a right shift (C++ oerpator >>) to all pixel values. Only implemented for 16-bit (signed or unsigned) pixel buffers.

    /// \param shift Number of bits by which to right shift each pixel value.

    void ShiftRight (uint32 shift);

    /// Change metadata so pixels are iterated in opposite horizontal order.

    /// This operation does not require movement of actual pixel data.

    void FlipH ();

    /// Change metadata so pixels are iterated in opposite vertical order.

    /// This operation does not require movement of actual pixel data.

    void FlipV ();

    /// Change metadata so pixels are iterated in opposite plane order.

    /// This operation does not require movement of actual pixel data.

    void FlipZ ();  // Flip planes

    /// Return true if the contents of an area of the pixel buffer area are the same as those of another.

    /// \param rhs Buffer to compare against.

    /// \param area Rectangle of pixel buffer to test.

    /// \param plane Plane to start comparing.

    /// \param planes Number of planes to compare.

    /// \retval bool true if areas are equal, false otherwise.

    bool EqualArea (const dng_pixel_buffer &rhs,

              const dng_rect &area,

              uint32 plane,

              uint32 planes) const;

    /// Return the absolute value of the maximum difference between two pixel buffers. Used for comparison testing with tolerance

    /// \param rhs Buffer to compare against.

    /// \param area Rectangle of pixel buffer to test.

    /// \param plane Plane to start comparing.

    /// \param planes Number of planes to compare.

    /// \retval larges absolute value difference between the corresponding pixels each buffer across area.

    real64 MaximumDifference (const dng_pixel_buffer &rhs,

                  const dng_rect &area,

                  uint32 plane,

                  uint32 planes) const;

  };

/*****************************************************************************/

#endif

/*****************************************************************************/