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