interface/wx/rawbmp.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        rawbmp.h
   3 // Purpose:     interface of wxPixelData
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxPixelData
  10
  11     A class template with ready to use implementations for getting
  12     direct and efficient access to wxBitmap's internal data and
  13     wxImage's internal data through a standard interface. It is
  14     possible to extend this class (interface) to other types of
  15     image content.
  16
  17     Implemented on Windows, GTK+ and OS X:
  18        @li wxNativePixelData: Class to access to wxBitmap's internal data
  19            without alpha channel (RGB).
  20        @li wxAlphaPixelData: Class to access to wxBitmap's internal data with
  21            alpha channel (RGBA).
  22
  23     Implemented everywhere:
  24        @li wxImagePixelData: Class to access to wxImage's internal data with
  25            alpha channel (RGBA).
  26
  27     Example:
  28
  29     @code
  30     wxBitmap bmp;
  31     wxNativePixelData data(bmp);
  32     if ( !data )
  33     {
  34         // ... raw access to bitmap data unavailable, do something else ...
  35         return;
  36     }
  37
  38     if ( data.GetWidth() < 20 || data.GetHeight() < 20 )
  39     {
  40         // ... complain: the bitmap it too small ...
  41         return;
  42     }
  43
  44     wxNativePixelData::Iterator p(data);
  45
  46     // we draw a (10, 10)-(20, 20) rect manually using the given r, g, b
  47     p.Offset(data, 10, 10);
  48
  49     for ( int y = 0; y < 10; ++y )
  50     {
  51         wxNativePixelData::Iterator rowStart = p;
  52
  53         for ( int x = 0; x < 10; ++x, ++p )
  54         {
  55             p.Red() = r;
  56             p.Green() = g;
  57             p.Blue() = b;
  58         }
  59
  60         p = rowStart;
  61         p.OffsetY(data, 1);
  62     }
  63     @endcode
  64
  65     @library{wxcore}
  66     @category{gdi}
  67
  68     @see wxBitmap, wxImage
  69 */
  70 template <class Image, class PixelFormat = wxPixelFormatFor<Image> >
  71 class wxPixelData :
  72     public wxPixelDataOut<Image>::template wxPixelDataIn<PixelFormat>
  73 {
  74 public:
  75     /**
  76         The type of the class we're working with.
  77     */
  78     typedef Image ImageType;
  79
  80     /**
  81         Create pixel data object representing the entire image.
  82     */
  83     wxPixelData(Image& image);
  84
  85
  86     /**
  87         Create pixel data object representing the area of the image defined by
  88         @a rect.
  89     */
  90     wxPixelData(Image& i, const wxRect& rect);
  91
  92     /**
  93         Create pixel data object representing the area of the image defined by
  94         @a pt and @a sz.
  95     */
  96     wxPixelData(Image& i, const wxPoint& pt, const wxSize& sz);
  97
  98     /**
  99         Return @true of if we could get access to bitmap data successfully.
 100     */
 101     operator bool() const;
 102
 103     /**
 104         Return the iterator pointing to the origin of the image.
 105     */
 106     Iterator GetPixels() const;
 107
 108     /**
 109         Returns origin of the rectangular region this wxPixelData represents.
 110     */
 111     wxPoint GetOrigin() const;
 112
 113     /**
 114         Return width of the region this wxPixelData represents.
 115     */
 116     int GetWidth() const;
 117
 118     /**
 119         Return height of the region this wxPixelData represents.
 120     */
 121     int GetHeight() const;
 122
 123     /**
 124         Return the area which this wxPixelData represents in the image.
 125     */
 126     wxSize GetSize() const;
 127
 128     /**
 129         Return the distance between two rows.
 130     */
 131     int GetRowStride() const;
 132
 133
 134     /**
 135         The iterator of class wxPixelData.
 136     */
 137     class Iterator
 138     {
 139     public:
 140
 141         /**
 142             Reset the iterator to point to (0, 0).
 143         */
 144         void Reset(const PixelData& data);
 145
 146         /**
 147             Initializes the iterator to point to the origin of the given pixel
 148             data.
 149         */
 150         Iterator(PixelData& data);
 151
 152         /**
 153             Initializes the iterator to point to the origin of the given Bitmap.
 154         */
 155         Iterator(wxBitmap& bmp, PixelData& data);
 156
 157         /**
 158             Default constructor.
 159         */
 160         Iterator();
 161
 162         /**
 163             Return @true if this iterator is valid.
 164         */
 165         bool IsOk() const;
 166
 167         /**
 168             Advance the iterator to the next pixel, prefix version.
 169         */
 170         Iterator& operator++();
 171
 172         /**
 173             Advance the iterator to the next pixel, postfix (hence less
 174             efficient -- don't use it unless you absolutely must) version.
 175         */
 176         Iterator operator++(int);
 177
 178         /**
 179             Move @a x pixels to the right and @a y down.
 180
 181             @note The rows won't wrap automatically.
 182         */
 183         void Offset(const PixelData& data, int x, int y);
 184
 185         /**
 186             Move @a x pixels to the right.
 187
 188             @note The rows won't wrap automatically.
 189         */
 190         void OffsetX(const PixelData&data, int x);
 191
 192         /**
 193             Move @a y rows to the bottom
 194         */
 195         void OffsetY(const PixelData& data, int y);
 196
 197         /**
 198             Go to the given position
 199         */
 200         void MoveTo(const PixelData& data, int x, int y);
 201
 202         //@{
 203         /**
 204             Data Access: Access to individual colour components.
 205         */
 206         ChannelType& Red();
 207         ChannelType& Green();
 208         ChannelType& Blue();
 209         ChannelType& Alpha();
 210         //@}
 211     };
 212 };
 213