include/wx/msw/dib.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/msw/dib.h
   3 // Purpose:     wxDIB class representing Win32 device independent bitmaps
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     03.03.03 (replaces the old file with the same name)
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1997-2003 wxWidgets team
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_MSW_DIB_H_
  13 #define _WX_MSW_DIB_H_
  14
  15 class WXDLLIMPEXP_FWD_CORE wxPalette;
  16
  17 #include "wx/msw/private.h"
  18
  19 #if wxUSE_WXDIB
  20
  21 #ifdef __WXMSW__
  22     #include "wx/bitmap.h"
  23 #endif // __WXMSW__
  24
  25 // ----------------------------------------------------------------------------
  26 // wxDIB: represents a DIB section
  27 // ----------------------------------------------------------------------------
  28
  29 class WXDLLIMPEXP_CORE wxDIB
  30 {
  31 public:
  32     // ctors and such
  33     // --------------
  34
  35     // create an uninitialized DIB with the given width, height and depth (only
  36     // 24 and 32 bpp DIBs are currently supported)
  37     //
  38     // after using this ctor, GetData() and GetHandle() may be used if IsOk()
  39     // returns true
  40     wxDIB(int width, int height, int depth)
  41         { Init(); (void)Create(width, height, depth); }
  42
  43 #ifdef __WXMSW__
  44     // create a DIB from the DDB
  45     wxDIB(const wxBitmap& bmp)
  46         { Init(); (void)Create(bmp); }
  47 #endif // __WXMSW__
  48
  49     // create a DIB from the Windows DDB
  50     wxDIB(HBITMAP hbmp)
  51         { Init(); (void)Create(hbmp); }
  52
  53     // load a DIB from file (any depth is supoprted here unlike above)
  54     //
  55     // as above, use IsOk() to see if the bitmap was loaded successfully
  56     wxDIB(const wxString& filename)
  57         { Init(); (void)Load(filename); }
  58
  59     // same as the corresponding ctors but with return value
  60     bool Create(int width, int height, int depth);
  61 #ifdef __WXMSW__
  62     bool Create(const wxBitmap& bmp) { return Create(GetHbitmapOf(bmp)); }
  63 #endif
  64     bool Create(HBITMAP hbmp);
  65     bool Load(const wxString& filename);
  66
  67     // dtor is not virtual, this class is not meant to be used polymorphically
  68     ~wxDIB();
  69
  70
  71     // operations
  72     // ----------
  73
  74 #ifndef __WXWINCE__
  75     // create a bitmap compatible with the given HDC (or screen by default) and
  76     // return its handle, the caller is responsible for freeing it (using
  77     // DeleteObject())
  78     HBITMAP CreateDDB(HDC hdc = 0) const;
  79 #endif // !__WXWINCE__
  80
  81     // get the handle from the DIB and reset it, i.e. this object won't destroy
  82     // the DIB after this (but the caller should do it)
  83     HBITMAP Detach() { HBITMAP hbmp = m_handle; m_handle = 0; return hbmp; }
  84
  85 #if wxUSE_PALETTE
  86     // create a palette for this DIB (always a trivial/default one for 24bpp)
  87     wxPalette *CreatePalette() const;
  88 #endif // wxUSE_PALETTE
  89
  90     // save the DIB as a .BMP file to the file with the given name
  91     bool Save(const wxString& filename);
  92
  93
  94     // accessors
  95     // ---------
  96
  97     // return true if DIB was successfully created, false otherwise
  98     bool IsOk() const { return m_handle != 0; }
  99
 100     // get the bitmap size
 101     wxSize GetSize() const { DoGetObject(); return wxSize(m_width, m_height); }
 102     int GetWidth() const { DoGetObject(); return m_width; }
 103     int GetHeight() const { DoGetObject(); return m_height; }
 104
 105     // get the number of bits per pixel, or depth
 106     int GetDepth() const { DoGetObject(); return m_depth; }
 107
 108     // get the DIB handle
 109     HBITMAP GetHandle() const { return m_handle; }
 110
 111     // get raw pointer to bitmap bits, you should know what you do if you
 112     // decide to use it
 113     unsigned char *GetData() const
 114         { DoGetObject(); return (unsigned char *)m_data; }
 115
 116
 117     // HBITMAP conversion
 118     // ------------------
 119
 120     // these functions are only used by wxWidgets internally right now, please
 121     // don't use them directly if possible as they're subject to change
 122
 123 #ifndef __WXWINCE__
 124     // creates a DDB compatible with the given (or screen) DC from either
 125     // a plain DIB or a DIB section (in which case the last parameter must be
 126     // non NULL)
 127     static HBITMAP ConvertToBitmap(const BITMAPINFO *pbi,
 128                                    HDC hdc = 0,
 129                                    void *bits = NULL);
 130
 131     // create a plain DIB (not a DIB section) from a DDB, the caller is
 132     // responsable for freeing it using ::GlobalFree()
 133     static HGLOBAL ConvertFromBitmap(HBITMAP hbmp);
 134
 135     // creates a DIB from the given DDB or calculates the space needed by it:
 136     // if pbi is NULL, only the space is calculated, otherwise pbi is supposed
 137     // to point at BITMAPINFO of the correct size which is filled by this
 138     // function (this overload is needed for wxBitmapDataObject code in
 139     // src/msw/ole/dataobj.cpp)
 140     static size_t ConvertFromBitmap(BITMAPINFO *pbi, HBITMAP hbmp);
 141 #endif // __WXWINCE__
 142
 143
 144     // wxImage conversion
 145     // ------------------
 146
 147 #if wxUSE_IMAGE
 148     // Possible formats for DIBs created by the functions below.
 149     enum PixelFormat
 150     {
 151         PixelFormat_PreMultiplied = 0,
 152         PixelFormat_NotPreMultiplied = 1
 153     };
 154
 155     // Create a DIB from the given image, the DIB will be either 24 or 32 (if
 156     // the image has alpha channel) bpp.
 157     //
 158     // By default the DIB stores pixel data in pre-multiplied format so that it
 159     // can be used with ::AlphaBlend() but it is also possible to disable
 160     // pre-multiplication for the DIB to be usable with ImageList_Draw() which
 161     // does pre-multiplication internally.
 162     wxDIB(const wxImage& image, PixelFormat pf = PixelFormat_PreMultiplied)
 163     {
 164         Init();
 165         (void)Create(image, pf);
 166     }
 167
 168     // same as the above ctor but with the return code
 169     bool Create(const wxImage& image, PixelFormat pf = PixelFormat_PreMultiplied);
 170
 171     // create wxImage having the same data as this DIB
 172     wxImage ConvertToImage() const;
 173 #endif // wxUSE_IMAGE
 174
 175
 176     // helper functions
 177     // ----------------
 178
 179     // return the size of one line in a DIB with given width and depth: the
 180     // point here is that as the scan lines need to be DWORD aligned so we may
 181     // need to add some padding
 182     static unsigned long GetLineSize(int width, int depth)
 183     {
 184         return ((width*depth + 31) & ~31) >> 3;
 185     }
 186
 187 private:
 188     // common part of all ctors
 189     void Init();
 190
 191     // free resources
 192     void Free();
 193
 194     // initialize the contents from the provided DDB (Create() must have been
 195     // already called)
 196     bool CopyFromDDB(HBITMAP hbmp);
 197
 198
 199     // the DIB section handle, 0 if invalid
 200     HBITMAP m_handle;
 201
 202     // NB: we could store only m_handle and not any of the other fields as
 203     //     we may always retrieve them from it using ::GetObject(), but we
 204     //     decide to still store them for efficiency concerns -- however if we
 205     //     don't have them from the very beginning (e.g. DIB constructed from a
 206     //     bitmap), we only retrieve them when necessary and so these fields
 207     //     should *never* be accessed directly, even from inside wxDIB code
 208
 209     // function which must be called before accessing any members and which
 210     // gets their values from m_handle, if not done yet
 211     void DoGetObject() const;
 212
 213     // pointer to DIB bits, may be NULL
 214     void *m_data;
 215
 216     // size and depth of the image
 217     int m_width,
 218         m_height,
 219         m_depth;
 220
 221     // in some cases we could be using a handle which we didn't create and in
 222     // this case we shouldn't free it neither -- this flag tell us if this is
 223     // the case
 224     bool m_ownsHandle;
 225
 226
 227     // DIBs can't be copied
 228     wxDIB(const wxDIB&);
 229     wxDIB& operator=(const wxDIB&);
 230 };
 231
 232 // ----------------------------------------------------------------------------
 233 // inline functions implementation
 234 // ----------------------------------------------------------------------------
 235
 236 inline
 237 void wxDIB::Init()
 238 {
 239     m_handle = 0;
 240     m_ownsHandle = true;
 241
 242     m_data = NULL;
 243
 244     m_width =
 245     m_height =
 246     m_depth = 0;
 247 }
 248
 249 inline
 250 void wxDIB::Free()
 251 {
 252     if ( m_handle && m_ownsHandle )
 253     {
 254         if ( !::DeleteObject(m_handle) )
 255         {
 256             wxLogLastError(wxT("DeleteObject(hDIB)"));
 257         }
 258
 259         Init();
 260     }
 261 }
 262
 263 inline wxDIB::~wxDIB()
 264 {
 265     Free();
 266 }
 267
 268 #endif
 269     // wxUSE_WXDIB
 270
 271 #endif // _WX_MSW_DIB_H_
 272