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
  16
  17 #include "wx/colour.h"
  18 #include "wx/gdicmn.h"
  19 #include "wx/log.h"
  20 #include "wx/stream.h"
  21
  22 class WXDLLIMPEXP_FWD_BASE wxInputStream;
  23 class WXDLLIMPEXP_FWD_CORE wxImage;
  24
  25 /*
  26
  27  Differences between a wxAnimationDecoder and a wxImageHandler:
  28
  29  1) wxImageHandlers always load an input stream directly into a given wxImage
  30     object converting from the format-specific data representation to the
  31     wxImage native format (RGB24).
  32     wxAnimationDecoders always load an input stream using some optimized format
  33     to store it which is format-depedent. This allows to store a (possibly big)
  34     animation using a format which is a good compromise between required memory
  35     and time required to blit it on the screen.
  36
  37  2) wxAnimationDecoders contain the animation data in some internal variable.
  38     That's why they derive from wxObjectRefData: they are data which can be shared.
  39
  40  3) wxAnimationDecoders can be used by a wxImageHandler to retrieve a frame
  41     in wxImage format; the viceversa cannot be done.
  42
  43  4) wxAnimationDecoders are decoders only, thus they do not support save features.
  44
  45  5) wxAnimationDecoders are directly used by wxAnimation (generic implementation)
  46     as wxObjectRefData while they need to be 'wrapped' by a wxImageHandler for
  47     wxImage uses.
  48
  49 */
  50
  51
  52 // --------------------------------------------------------------------------
  53 // Constants
  54 // --------------------------------------------------------------------------
  55
  56 // NB: the values of these enum items are not casual but coincide with the
  57 //     GIF disposal codes. Do not change them !!
  58 enum wxAnimationDisposal
  59 {
  60     // No disposal specified. The decoder is not required to take any action.
  61     wxANIM_UNSPECIFIED = -1,
  62
  63     // Do not dispose. The graphic is to be left in place.
  64     wxANIM_DONOTREMOVE = 0,
  65
  66     // Restore to background color. The area used by the graphic must be
  67     // restored to the background color.
  68     wxANIM_TOBACKGROUND = 1,
  69
  70     // Restore to previous. The decoder is required to restore the area
  71     // overwritten by the graphic with what was there prior to rendering the graphic.
  72     wxANIM_TOPREVIOUS = 2
  73 };
  74
  75 enum wxAnimationType
  76 {
  77     wxANIMATION_TYPE_INVALID,
  78     wxANIMATION_TYPE_GIF,
  79     wxANIMATION_TYPE_ANI,
  80
  81     wxANIMATION_TYPE_ANY
  82 };
  83
  84
  85 // --------------------------------------------------------------------------
  86 // wxAnimationDecoder class
  87 // --------------------------------------------------------------------------
  88
  89 class WXDLLIMPEXP_CORE wxAnimationDecoder : public wxObjectRefData
  90 {
  91 public:
  92     wxAnimationDecoder()
  93     {
  94         m_nFrames = 0;
  95     }
  96
  97     virtual bool Load( wxInputStream& stream ) = 0;
  98
  99     bool CanRead( wxInputStream& stream ) const
 100     {
 101         // NOTE: this code is the same of wxImageHandler::CallDoCanRead
 102
 103         if ( !stream.IsSeekable() )
 104             return false;        // can't test unseekable stream
 105
 106         wxFileOffset posOld = stream.TellI();
 107         bool ok = DoCanRead(stream);
 108
 109         // restore the old position to be able to test other formats and so on
 110         if ( stream.SeekI(posOld) == wxInvalidOffset )
 111         {
 112             wxLogDebug(wxT("Failed to rewind the stream in wxAnimationDecoder!"));
 113
 114             // reading would fail anyhow as we're not at the right position
 115             return false;
 116         }
 117
 118         return ok;
 119     }
 120
 121     virtual wxAnimationDecoder *Clone() const = 0;
 122     virtual wxAnimationType GetType() const = 0;
 123
 124     // convert given frame to wxImage
 125     virtual bool ConvertToImage(unsigned int frame, wxImage *image) const = 0;
 126
 127
 128     // frame specific data getters
 129
 130     // not all frames may be of the same size; e.g. GIF allows to
 131     // specify that between two frames only a smaller portion of the
 132     // entire animation has changed.
 133     virtual wxSize GetFrameSize(unsigned int frame) const = 0;
 134
 135     // the position of this frame in case it's not as big as m_szAnimation
 136     // or wxPoint(0,0) otherwise.
 137     virtual wxPoint GetFramePosition(unsigned int frame) const = 0;
 138
 139     // what should be done after displaying this frame.
 140     virtual wxAnimationDisposal GetDisposalMethod(unsigned int frame) const = 0;
 141
 142     // the number of milliseconds this frame should be displayed.
 143     // if returns -1 then the frame must be displayed forever.
 144     virtual long GetDelay(unsigned int frame) const = 0;
 145
 146     // the transparent colour for this frame if any or wxNullColour.
 147     virtual wxColour GetTransparentColour(unsigned int frame) const = 0;
 148
 149     // get global data
 150     wxSize GetAnimationSize() const { return m_szAnimation; }
 151     wxColour GetBackgroundColour() const { return m_background; }
 152     unsigned int GetFrameCount() const { return m_nFrames; }
 153
 154 protected:
 155     // checks the signature of the data in the given stream and returns true if it
 156     // appears to be a valid animation format recognized by the animation decoder;
 157     // this function should modify the stream current position without taking care
 158     // of restoring it since CanRead() will do it.
 159     virtual bool DoCanRead(wxInputStream& stream) const = 0;
 160
 161     wxSize m_szAnimation;
 162     unsigned int m_nFrames;
 163
 164     // this is the colour to use for the wxANIM_TOBACKGROUND disposal.
 165     // if not specified by the animation, it's set to wxNullColour
 166     wxColour m_background;
 167 };
 168
 169 #endif  // wxUSE_STREAMS
 170
 171 #endif  // _WX_ANIMDECOD_H
 172