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