include/wx/animdecod.h

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