0028441: Coding Rules - move out nested Image_PixMap::ImgFormat enumeration to dedica...
[occt.git] / 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_Format.hxx>
20 #include <Image_PixMapData.hxx>
21 #include <Standard_Transient.hxx>
22 #include <Quantity_ColorRGBA.hxx>
23
24 //! Class represents packed image plane.
25 class Image_PixMap : public Standard_Transient
26 {
27   DEFINE_STANDARD_RTTIEXT(Image_PixMap, Standard_Transient)
28 public:
29
30   //! Determine Big-Endian at runtime
31   static inline bool IsBigEndianHost()
32   {
33     union { int myInt; char myChar[sizeof(int)]; } aUnion;
34     aUnion.myInt = 1;
35     return !aUnion.myChar[0];
36   }
37
38   //! Auxiliary method for swapping bytes between RGB and BGR formats.
39   //! This method modifies the image data but does not change pixel format!
40   //! Method will fail if pixel format is not one of the following:
41   //!  - Image_Format_RGB32 / Image_Format_BGR32
42   //!  - Image_Format_RGBA  / Image_Format_BGRA
43   //!  - Image_Format_RGB   / Image_Format_BGR
44   //!  - Image_Format_RGBF  / Image_Format_BGRF
45   //!  - Image_Format_RGBAF / Image_Format_BGRAF
46   Standard_EXPORT static bool SwapRgbaBgra (Image_PixMap& theImage);
47
48 public: // high-level API
49
50   Image_Format Format() const { return myImgFormat; }
51
52   //! Override pixel format specified by InitXXX() methods.
53   //! Will throw exception if pixel size of new format is not equal to currently initialized format.
54   //! Intended to switch formats indicating different interpretation of the same data
55   //! (e.g. ImgGray and ImgAlpha).
56   Standard_EXPORT void SetFormat (const Image_Format thePixelFormat);
57
58   //! @return image width in pixels
59   inline Standard_Size Width() const
60   {
61     return myData.SizeX;
62   }
63
64   //! @return image height in pixels
65   inline Standard_Size Height() const
66   {
67     return myData.SizeY;
68   }
69
70   //! @return image width in pixels
71   inline Standard_Size SizeX() const
72   {
73     return myData.SizeX;
74   }
75
76   //! @return image height in pixels
77   inline Standard_Size SizeY() const
78   {
79     return myData.SizeY;
80   }
81
82   //! @return width / height.
83   inline Standard_Real Ratio() const
84   {
85     return (SizeY() > 0) ? (Standard_Real(SizeX()) / Standard_Real(SizeY())) : 1.0;
86   }
87
88   //! @return true if data is NULL.
89   bool IsEmpty() const
90   {
91     return myData.IsEmpty();
92   }
93
94   //! Empty constructor. Initialize the NULL image plane.
95   Standard_EXPORT Image_PixMap();
96
97   //! Destructor
98   Standard_EXPORT virtual ~Image_PixMap();
99
100   //! Returns the pixel color. This function is relatively slow.
101   //! Beware that this method takes coordinates in opposite order in contrast to ::Value() and ::ChangeValue().
102   //! @param theX column index from left
103   //! @param theY row    index from top
104   //! @return the pixel color
105   inline Quantity_Color PixelColor (const Standard_Integer theX,
106                                     const Standard_Integer theY) const
107   {
108     Quantity_Parameter aDummy;
109     return PixelColor (theX, theY, aDummy);
110   }
111
112   //! Returns the pixel color. This function is relatively slow.
113   //! theAlpha argument is set to color intensity (0 - transparent, 1 - opaque)
114   //! Beware that this method takes coordinates in opposite order in contrast to ::Value() and ::ChangeValue().
115   Standard_EXPORT Quantity_Color PixelColor (const Standard_Integer theX,
116                                              const Standard_Integer theY,
117                                              Quantity_Parameter&    theAlpha) const;
118
119   //! Sets the pixel color. This function is relatively slow.
120   //! Beware that this method takes coordinates in opposite order in contrast to ::Value() and ::ChangeValue().
121   void SetPixelColor (const Standard_Integer    theX,
122                       const Standard_Integer    theY,
123                       const Quantity_ColorRGBA& theColor)
124   {
125     const NCollection_Vec4<float> aColor = theColor;
126     SetPixelColor (theX, theY, aColor);
127   }
128
129   //! Sets the pixel color. This function is relatively slow.
130   //! Beware that this method takes coordinates in opposite order in contrast to ::Value() and ::ChangeValue().
131   void SetPixelColor(const Standard_Integer theX,
132                      const Standard_Integer theY,
133                      const Quantity_Color&  theColor)
134   {
135     const NCollection_Vec3<float> aColor = theColor;
136     SetPixelColor (theX, theY, NCollection_Vec4<float> (aColor, 1.0f));
137   }
138
139   //! Sets the pixel color. This function is relatively slow.
140   //! Beware that this method takes coordinates in opposite order in contrast to ::Value() and ::ChangeValue().
141   Standard_EXPORT void SetPixelColor (const Standard_Integer theX,
142                                       const Standard_Integer theY,
143                                       const NCollection_Vec4<float>& theColor);
144
145   //! Initialize image plane as wrapper over alien data.
146   //! Data will not be copied! Notice that caller should ensure
147   //! that data pointer will not be released during this wrapper lifetime.
148   //! You may call InitCopy() to perform data copying.
149   Standard_EXPORT virtual bool InitWrapper (Image_Format         thePixelFormat,
150                                             Standard_Byte*       theDataPtr,
151                                             const Standard_Size  theSizeX,
152                                             const Standard_Size  theSizeY,
153                                             const Standard_Size  theSizeRowBytes = 0);
154
155   //! Initialize image plane with required dimensions.
156   //! Memory will be left uninitialized (performance trick).
157   Standard_EXPORT virtual bool InitTrash (Image_Format        thePixelFormat,
158                                           const Standard_Size theSizeX,
159                                           const Standard_Size theSizeY,
160                                           const Standard_Size theSizeRowBytes = 0);
161
162   //! Initialize by copying data.
163   //! If you want to copy alien data you should create wrapper using InitWrapper() before.
164   Standard_EXPORT virtual bool InitCopy (const Image_PixMap& theCopy);
165
166   //! Initialize image plane with required dimensions.
167   //! Buffer will be zeroed (black color for most formats).
168   Standard_EXPORT bool InitZero (Image_Format        thePixelFormat,
169                                  const Standard_Size theSizeX,
170                                  const Standard_Size theSizeY,
171                                  const Standard_Size theSizeRowBytes = 0,
172                                  const Standard_Byte theValue = 0);
173
174   //! Method correctly deallocate internal buffer.
175   Standard_EXPORT virtual void Clear();
176
177 public: //! @name low-level API for batch-processing (pixels reading / comparison / modification)
178
179   //! Returns TRUE if image data is stored from Top to the Down.
180   //! By default Bottom Up order is used instead
181   //! (topmost scanlines starts from the bottom in memory).
182   //! which is most image frameworks naturally support.
183   //!
184   //! Notice that access methods within this class automatically
185   //! convert input row-index to apply this flag!
186   //! You should use this flag only if interconnect with alien APIs and buffers.
187   //! @return true if image data is top-down
188   inline bool IsTopDown() const
189   {
190     return myData.TopToDown == 1;
191   }
192
193   //! Setup scanlines order in memory - top-down or bottom-up.
194   //! Drawers should explicitly specify this value if current state IsTopDown() was ignored!
195   //! @param theIsTopDown top-down flag
196   inline void SetTopDown (const bool theIsTopDown)
197   {
198     myData.SetTopDown (theIsTopDown);
199   }
200
201   //! Returns +1 if scanlines ordered in Top->Down order in memory and -1 otherwise.
202   //! @return scanline increment for Top->Down iteration
203   inline Standard_Size TopDownInc() const
204   {
205     return myData.TopToDown;
206   }
207
208   //! @return data pointer for low-level operations (copying entire buffer, parsing with extra tools etc.).
209   inline const Standard_Byte* Data() const
210   {
211     return myData.Data();
212   }
213
214   //! @return data pointer for low-level operations (copying entire buffer, parsing with extra tools etc.).
215   inline Standard_Byte* ChangeData()
216   {
217     return myData.ChangeData();
218   }
219
220   //! @return data pointer to requested row (first column).
221   inline const Standard_Byte* Row (const Standard_Size theRow) const
222   {
223     return myData.Row (theRow);
224   }
225
226   //! @return data pointer to requested row (first column).
227   inline Standard_Byte* ChangeRow (const Standard_Size theRow)
228   {
229     return myData.ChangeRow (theRow);
230   }
231
232   //! @return bytes reserved for one pixel (may include extra bytes for alignment).
233   inline Standard_Size SizePixelBytes() const
234   {
235     return myData.SizeBPP;
236   }
237
238   //! @return bytes reserved for one pixel (may include extra bytes for alignment).
239   Standard_EXPORT static Standard_Size SizePixelBytes (const Image_Format thePixelFormat);
240
241   //! @return bytes reserved per row.
242   //! Could be larger than needed to store packed row (extra bytes for alignment etc.).
243   inline Standard_Size SizeRowBytes() const
244   {
245     return myData.SizeRowBytes;
246   }
247
248   //! @return the extra bytes in the row.
249   inline Standard_Size RowExtraBytes() const
250   {
251     return SizeRowBytes() - SizeX() * SizePixelBytes();
252   }
253
254   //! Compute the maximal row alignment for current row size.
255   //! @return maximal row alignment in bytes (up to 16 bytes).
256   inline Standard_Size MaxRowAligmentBytes() const
257   {
258     return myData.MaxRowAligmentBytes();
259   }
260
261   //! @return buffer size
262   inline Standard_Size SizeBytes() const
263   {
264     return myData.Size();
265   }
266
267   //! Access image pixel with specified color type.
268   //! This method does not perform any type checks - use on own risk (check Format() before)!
269   template <typename ColorType_t>
270   inline const ColorType_t& Value (const Standard_Size theRow,
271                                    const Standard_Size theCol) const
272   {
273     return *reinterpret_cast<const ColorType_t*>(myData.Value (theRow, theCol));
274   }
275
276   //! Access image pixel with specified color type.
277   //! This method does not perform any type checks - use on own risk (check Format() before)!
278   template <typename ColorType_t>
279   inline ColorType_t& ChangeValue (const Standard_Size theRow,
280                                    const Standard_Size theCol)
281   {
282     return *reinterpret_cast<ColorType_t* >(myData.ChangeValue (theRow, theCol));
283   }
284
285 public:
286
287   Standard_DEPRECATED("This member is deprecated, use Image_Format enumeration instead")
288   typedef Image_Format ImgFormat;
289   static const Image_Format ImgUNKNOWN = Image_Format_UNKNOWN;
290   static const Image_Format ImgGray    = Image_Format_Gray;
291   static const Image_Format ImgAlpha   = Image_Format_Alpha;
292   static const Image_Format ImgRGB     = Image_Format_RGB;
293   static const Image_Format ImgBGR     = Image_Format_BGR;
294   static const Image_Format ImgRGB32   = Image_Format_RGB32;
295   static const Image_Format ImgBGR32   = Image_Format_BGR32;
296   static const Image_Format ImgRGBA    = Image_Format_RGBA;
297   static const Image_Format ImgBGRA    = Image_Format_BGRA;
298   static const Image_Format ImgGrayF   = Image_Format_GrayF;
299   static const Image_Format ImgAlphaF  = Image_Format_AlphaF;
300   static const Image_Format ImgRGBF    = Image_Format_RGBF;
301   static const Image_Format ImgBGRF    = Image_Format_BGRF;
302   static const Image_Format ImgRGBAF   = Image_Format_RGBAF;
303   static const Image_Format ImgBGRAF   = Image_Format_BGRAF;
304
305 protected:
306
307   Image_PixMapData myData;      //!< data buffer
308   Image_Format     myImgFormat; //!< pixel format
309
310 private:
311
312   //! Copying allowed only within Handles
313   Image_PixMap            (const Image_PixMap& );
314   Image_PixMap& operator= (const Image_PixMap& );
315
316 };
317
318 DEFINE_STANDARD_HANDLE(Image_PixMap, Standard_Transient)
319
320 #endif // _Image_PixMap_H__