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@wxwindows.org>
   9 // Licence:     wxWindows licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_RAWBMP_H_BASE_
  13 #define _WX_RAWBMP_H_BASE_
  14
  15 // ----------------------------------------------------------------------------
  16 // Abstract Pixel API
  17 //
  18 // We need to access our raw bitmap data (1) portably and (2) efficiently.
  19 // We do this using a two-dimensional "iteration" interface.  Performance
  20 // is extremely important here: these functions will be called hundreds
  21 // of thousands of times in a row, and even small inefficiencies will
  22 // make applications seem slow.
  23 //
  24 // We can't always rely on inline functions, because not all compilers actually
  25 // bother to inline them unless we crank the optimization levels way up.
  26 // Therefore, we also provide macros to wring maximum speed out of compiler
  27 // unconditionally (e.g. even in debug builds). Of course, if the performance
  28 // isn't absolutely crucial for you you shouldn't be using them but the inline
  29 // functions instead.
  30 // ----------------------------------------------------------------------------
  31
  32 /*
  33    Usage example:
  34
  35     wxBitmap bmp;
  36     wxRawBitmapData data(bitmap);
  37     if ( !data )
  38     {
  39         ... raw access to bitmap data unavailable, do something else ...
  40         return;
  41     }
  42
  43     if ( data.m_width < 20 || data.m_height < 20 )
  44     {
  45         ... complain: the bitmap it too small ...
  46         return;
  47     }
  48
  49     wxRawBitmapIterator p(data);
  50
  51     // we draw a (10, 10)-(20, 20) rect manually using the given r, g, b
  52     p.Offset(10, 10);
  53
  54     for ( int y = 0; y < 10; ++y )
  55     {
  56         wxRawBitmapIterator rowStart = p;
  57
  58         for ( int x = 0; x < 10; ++x, ++p )
  59         {
  60             p.Red() = r;
  61             p.Green() = g;
  62             p.Blue() = b;
  63         }
  64
  65         p = rowStart;
  66         p.OffsetY(1);
  67     }
  68  */
  69
  70 // this struct represents a pointer to raw bitmap data
  71 class wxRawBitmapData
  72 {
  73 public:
  74     // ctor associates this pointer with a bitmap and locks the bitmap for raw
  75     // access, it will be unlocked only by our dtor and so these objects should
  76     // normally be only created on the stack, i.e. have limited life-time
  77     wxRawBitmapData(wxBitmap bmp) : m_bmp(bmp)
  78     {
  79         if ( !bmp.GetRawData(this) )
  80             m_pixels = NULL;
  81     }
  82
  83     // we evaluate to true only if we could get access to bitmap data
  84     // successfully
  85     operator bool() const { return m_pixels != NULL; }
  86
  87     // dtor unlocks the bitmap
  88     ~wxRawBitmapData()
  89     {
  90         m_bmp.UngetRawData(this);
  91     }
  92
  93     // accessors
  94     unsigned char *GetPixels() const { return m_pixels; }
  95     int GetWidth() const { return m_width; }
  96     int GetHeight() const { return m_height; }
  97     int GetByPP() const { return m_bypp; }
  98     int GetBPP() const { return 8*GetByPP(); }
  99     int GetRowStride() const { return m_stride; }
 100
 101 // private: -- public because accessed by the macros below but still mustn't be
 102 //             used directly
 103
 104     // the bitmap we're associated with
 105     wxBitmap m_bmp;
 106
 107     // pointer to the start of the data
 108     unsigned char *m_pixels;
 109
 110     // the size of the image we address, in pixels
 111     int m_width,
 112         m_height;
 113
 114     // number of bytes (NOT bits) per pixel, including alpha channel if any
 115     int m_bypp;
 116
 117     // this parameter is the offset of the start of the (N+1)st row from the
 118     // Nth one and can be different from m_bypp*width in some cases:
 119     //  a) the most usual one is to force 32/64 bit alignment of rows
 120     //  b) another one is for bottom-to-top images where it's negative
 121     //  c) finally, it could conceivably be 0 for the images with all
 122     //     lines being identical
 123     int m_stride;
 124 };
 125
 126 // this is the type for the iterator over raw bitmap data
 127 class wxRawBitmapIterator
 128 {
 129 public:
 130     // ctors and such
 131     // --------------
 132
 133     // we must be associated/initialized with some bitmap data object
 134     wxRawBitmapIterator(const wxRawBitmapData& data) : m_data(&data)
 135     {
 136         m_ptr = m_data->GetPixels();
 137     }
 138
 139     // default copy ctor, assignment operator and dtor are ok
 140
 141
 142     // navigation
 143     // ----------
 144
 145     // move x pixels to the right and y down
 146     //
 147     // note that the rows don't wrap!
 148     void Offset(int x, int y)
 149     {
 150         m_ptr += m_data->GetRowStride()*y + m_data->GetByPP()*x;
 151     }
 152
 153     // move x pixels to the right (again, no row wrapping)
 154     void OffsetX(int x)
 155     {
 156         m_ptr += m_data->GetByPP()*x;
 157     }
 158
 159     // move y rows to the bottom
 160     void OffsetY(int y)
 161     {
 162         m_ptr += m_data->GetRowStride()*y;
 163     }
 164
 165     // go back to (0, 0)
 166     void Reset()
 167     {
 168         m_ptr = m_data->GetPixels();
 169     }
 170
 171     // go to the given position
 172     void MoveTo(int x, int y)
 173     {
 174         Reset();
 175         Offset(x, y);
 176     }
 177
 178     // same as OffsetX(1) for convenience
 179     wxRawBitmapIterator& operator++()
 180     {
 181         OffsetX(1);
 182         return *this;
 183     }
 184
 185     // postfix (hence less efficient) version
 186     wxRawBitmapIterator operator++(int)
 187     {
 188         wxRawBitmapIterator p(*this);
 189         OffsetX(1);
 190         return p;
 191     }
 192
 193     // data access
 194     // -----------
 195
 196     // DIBs store data in BGR format, i.e. "little endian" RGB
 197     enum
 198     {
 199 #ifdef __WXMSW__
 200         BLUE, GREEN, RED,
 201 #else // !__WXMSW__
 202         RED, GREEN, BLUE
 203 #endif // __WXMSW__/!__WXMSW__
 204         ALPHA
 205     };
 206
 207     // access to invidividual colour components
 208     unsigned char& Red() { return m_ptr[RED]; }
 209     unsigned char& Green() { return m_ptr[GREEN]; }
 210     unsigned char& Blue() { return m_ptr[BLUE]; }
 211     unsigned char& Alpha() { return m_ptr[ALPHA]; }
 212
 213     // address the pixel contents directly
 214     //
 215     // warning: the format is platform dependent
 216     wxUint32& Data() { return *(wxUint32 *)m_ptr; }
 217
 218 // private: -- don't access these fields directly, same as as above
 219     unsigned char *m_ptr;
 220
 221     const wxRawBitmapData *m_data;
 222 };
 223
 224
 225 // these macros are used to change the current location in the bitmap
 226 // ------------------------------------------------------------------
 227
 228 // move x pixels to the right and y down
 229 //
 230 // note that the rows don't wrap!
 231 #define wxBMP_OFFSET(p, x, y) \
 232     p.m_ptr += p.m_data->m_stride * (y) + p.m_data->m_bypp * (x)
 233
 234 // move x pixels to the right (again, no row wrapping)
 235 #define wxBMP_OFFSET_X(p, x) p.m_ptr += p.m_data->m_bypp * (x)
 236
 237 // move y rows to the bottom
 238 #define wxBMP_OFFSET_Y(p, y) p.m_ptr += p.m_data->m_stride * (y)
 239
 240
 241
 242 // these macros are used to work with the pixel values
 243 //
 244 // all of them can be used as either lvalues or rvalues.
 245 // ----------------------------------------------------
 246
 247 #define wxBMP_RED(p)         (p.m_ptr[wxRawBitmapIterator::RED])
 248 #define wxBMP_GREEN(p)       (p.m_ptr[wxRawBitmapIterator::GREEN])
 249 #define wxBMP_BLUE(p)        (p.m_ptr[wxRawBitmapIterator::BLUE])
 250
 251 #define wxBMP_ALPHA(p)       (p.m_ptr[wxRawBitmapIterator::ALPHA])
 252
 253 // these macros are most efficient but return the buffer contents in
 254 // platform-specific format, e.g. RGB on all sane platforms and BGR under Win32
 255 #define wxBMP_RGB(p)     *(wxUint32 *)(p.m_ptr)
 256 #define wxBMP_RGBA(p)    *(wxUint32 *)(p.m_ptr)
 257
 258 #endif // _WX_RAWBMP_H_BASE_
 259