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