src/Image/Image_PixMap.hxx

   1 // Created on: 2012-07-18
   2 // Created by: Kirill GAVRILOV
   3 // Copyright (c) 2012-2014 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef _Image_PixMap_H__
  17 #define _Image_PixMap_H__
  18
  19 #include <Image_PixMapData.hxx>
  20 #include <Image_PixMap_Handle.hxx>
  21 #include <Standard_Transient.hxx>
  22 #include <Quantity_Color.hxx>
  23
  24 //! Class represents packed image plane.
  25 class Image_PixMap : public Standard_Transient
  26 {
  27
  28 public:
  29
  30   //! This enumeration define packed image plane formats
  31   typedef enum tagFormat {
  32       ImgUNKNOWN = 0, //!< unsupported or unknown format
  33       ImgGray    = 1, //!< 1 byte per pixel
  34       ImgRGB,         //!< 3 bytes packed RGB image plane
  35       ImgBGR,         //!< same as RGB but with different components order
  36       ImgRGB32,       //!< 4 bytes packed RGB image plane (1 extra byte for alignment, may have undefined value)
  37       ImgBGR32,       //!< same as RGB but with different components order
  38       ImgRGBA,        //!< 4 bytes packed RGBA image plane
  39       ImgBGRA,        //!< same as RGBA but with different components order
  40       ImgGrayF,       //!< 1 float  (4-bytes) per pixel (1-component plane)
  41       ImgRGBF,        //!< 3 floats (12-bytes) RGB image plane
  42       ImgBGRF,        //!< same as RGBF but with different components order
  43       ImgRGBAF,       //!< 4 floats (16-bytes) RGBA image plane
  44       ImgBGRAF,       //!< same as RGBAF but with different components order
  45   } ImgFormat;
  46
  47   //! Determine Big-Endian at runtime
  48   static inline bool IsBigEndianHost()
  49   {
  50     union { int myInt; char myChar[sizeof(int)]; } aUnion;
  51     aUnion.myInt = 1;
  52     return !aUnion.myChar[0];
  53   }
  54
  55 public: // high-level API
  56
  57   inline ImgFormat Format() const
  58   {
  59     return myImgFormat;
  60   }
  61
  62   //! @return image width in pixels
  63   inline Standard_Size Width() const
  64   {
  65     return myData.SizeX;
  66   }
  67
  68   //! @return image height in pixels
  69   inline Standard_Size Height() const
  70   {
  71     return myData.SizeY;
  72   }
  73
  74   //! @return image width in pixels
  75   inline Standard_Size SizeX() const
  76   {
  77     return myData.SizeX;
  78   }
  79
  80   //! @return image height in pixels
  81   inline Standard_Size SizeY() const
  82   {
  83     return myData.SizeY;
  84   }
  85
  86   //! @return width / height.
  87   inline Standard_Real Ratio() const
  88   {
  89     return (SizeY() > 0) ? (Standard_Real(SizeX()) / Standard_Real(SizeY())) : 1.0;
  90   }
  91
  92   //! @return true if data is NULL.
  93   bool IsEmpty() const
  94   {
  95     return myData.IsEmpty();
  96   }
  97
  98   //! Empty constructor. Initialize the NULL image plane.
  99   Standard_EXPORT Image_PixMap();
 100
 101   //! Destructor
 102   Standard_EXPORT virtual ~Image_PixMap();
 103
 104   //! Returns the pixel color. This function is relatively slow.
 105   //! @param theX - column index from left
 106   //! @param theY - row    index from top
 107   //! @return the pixel color
 108   inline Quantity_Color PixelColor (const Standard_Integer theX,
 109                                     const Standard_Integer theY) const
 110   {
 111     Quantity_Parameter aDummy;
 112     return PixelColor (theX, theY, aDummy);
 113   }
 114
 115   //! Returns the pixel color. This function is relatively slow.
 116   //! theAlpha argument is set to color intensity (0 - transparent, 1 - opaque)
 117   Standard_EXPORT Quantity_Color PixelColor (const Standard_Integer theX,
 118                                              const Standard_Integer theY,
 119                                              Quantity_Parameter&    theAlpha) const;
 120
 121   //! Initialize image plane as wrapper over alien data.
 122   //! Data will not be copied! Notice that caller should ensure
 123   //! that data pointer will not be released during this wrapper lifetime.
 124   //! You may call InitCopy() to perform data copying.
 125   Standard_EXPORT virtual bool InitWrapper (ImgFormat            thePixelFormat,
 126                                             Standard_Byte*       theDataPtr,
 127                                             const Standard_Size  theSizeX,
 128                                             const Standard_Size  theSizeY,
 129                                             const Standard_Size  theSizeRowBytes = 0);
 130
 131   //! Initialize image plane with required dimensions.
 132   //! Memory will be left uninitialized (performance trick).
 133   Standard_EXPORT virtual bool InitTrash (ImgFormat           thePixelFormat,
 134                                           const Standard_Size theSizeX,
 135                                           const Standard_Size theSizeY,
 136                                           const Standard_Size theSizeRowBytes = 0);
 137
 138   //! Initialize by copying data.
 139   //! If you want to copy alien data you should create wrapper using InitWrapper() before.
 140   Standard_EXPORT virtual bool InitCopy (const Image_PixMap& theCopy);
 141
 142   //! Initialize image plane with required dimensions.
 143   //! Buffer will be zeroed (black color for most formats).
 144   Standard_EXPORT bool InitZero (ImgFormat           thePixelFormat,
 145                                  const Standard_Size theSizeX,
 146                                  const Standard_Size theSizeY,
 147                                  const Standard_Size theSizeRowBytes = 0,
 148                                  const Standard_Byte theValue = 0);
 149
 150   //! Method correctly deallocate internal buffer.
 151   Standard_EXPORT virtual void Clear();
 152
 153 public: //! @name low-level API for batch-processing (pixels reading / comparison / modification)
 154
 155   //! Returns TRUE if image data is stored from Top to the Down.
 156   //! By default Bottom Up order is used instead
 157   //! (topmost scanlines starts from the bottom in memory).
 158   //! which is most image frameworks naturally support.
 159   //!
 160   //! Notice that access methods within this class automatically
 161   //! convert input row-index to apply this flag!
 162   //! You should use this flag only if interconnect with alien APIs and buffers.
 163   //! @return true if image data is top-down
 164   inline bool IsTopDown() const
 165   {
 166     return myData.TopToDown == 1;
 167   }
 168
 169   //! Setup scanlines order in memory - top-down or bottom-up.
 170   //! Drawers should explicitly specify this value if current state IsTopDown() was ignored!
 171   //! @param theIsTopDown top-down flag
 172   inline void SetTopDown (const bool theIsTopDown)
 173   {
 174     myData.SetTopDown (theIsTopDown);
 175   }
 176
 177   //! Returns +1 if scanlines ordered in Top->Down order in memory and -1 otherwise.
 178   //! @return scanline increment for Top->Down iteration
 179   inline Standard_Size TopDownInc() const
 180   {
 181     return myData.TopToDown;
 182   }
 183
 184   //! @return data pointer for low-level operations (copying entire buffer, parsing with extra tools etc.).
 185   inline const Standard_Byte* Data() const
 186   {
 187     return myData.Data();
 188   }
 189
 190   //! @return data pointer for low-level operations (copying entire buffer, parsing with extra tools etc.).
 191   inline Standard_Byte* ChangeData()
 192   {
 193     return myData.ChangeData();
 194   }
 195
 196   //! @return data pointer to requested row (first column).
 197   inline const Standard_Byte* Row (const Standard_Size theRow) const
 198   {
 199     return myData.Row (theRow);
 200   }
 201
 202   //! @return data pointer to requested row (first column).
 203   inline Standard_Byte* ChangeRow (const Standard_Size theRow)
 204   {
 205     return myData.ChangeRow (theRow);
 206   }
 207
 208   //! @return bytes reserved for one pixel (may include extra bytes for alignment).
 209   inline Standard_Size SizePixelBytes() const
 210   {
 211     return myData.SizeBPP;
 212   }
 213
 214   //! @return bytes reserved for one pixel (may include extra bytes for alignment).
 215   Standard_EXPORT static Standard_Size SizePixelBytes (const Image_PixMap::ImgFormat thePixelFormat);
 216
 217   //! @return bytes reserved per row.
 218   //! Could be larger than needed to store packed row (extra bytes for alignment etc.).
 219   inline Standard_Size SizeRowBytes() const
 220   {
 221     return myData.SizeRowBytes;
 222   }
 223
 224   //! @return the extra bytes in the row.
 225   inline Standard_Size RowExtraBytes() const
 226   {
 227     return SizeRowBytes() - SizeX() * SizePixelBytes();
 228   }
 229
 230   //! Compute the maximal row alignment for current row size.
 231   //! @return maximal row alignment in bytes (up to 16 bytes).
 232   inline Standard_Size MaxRowAligmentBytes() const
 233   {
 234     return myData.MaxRowAligmentBytes();
 235   }
 236
 237   //! @return buffer size
 238   inline Standard_Size SizeBytes() const
 239   {
 240     return myData.Size();
 241   }
 242
 243   //! Access image pixel with specified color type.
 244   //! This method does not perform any type checks - use on own risk (check Format() before)!
 245   template <typename ColorType_t>
 246   inline const ColorType_t& Value (const Standard_Size theRow,
 247                                    const Standard_Size theCol) const
 248   {
 249     return *reinterpret_cast<const ColorType_t*>(myData.Value (theRow, theCol));
 250   }
 251
 252   //! Access image pixel with specified color type.
 253   //! This method does not perform any type checks - use on own risk (check Format() before)!
 254   template <typename ColorType_t>
 255   inline ColorType_t& ChangeValue (const Standard_Size theRow,
 256                                    const Standard_Size theCol)
 257   {
 258     return *reinterpret_cast<ColorType_t* >(myData.ChangeValue (theRow, theCol));
 259   }
 260
 261 protected:
 262
 263   //! Setup pixel format
 264   Standard_EXPORT void setFormat (ImgFormat thePixelFormat);
 265
 266 protected:
 267
 268   Image_PixMapData myData;      //!< data buffer
 269   ImgFormat        myImgFormat; //!< pixel format
 270
 271 private:
 272
 273   //! Copying allowed only within Handles
 274   Image_PixMap            (const Image_PixMap& );
 275   Image_PixMap& operator= (const Image_PixMap& );
 276
 277 public:
 278
 279   DEFINE_STANDARD_RTTI(Image_PixMap) // Type definition
 280
 281 };
 282
 283 #endif // _Image_PixMap_H__