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