]> git.saurik.com Git - wxWidgets.git/blob - include/wx/rawbmp.h
cleanup
[wxWidgets.git] / include / wx / rawbmp.h
1 ///////////////////////////////////////////////////////////////////////////////
2 // Name: wx/rawbmp.h
3 // Purpose: macros for fast, raw bitmap data access
4 // Author: Eric Kidd, Vadim Zeitlin
5 // Modified by:
6 // Created: 10.03.03
7 // RCS-ID: $Id$
8 // Copyright: (c) 2002 Vadim Zeitlin <vadim@wxwidgets.org>
9 // Licence: wxWindows licence
10 ///////////////////////////////////////////////////////////////////////////////
11
12 #ifndef _WX_RAWBMP_H_
13 #define _WX_RAWBMP_H_
14
15 #include "wx/image.h"
16
17 // ----------------------------------------------------------------------------
18 // Abstract Pixel API
19 //
20 // We need to access our raw bitmap data (1) portably and (2) efficiently.
21 // We do this using a two-dimensional "iteration" interface. Performance
22 // is extremely important here: these functions will be called hundreds
23 // of thousands of times in a row, and even small inefficiencies will
24 // make applications seem slow.
25 //
26 // We can't always rely on inline functions, because not all compilers actually
27 // bother to inline them unless we crank the optimization levels way up.
28 // Therefore, we also provide macros to wring maximum speed out of compiler
29 // unconditionally (e.g. even in debug builds). Of course, if the performance
30 // isn't absolutely crucial for you you shouldn't be using them but the inline
31 // functions instead.
32 // ----------------------------------------------------------------------------
33
34 /*
35 Usage example:
36
37 typedef wxPixelData<wxBitmap, wxNativePixelFormat> PixelData;
38
39 wxBitmap bmp;
40 PixelData data(bmp);
41 if ( !data )
42 {
43 ... raw access to bitmap data unavailable, do something else ...
44 return;
45 }
46
47 if ( data.GetWidth() < 20 || data.GetHeight() < 20 )
48 {
49 ... complain: the bitmap it too small ...
50 return;
51 }
52
53 PixelData::Iterator p(data);
54
55 // we draw a (10, 10)-(20, 20) rect manually using the given r, g, b
56 p.Offset(data, 10, 10);
57
58 for ( int y = 0; y < 10; ++y )
59 {
60 PixelData::Iterator rowStart = p;
61
62 for ( int x = 0; x < 10; ++x, ++p )
63 {
64 p.Red() = r;
65 p.Green() = g;
66 p.Blue() = b;
67 }
68
69 p = rowStart;
70 p.OffsetY(data, 1);
71 }
72 */
73
74 /*
75 Note: we do not use WXDLLEXPORT with classes in this file because VC++ has
76 problems with exporting inner class defined inside a specialization of a
77 template class from a DLL. Besides, as all the methods are inline it's not
78 really necessary to put them in DLL at all.
79 */
80
81 // ----------------------------------------------------------------------------
82 // wxPixelFormat
83 // ----------------------------------------------------------------------------
84
85 /*
86 wxPixelFormat is a template class describing the bitmap data format. It
87 contains the constants describing the format of pixel data, but does not
88 describe how the entire bitmap is stored (i.e. top-to-bottom,
89 bottom-to-top, ...). It is also a "traits"-like class, i.e. it only
90 contains some constants and maybe static methods but nothing more, so it
91 can be safely used without incurring any overhead as all accesses to it are
92 done at compile-time.
93
94 Current limitations: we don't support RAGABA and ARAGAB formats supported
95 by Mac OS X. If there is sufficient interest, these classes could be
96 extended to deal with them. Neither do we support alpha channel having
97 different representation from the RGB ones (happens under QNX/Photon I
98 think), but again this could be achieved with some small extra effort.
99
100 Template parameters are:
101 - type of a single pixel component
102 - size of the single pixel in bits
103 - indices of red, green and blue pixel components inside the pixel
104 - index of the alpha component or -1 if none
105 - type which can contain the full pixel value (all channels)
106 */
107
108 template <class Channel,
109 size_t Bpp, int R, int G, int B, int A = -1,
110 class Pixel = wxUint32>
111
112 struct wxPixelFormat
113 {
114 // iterator over pixels is usually of type "ChannelType *"
115 typedef Channel ChannelType;
116
117 // the type which may hold the entire pixel value
118 typedef Pixel PixelType;
119
120 // NB: using static ints initialized inside the class declaration is not
121 // portable as it doesn't work with VC++ 6, so we must use enums
122
123 // size of one pixel in bits
124 enum { BitsPerPixel = Bpp };
125
126 // size of one pixel in ChannelType units (usually bytes)
127 enum { SizePixel = Bpp / (8 * sizeof(Channel)) };
128
129 // the channels indices inside the pixel
130 enum
131 {
132 RED = R,
133 GREEN = G,
134 BLUE = B,
135 ALPHA = A
136 };
137
138 // true if we have an alpha channel (together with the other channels, this
139 // doesn't cover the case of wxImage which stores alpha separately)
140 enum { HasAlpha = A != -1 };
141 };
142
143 // some "predefined" pixel formats
144 // -------------------------------
145
146 // wxImage format is common to all platforms
147 typedef wxPixelFormat<unsigned char, 24, 0, 1, 2> wxImagePixelFormat;
148
149 // the (most common) native bitmap format without alpha support
150 #if defined(__WXMSW__)
151 // under MSW the RGB components are reversed, they're in BGR order
152 typedef wxPixelFormat<unsigned char, 24, 2, 1, 0> wxNativePixelFormat;
153
154 #define wxPIXEL_FORMAT_ALPHA 3
155 #elif defined(__WXMAC__)
156 // under Mac, first component is unused but still present, hence we use
157 // 32bpp, not 24
158 typedef wxPixelFormat<unsigned char, 32, 1, 2, 3> wxNativePixelFormat;
159
160 #define wxPIXEL_FORMAT_ALPHA 0
161 #elif defined(__WXCOCOA__)
162 // Cocoa is standard RGB or RGBA (normally it is RGBA)
163 typedef wxPixelFormat<unsigned char, 24, 0, 1, 2> wxNativePixelFormat;
164
165 #define wxPIXEL_FORMAT_ALPHA 3
166 #elif defined(__WXGTK__)
167 // Under GTK+ 2.X we use GdkPixbuf, which is standard RGB or RGBA
168 typedef wxPixelFormat<unsigned char, 24, 0, 1, 2> wxNativePixelFormat;
169
170 #define wxPIXEL_FORMAT_ALPHA 3
171 #elif defined(__WXDFB__)
172 // Under DirectFB, RGB components are reversed, they're in BGR order
173 typedef wxPixelFormat<unsigned char, 24, 2, 1, 0> wxNativePixelFormat;
174
175 #define wxPIXEL_FORMAT_ALPHA 3
176 #endif
177
178 // the (most common) native format for bitmaps with alpha channel
179 #ifdef wxPIXEL_FORMAT_ALPHA
180 typedef wxPixelFormat<unsigned char, 32,
181 wxNativePixelFormat::RED,
182 wxNativePixelFormat::GREEN,
183 wxNativePixelFormat::BLUE,
184 wxPIXEL_FORMAT_ALPHA> wxAlphaPixelFormat;
185 #endif // wxPIXEL_FORMAT_ALPHA
186
187 // we also define the (default/best) pixel format for the given class: this is
188 // used as default value for the pixel format in wxPixelIterator template
189 template <class T> struct wxPixelFormatFor;
190
191 #if wxUSE_IMAGE
192 // wxPixelFormatFor is only defined for wxImage, attempt to use it with other
193 // classes (wxBitmap...) will result in compile errors which is exactly what we
194 // want
195 template <>
196 struct wxPixelFormatFor<wxImage>
197 {
198 typedef wxImagePixelFormat Format;
199 };
200 #endif //wxUSE_IMAGE
201
202 // ----------------------------------------------------------------------------
203 // wxPixelData
204 // ----------------------------------------------------------------------------
205
206 /*
207 wxPixelDataBase is just a helper for wxPixelData: it contains things common
208 to both wxImage and wxBitmap specializations.
209 */
210 class wxPixelDataBase
211 {
212 public:
213 // origin of the rectangular region we represent
214 wxPoint GetOrigin() const { return m_ptOrigin; }
215
216 // width and height of the region we represent
217 int GetWidth() const { return m_width; }
218 int GetHeight() const { return m_height; }
219
220 wxSize GetSize() const { return wxSize(m_width, m_height); }
221
222 // the distance between two rows
223 int GetRowStride() const { return m_stride; }
224
225 // private: -- see comment in the beginning of the file
226
227 // the origin of this image inside the bigger bitmap (usually (0, 0))
228 wxPoint m_ptOrigin;
229
230 // the size of the image we address, in pixels
231 int m_width,
232 m_height;
233
234 // this parameter is the offset of the start of the (N+1)st row from the
235 // Nth one and can be different from m_bypp*width in some cases:
236 // a) the most usual one is to force 32/64 bit alignment of rows
237 // b) another one is for bottom-to-top images where it's negative
238 // c) finally, it could conceivably be 0 for the images with all
239 // lines being identical
240 int m_stride;
241
242 protected:
243 // ctor is protected because this class is only meant to be used as the
244 // base class by wxPixelData
245 wxPixelDataBase()
246 {
247 m_width =
248 m_height =
249 m_stride = 0;
250 }
251 };
252
253 /*
254 wxPixelData represents the entire bitmap data, i.e. unlike
255 wxPixelFormat (which it uses) it also stores the global bitmap
256 characteristics such as its size, inter-row separation and so on.
257
258 Because of this it can be used to move the pixel iterators (which don't
259 have enough information about the bitmap themselves). This may seem a bit
260 unnatural but must be done in this way to keep the iterator objects as
261 small as possible for maximum efficiency as otherwise they wouldn't be put
262 into the CPU registers by the compiler any more.
263
264 Implementation note: we use the standard workaround for lack of partial
265 template specialization support in VC (both 6 and 7): instead of partly
266 specializing the class Foo<T, U> for some T we introduce FooOut<T> and
267 FooIn<U> nested in it, make Foo<T, U> equivalent to FooOut<T>::FooIn<U> and
268 fully specialize FooOut.
269
270 Also note that this class doesn't have any default definition because we
271 can't really do anything without knowing the exact image class. We do
272 provide wxPixelDataBase to make it simpler to write new wxPixelData
273 specializations.
274 */
275
276 // we need to define this skeleton template to mollify VC++
277 template <class Image>
278 struct wxPixelDataOut
279 {
280 template <class PixelFormat>
281 class wxPixelDataIn
282 {
283 public:
284 class Iterator { };
285 };
286 };
287
288 #if wxUSE_IMAGE
289 // wxPixelData specialization for wxImage: this is the simplest case as we
290 // don't have to care about different pixel formats here
291 template <>
292 struct wxPixelDataOut<wxImage>
293 {
294 // NB: this is a template class even though it doesn't use its template
295 // parameter because otherwise wxPixelData couldn't compile
296 template <class dummyPixelFormat>
297 class wxPixelDataIn : public wxPixelDataBase
298 {
299 public:
300 // the type of the class we're working with
301 typedef wxImage ImageType;
302
303 // the iterator which should be used for working with data in this
304 // format
305 class Iterator
306 {
307 public:
308 // the pixel format we use
309 typedef wxImagePixelFormat PixelFormat;
310
311 // the type of the pixel components
312 typedef typename dummyPixelFormat::ChannelType ChannelType;
313
314 // the pixel data we're working with
315 typedef
316 wxPixelDataOut<wxImage>::wxPixelDataIn<PixelFormat> PixelData;
317
318 // go back to (0, 0)
319 void Reset(const PixelData& data)
320 {
321 *this = data.GetPixels();
322 }
323
324 // creates the iterator pointing to the beginning of data
325 Iterator(PixelData& data)
326 {
327 Reset(data);
328 }
329
330 // creates the iterator initially pointing to the image origin
331 Iterator(const wxImage& image)
332 {
333 m_pRGB = image.GetData();
334
335 if ( image.HasAlpha() )
336 {
337 m_pAlpha = image.GetAlpha();
338 }
339 else // alpha is not used at all
340 {
341 m_pAlpha = NULL;
342 }
343 }
344
345 // true if the iterator is valid
346 bool IsOk() const { return m_pRGB != NULL; }
347
348
349 // navigation
350 // ----------
351
352 // advance the iterator to the next pixel, prefix version
353 Iterator& operator++()
354 {
355 m_pRGB += PixelFormat::SizePixel;
356 if ( m_pAlpha )
357 ++m_pAlpha;
358
359 return *this;
360 }
361
362 // postfix (hence less efficient -- don't use it unless you
363 // absolutely must) version
364 Iterator operator++(int)
365 {
366 Iterator p(*this);
367 ++*this;
368 return p;
369 }
370
371 // move x pixels to the right and y down
372 //
373 // note that the rows don't wrap!
374 void Offset(const PixelData& data, int x, int y)
375 {
376 m_pRGB += data.GetRowStride()*y + PixelFormat::SizePixel*x;
377 if ( m_pAlpha )
378 m_pAlpha += data.GetWidth() + x;
379 }
380
381 // move x pixels to the right (again, no row wrapping)
382 void OffsetX(const PixelData& WXUNUSED(data), int x)
383 {
384 m_pRGB += PixelFormat::SizePixel*x;
385 if ( m_pAlpha )
386 m_pAlpha += x;
387 }
388
389 // move y rows to the bottom
390 void OffsetY(const PixelData& data, int y)
391 {
392 m_pRGB += data.GetRowStride()*y;
393 if ( m_pAlpha )
394 m_pAlpha += data.GetWidth();
395 }
396
397 // go to the given position
398 void MoveTo(const PixelData& data, int x, int y)
399 {
400 Reset(data);
401 Offset(data, x, y);
402 }
403
404
405 // data access
406 // -----------
407
408 // access to invidividual colour components
409 ChannelType& Red() { return m_pRGB[PixelFormat::RED]; }
410 ChannelType& Green() { return m_pRGB[PixelFormat::GREEN]; }
411 ChannelType& Blue() { return m_pRGB[PixelFormat::BLUE]; }
412 ChannelType& Alpha() { return *m_pAlpha; }
413
414 // private: -- see comment in the beginning of the file
415
416 // pointer into RGB buffer
417 unsigned char *m_pRGB;
418
419 // pointer into alpha buffer or NULL if alpha isn't used
420 unsigned char *m_pAlpha;
421 };
422
423 // initializes us with the data of the given image
424 wxPixelDataIn(ImageType& image) : m_image(image), m_pixels(image)
425 {
426 m_width = image.GetWidth();
427 m_height = image.GetHeight();
428 m_stride = Iterator::SizePixel * m_width;
429 }
430
431 // initializes us with the given region of the specified image
432 wxPixelDataIn(ImageType& image,
433 const wxPoint& pt,
434 const wxSize& sz) : m_image(image), m_pixels(image)
435 {
436 m_stride = Iterator::SizePixel * m_width;
437
438 InitRect(pt, sz);
439 }
440
441 // initializes us with the given region of the specified image
442 wxPixelDataIn(ImageType& image,
443 const wxRect& rect) : m_image(image), m_pixels(image)
444 {
445 m_stride = Iterator::SizePixel * m_width;
446
447 InitRect(rect.GetPosition(), rect.GetSize());
448 }
449
450 // we evaluate to true only if we could get access to bitmap data
451 // successfully
452 operator bool() const { return m_pixels.IsOk(); }
453
454 // get the iterator pointing to the origin
455 Iterator GetPixels() const { return m_pixels; }
456
457 private:
458 void InitRect(const wxPoint& pt, const wxSize& sz)
459 {
460 m_width = sz.x;
461 m_height = sz.y;
462
463 m_ptOrigin = pt;
464 m_pixels.Offset(*this, pt.x, pt.y);
465 }
466
467 // the image we're working with
468 ImageType& m_image;
469
470 // the iterator pointing to the image origin
471 Iterator m_pixels;
472 };
473 };
474 #endif //wxUSE_IMAGE
475
476 #if wxUSE_GUI
477 // wxPixelData specialization for wxBitmap: here things are more interesting as
478 // we also have to support different pixel formats
479 template <>
480 struct wxPixelDataOut<wxBitmap>
481 {
482 template <class Format>
483 class wxPixelDataIn : public wxPixelDataBase
484 {
485 public:
486 // the type of the class we're working with
487 typedef wxBitmap ImageType;
488
489 class Iterator
490 {
491 public:
492 // the pixel format we use
493 typedef Format PixelFormat;
494
495 // the type of the pixel components
496 typedef typename PixelFormat::ChannelType ChannelType;
497
498 // the pixel data we're working with
499 typedef wxPixelDataOut<wxBitmap>::wxPixelDataIn<Format> PixelData;
500
501
502 // go back to (0, 0)
503 void Reset(const PixelData& data)
504 {
505 *this = data.GetPixels();
506 }
507
508 // initializes the iterator to point to the origin of the given
509 // pixel data
510 Iterator(PixelData& data)
511 {
512 Reset(data);
513 }
514
515 // initializes the iterator to point to the origin of the given
516 // bitmap
517 Iterator(wxBitmap& bmp, PixelData& data)
518 {
519 // using cast here is ugly but it should be safe as
520 // GetRawData() real return type should be consistent with
521 // BitsPerPixel (which is in turn defined by ChannelType) and
522 // this is the only thing we can do without making GetRawData()
523 // a template function which is undesirable
524 m_ptr = (ChannelType *)
525 bmp.GetRawData(data, PixelFormat::BitsPerPixel);
526 }
527
528 // default constructor
529 Iterator()
530 {
531 m_ptr = NULL;
532 }
533
534 // return true if this iterator is valid
535 bool IsOk() const { return m_ptr != NULL; }
536
537
538 // navigation
539 // ----------
540
541 // advance the iterator to the next pixel, prefix version
542 Iterator& operator++()
543 {
544 m_ptr += PixelFormat::SizePixel;
545
546 return *this;
547 }
548
549 // postfix (hence less efficient -- don't use it unless you
550 // absolutely must) version
551 Iterator operator++(int)
552 {
553 Iterator p(*this);
554 ++*this;
555 return p;
556 }
557
558 // move x pixels to the right and y down
559 //
560 // note that the rows don't wrap!
561 void Offset(const PixelData& data, int x, int y)
562 {
563 m_ptr += data.GetRowStride()*y + PixelFormat::SizePixel*x;
564 }
565
566 // move x pixels to the right (again, no row wrapping)
567 void OffsetX(const PixelData& WXUNUSED(data), int x)
568 {
569 m_ptr += PixelFormat::SizePixel*x;
570 }
571
572 // move y rows to the bottom
573 void OffsetY(const PixelData& data, int y)
574 {
575 m_ptr += data.GetRowStride()*y;
576 }
577
578 // go to the given position
579 void MoveTo(const PixelData& data, int x, int y)
580 {
581 Reset(data);
582 Offset(data, x, y);
583 }
584
585
586 // data access
587 // -----------
588
589 // access to invidividual colour components
590 ChannelType& Red() { return m_ptr[PixelFormat::RED]; }
591 ChannelType& Green() { return m_ptr[PixelFormat::GREEN]; }
592 ChannelType& Blue() { return m_ptr[PixelFormat::BLUE]; }
593 ChannelType& Alpha() { return m_ptr[PixelFormat::ALPHA]; }
594
595 // address the pixel contents directly
596 //
597 // warning: the format is platform dependent
598 typename PixelFormat::PixelType& Data()
599 { return *(typename PixelFormat::PixelType *)m_ptr; }
600
601 // private: -- see comment in the beginning of the file
602
603 // for efficiency reasons this class should not have any other
604 // fields, otherwise it won't be put into a CPU register (as it
605 // should inside the inner loops) by some compilers, notably gcc
606 ChannelType *m_ptr;
607 };
608
609 // ctor associates this pointer with a bitmap and locks the bitmap for
610 // raw access, it will be unlocked only by our dtor and so these
611 // objects should normally be only created on the stack, i.e. have
612 // limited life-time
613 wxPixelDataIn(wxBitmap& bmp) : m_bmp(bmp), m_pixels(bmp, *this)
614 {
615 }
616
617 wxPixelDataIn(wxBitmap& bmp, const wxRect& rect)
618 : m_bmp(bmp), m_pixels(bmp, *this)
619 {
620 InitRect(rect.GetPosition(), rect.GetSize());
621 }
622
623 wxPixelDataIn(wxBitmap& bmp, const wxPoint& pt, const wxSize& sz)
624 : m_bmp(bmp), m_pixels(bmp, *this)
625 {
626 InitRect(pt, sz);
627 }
628
629 // we evaluate to true only if we could get access to bitmap data
630 // successfully
631 operator bool() const { return m_pixels.IsOk(); }
632
633 // get the iterator pointing to the origin
634 Iterator GetPixels() const { return m_pixels; }
635
636 // dtor unlocks the bitmap
637 ~wxPixelDataIn()
638 {
639 if ( m_pixels.IsOk() )
640 {
641 #if defined(__WXMSW__) || defined(__WXMAC__)
642 // this is a hack to mark wxBitmap as using alpha channel
643 if ( Format::HasAlpha )
644 m_bmp.UseAlpha();
645 #endif
646 m_bmp.UngetRawData(*this);
647 }
648 // else: don't call UngetRawData() if GetRawData() failed
649 }
650
651 #if WXWIN_COMPATIBILITY_2_8
652 // not needed anymore, calls to it should be simply removed
653 wxDEPRECATED_INLINE( void UseAlpha(), wxEMPTY_PARAMETER_VALUE )
654 #endif
655
656 // private: -- see comment in the beginning of the file
657
658 // the bitmap we're associated with
659 wxBitmap m_bmp;
660
661 // the iterator pointing to the image origin
662 Iterator m_pixels;
663
664 private:
665 void InitRect(const wxPoint& pt, const wxSize& sz)
666 {
667 m_pixels.Offset(*this, pt.x, pt.y);
668
669 m_ptOrigin = pt;
670 m_width = sz.x;
671 m_height = sz.y;
672 }
673 };
674 };
675
676 #endif //wxUSE_GUI
677
678 template <class Image, class PixelFormat = wxPixelFormatFor<Image> >
679 class wxPixelData :
680 public wxPixelDataOut<Image>::template wxPixelDataIn<PixelFormat>
681 {
682 public:
683 typedef
684 typename wxPixelDataOut<Image>::template wxPixelDataIn<PixelFormat>
685 Base;
686
687 wxPixelData(Image& image) : Base(image) { }
688
689 wxPixelData(Image& i, const wxRect& rect) : Base(i, rect) { }
690
691 wxPixelData(Image& i, const wxPoint& pt, const wxSize& sz)
692 : Base(i, pt, sz)
693 {
694 }
695 };
696
697 // some "predefined" pixel data classes
698 #if wxUSE_IMAGE
699 typedef wxPixelData<wxImage> wxImagePixelData;
700 #endif //wxUSE_IMAGE
701 #if wxUSE_GUI
702 typedef wxPixelData<wxBitmap, wxNativePixelFormat> wxNativePixelData;
703 typedef wxPixelData<wxBitmap, wxAlphaPixelFormat> wxAlphaPixelData;
704
705 #endif //wxUSE_GUI
706
707 // ----------------------------------------------------------------------------
708 // wxPixelIterator
709 // ----------------------------------------------------------------------------
710
711 /*
712 wxPixel::Iterator represents something which points to the pixel data and
713 allows us to iterate over it. In the simplest case of wxBitmap it is,
714 indeed, just a pointer, but it can be something more complicated and,
715 moreover, you are free to specialize it for other image classes and bitmap
716 formats.
717
718 Note that although it would have been much more intuitive to have a real
719 class here instead of what we have now, this class would need two template
720 parameters, and this can't be done because we'd need compiler support for
721 partial template specialization then and neither VC6 nor VC7 provide it.
722 */
723 template < class Image, class PixelFormat = wxPixelFormatFor<Image> >
724 struct wxPixelIterator : public wxPixelData<Image, PixelFormat>::Iterator
725 {
726 };
727
728 #endif // _WX_RAWBMP_H_