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