interface/wx/rawbmp.h

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