include/wx/animdecod.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/animdecod.h
   3 // Purpose:     wxAnimationDecoder
   4 // Author:      Francesco Montorsi
   5 // CVS-ID:      $Id$
   6 // Copyright:   (c) 2006 Francesco Montorsi
   7 // Licence:     wxWindows licence
   8 /////////////////////////////////////////////////////////////////////////////
   9
  10 #ifndef _WX_ANIMDECOD_H
  11 #define _WX_ANIMDECOD_H
  12
  13 #include "wx/defs.h"
  14
  15 #if wxUSE_STREAMS && wxUSE_GIF
  16
  17 #include "wx/stream.h"
  18 #include "wx/image.h"
  19 #include "wx/colour.h"
  20
  21 /*
  22
  23  Differences between a wxAnimationDecoder and a wxImageHandler:
  24
  25  1) wxImageHandlers always load an input stream directly into a given wxImage
  26     object converting from the format-specific data representation to the
  27     wxImage native format (RGB24).
  28     wxAnimationDecoders always load an input stream using some optimized format
  29     to store it which is format-depedent. This allows to store a (possibly big)
  30     animation using a format which is a good compromise between required memory
  31     and time required to blit in on the screen.
  32
  33  2) wxAnimationDecoders contain the animation data in some internal var.
  34     That's why they derive from wxObjectRefData: they are data which can be shared.
  35
  36  3) wxAnimationDecoders can be used by a wxImageHandler to retrieve a frame
  37     in wxImage format; the viceversa cannot be done.
  38
  39  4) wxAnimationDecoders are decoders only, thus do not support save features.
  40
  41  5) wxAnimationDecoders are directly used by wxAnimation (generic implementation)
  42     as wxObjectRefData while they need to be 'wrapped' by a wxImageHandler for
  43     wxImage uses.
  44
  45 */
  46
  47
  48 // --------------------------------------------------------------------------
  49 // Constants
  50 // --------------------------------------------------------------------------
  51
  52 // NB: the values of these enum items are not casual but coincide with the
  53 //     GIF disposal codes. Do not change them !!
  54 enum wxAnimationDisposal
  55 {
  56     // No disposal specified. The decoder is not required to take any action.
  57     wxANIM_UNSPECIFIED = -1,
  58
  59     // Do not dispose. The graphic is to be left in place.
  60     wxANIM_DONOTREMOVE = 0,
  61
  62     // Restore to background color. The area used by the graphic must be
  63     // restored to the background color.
  64     wxANIM_TOBACKGROUND = 1,
  65
  66     // Restore to previous. The decoder is required to restore the area
  67     // overwritten by the graphic with what was there prior to rendering the graphic.
  68     wxANIM_TOPREVIOUS = 2
  69 };
  70
  71 enum wxAnimationType
  72 {
  73     wxANIMATION_TYPE_INVALID,
  74     wxANIMATION_TYPE_GIF,
  75     wxANIMATION_TYPE_ANI,
  76
  77     wxANIMATION_TYPE_ANY
  78 };
  79
  80
  81 // --------------------------------------------------------------------------
  82 // wxAnimationDecoder class
  83 // --------------------------------------------------------------------------
  84
  85 class WXDLLEXPORT wxAnimationDecoder : public wxObjectRefData
  86 {
  87 protected:
  88     wxSize m_szAnimation;
  89     size_t m_nFrames;
  90
  91     // this is the colour to use for the wxANIM_TOBACKGROUND disposal.
  92     // if not specified by the animation, it's set to wxNullColour
  93     wxColour m_background;
  94
  95 public:     // frame specific data getters
  96
  97     // not all frames may be of the same size; e.g. GIF allows to
  98     // specify that between two frames only a smaller portion of the
  99     // entire animation has changed.
 100     virtual wxSize GetFrameSize(size_t frame) const = 0;
 101
 102     // the position of this frame in case it's not as big as m_szAnimation
 103     // or wxPoint(0,0) otherwise.
 104     virtual wxPoint GetFramePosition(size_t frame) const = 0;
 105
 106     // what should be done after displaying this frame.
 107     virtual wxAnimationDisposal GetDisposalMethod(size_t frame) const = 0;
 108
 109     // the number of milliseconds this frame should be displayed.
 110     // if returns -1 then the frame must be displayed forever.
 111     virtual long GetDelay(size_t frame) const = 0;
 112
 113     // get global data
 114     wxSize GetAnimationSize() const { return m_szAnimation; }
 115     wxColour GetBackgroundColour() const { return m_background; }
 116     size_t GetFrameCount() const { return m_nFrames; }
 117
 118 public:
 119     wxAnimationDecoder()
 120     {
 121         m_background = wxNullColour;
 122         m_nFrames = 0;
 123     }
 124     ~wxAnimationDecoder() {}
 125
 126
 127     virtual bool Load( wxInputStream& stream ) = 0;
 128     virtual bool CanRead( wxInputStream& stream ) const = 0;
 129
 130     virtual wxAnimationDecoder *Clone() const = 0;
 131     virtual wxAnimationType GetType() const = 0;
 132
 133     // convert given frame to wxImage
 134     virtual bool ConvertToImage(size_t frame, wxImage *image) const = 0;
 135 };
 136
 137
 138 #endif  // wxUSE_STREAM && wxUSE_GIF
 139 #endif  // _WX_ANIMDECOD_H
 140