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