1 /***********************************************************************
2     created:    Sat Jan 17 2009
3     author:     Paul D Turner
4 *************************************************************************/
5 /***************************************************************************
6  *   Copyright (C) 2004 - 2011 Paul D Turner & The CEGUI Development Team
7  *
8  *   Permission is hereby granted, free of charge, to any person obtaining
9  *   a copy of this software and associated documentation files (the
10  *   "Software"), to deal in the Software without restriction, including
11  *   without limitation the rights to use, copy, modify, merge, publish,
12  *   distribute, sublicense, and/or sell copies of the Software, and to
13  *   permit persons to whom the Software is furnished to do so, subject to
14  *   the following conditions:
15  *
16  *   The above copyright notice and this permission notice shall be
17  *   included in all copies or substantial portions of the Software.
18  *
19  *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
20  *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
21  *   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
22  *   IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
23  *   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
24  *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25  *   OTHER DEALINGS IN THE SOFTWARE.
26  ***************************************************************************/
27 #ifndef _CEGUIRenderEffect_h_
28 #define _CEGUIRenderEffect_h_
29 
30 #include "CEGUI/Base.h"
31 
32 // Start of CEGUI namespace section
33 namespace CEGUI
34 {
35 /*!
36 \brief
37     Interface for objects that hook into RenderingWindow to affect the rendering
38     process, thus allowing various effects to be achieved.
39 */
40 class CEGUIEXPORT RenderEffect :
41     public AllocatedObject<RenderEffect>
42 {
43 public:
~RenderEffect()44     virtual ~RenderEffect() {};
45     /*!
46     \brief
47         Return the number of passes required by this effect.
48 
49     \return
50         integer value indicating the number of rendering passes required to
51         fully render this effect.
52     */
53     virtual int getPassCount() const = 0;
54 
55     /*!
56     \brief
57         Function called prior to RenderingWindow::draw being called.  This is
58         intended to be used for any required setup / state initialisation and is
59         called once for each pass in the effect.
60 
61     \param pass
62         Indicates the pass number to be initialised (starting at pass 0).
63 
64     \note
65         Note that this function is called \e after any standard state
66         initialisation that might be peformed by the Renderer module.
67     */
68     virtual void performPreRenderFunctions(const int pass) = 0;
69 
70     /*!
71     \brief
72         Function called after RenderingWindow::draw is called.  This is intended
73         to be used for any required cleanup / state restoration.  This function
74         is called <em>once only</em>, unlike performPreRenderFunctions which may
75         be called multiple times; once for each pass in the effect.
76     \note
77         Note that this function is called \e before any standard state
78         cleanup that might be peformed by the Renderer module.
79     */
80     virtual void performPostRenderFunctions() = 0;
81 
82     /*!
83     \brief
84         Function called to generate geometry for the RenderingWindow.
85 
86         The geometry generated should be fully unclipped and window local.  The
87         origin for the geometry is located at the top-left corner.
88 
89     \param window
90         The RenderingWindow object that is being processed.
91 
92     \param geometry
93         GeometryBuffer object where the generated geometry should be added.
94         This object will be cleared before this function is invoked.
95 
96     \return
97         boolean value indicating whether the RenderingWindow should generate
98         it's own geometry.
99         - true if the RenderingWindow should generate it's own geometry.  You
100         will usually only return true if you do not need to use custom geometry.
101         - false if you have added any required geometry needed to represent the
102         RenderingWindow.
103     */
104     virtual bool realiseGeometry(RenderingWindow& window,
105                                  GeometryBuffer& geometry) = 0;
106 
107     /*!
108     \brief
109         Function called to perform any time based updates on the RenderEffect
110         state.
111 
112     \note
113         This function should only affect the internal state of the RenderEffect
114         object.  This function should definitely \e not be used to directly
115         affect any render states of the underlying rendering API or engine.
116 
117     \param elapsed
118         The number of seconds that have elapsed since the last time this
119         function was called.
120 
121     \param window
122         RenderingWindow object that the RenderEffect is being applied to.
123 
124     \return
125         boolean that indicates whether the window geometry will still be valid
126         after the update.
127     */
128     virtual bool update(const float elapsed, RenderingWindow& window) = 0;
129 };
130 
131 } // End of  CEGUI namespace section
132 
133 #endif  // end of guard _CEGUIRenderEffect_h_
134