1/////////////////////////////////////////////////////////////////////////////
2// Name:        wx/animdecod.h
3// Purpose:     wxAnimationDecoder
4// Author:      Francesco Montorsi
5// CVS-ID:      $Id: animdecod.h 49563 2007-10-31 20:46:21Z VZ $
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
20class WXDLLIMPEXP_FWD_BASE wxInputStream;
21class 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 in on the screen.
34
35 2) wxAnimationDecoders contain the animation data in some internal var.
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 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 !!
56enum 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
73enum 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
87class WXDLLEXPORT wxAnimationDecoder : public wxObjectRefData
88{
89public:
90    wxAnimationDecoder()
91    {
92        m_background = wxNullColour;
93        m_nFrames = 0;
94    }
95    virtual ~wxAnimationDecoder() { }
96
97
98    virtual bool Load( wxInputStream& stream ) = 0;
99    virtual bool CanRead( wxInputStream& stream ) const = 0;
100
101    virtual wxAnimationDecoder *Clone() const = 0;
102    virtual wxAnimationType GetType() const = 0;
103
104    // convert given frame to wxImage
105    virtual bool ConvertToImage(unsigned int frame, wxImage *image) const = 0;
106
107
108    // frame specific data getters
109
110    // not all frames may be of the same size; e.g. GIF allows to
111    // specify that between two frames only a smaller portion of the
112    // entire animation has changed.
113    virtual wxSize GetFrameSize(unsigned int frame) const = 0;
114
115    // the position of this frame in case it's not as big as m_szAnimation
116    // or wxPoint(0,0) otherwise.
117    virtual wxPoint GetFramePosition(unsigned int frame) const = 0;
118
119    // what should be done after displaying this frame.
120    virtual wxAnimationDisposal GetDisposalMethod(unsigned int frame) const = 0;
121
122    // the number of milliseconds this frame should be displayed.
123    // if returns -1 then the frame must be displayed forever.
124    virtual long GetDelay(unsigned int frame) const = 0;
125
126    // the transparent colour for this frame if any or wxNullColour.
127    virtual wxColour GetTransparentColour(unsigned int frame) const = 0;
128
129    // get global data
130    wxSize GetAnimationSize() const { return m_szAnimation; }
131    wxColour GetBackgroundColour() const { return m_background; }
132    unsigned int GetFrameCount() const { return m_nFrames; }
133
134protected:
135    wxSize m_szAnimation;
136    unsigned int m_nFrames;
137
138    // this is the colour to use for the wxANIM_TOBACKGROUND disposal.
139    // if not specified by the animation, it's set to wxNullColour
140    wxColour m_background;
141};
142
143
144#endif  // wxUSE_STREAM
145#endif  // _WX_ANIMDECOD_H
146
147