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