source: OGRE/trunk/ogre_dependencies/Dependencies/include/CEGUI/CEGUIRenderer.h @ 692

Revision 692, 12.1 KB checked in by mattausch, 19 years ago (diff)

adding ogre 1.2 and dependencies

Line 
1/************************************************************************
2        filename:       CEGUIRenderer.h
3        created:        20/2/2004
4        author:         Paul D Turner
5       
6        purpose:        Defines interface for abstract Renderer class
7*************************************************************************/
8/*************************************************************************
9    Crazy Eddie's GUI System (http://www.cegui.org.uk)
10    Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
11
12    This library is free software; you can redistribute it and/or
13    modify it under the terms of the GNU Lesser General Public
14    License as published by the Free Software Foundation; either
15    version 2.1 of the License, or (at your option) any later version.
16
17    This library is distributed in the hope that it will be useful,
18    but WITHOUT ANY WARRANTY; without even the implied warranty of
19    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
20    Lesser General Public License for more details.
21
22    You should have received a copy of the GNU Lesser General Public
23    License along with this library; if not, write to the Free Software
24    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
25*************************************************************************/
26#ifndef _CEGUIRenderer_h_
27#define _CEGUIRenderer_h_
28
29#include "CEGUIBase.h"
30#include "CEGUIString.h"
31#include "CEGUIRect.h"
32#include "CEGUIColourRect.h"
33#include "CEGUIEventSet.h"
34
35
36// Start of CEGUI namespace section
37namespace CEGUI
38{
39/*!
40\brief
41        Enumerated type that contains the valid flags that can be to use when rendering image
42*/
43enum OrientationFlags {
44        FlipHorizontal          = 1,    //!< Horizontal flip the image
45        FlipVertical            = 2,    //!< Vertical flip the image
46        RotateRightAngle        = 4             //!< Rotate the image anticlockwise 90 degree
47};
48
49/*!
50\brief
51        Enumerated type that contains the valid diagonal-mode that specify how a quad is split into triangles when rendered with fx. a 3D API
52*/
53enum QuadSplitMode
54{
55        TopLeftToBottomRight,   //!< Diagonal goes from top-left to bottom-right
56        BottomLeftToTopRight    //!< Diagonal goes from bottom-left to top-right
57};
58
59
60/*!
61\brief
62        Abstract class defining the interface for Renderer objects.
63
64        Objects derived from Renderer are the means by which the GUI system interfaces
65        with specific rendering technologies.  To use a rendering system or API to draw
66        CEGUI imagery requires that an appropriate Renderer object be available.
67*/
68class CEGUIEXPORT Renderer : public EventSet
69{
70public:
71        static const String EventNamespace;                             //!< Namespace for global events
72
73        /*************************************************************************
74                Event name constants
75        *************************************************************************/
76        /*!
77                event that fires when the underlying display size had changed.
78               
79                It is important that all Renderer implementers fire this properly as the
80                system itself subscribes to this event.
81        */
82        static const String EventDisplaySizeChanged;
83
84
85        /*************************************************************************
86                Abstract interface methods
87        *************************************************************************/
88        /*!
89        \brief
90                Add a quad to the rendering queue.  All clipping and other adjustments should have been made prior to calling this.
91
92        \param dest_rect
93                Rect object describing the destination area (values are in pixels)
94
95        \param z
96                float value specifying the z co-ordinate / z order of the quad
97
98        \param tex
99                pointer to the Texture object that holds the imagery to be rendered
100
101        \param texture_rect
102                Rect object holding the area of \a tex that is to be rendered (values are in texture co-ordinates).
103
104        \param colours
105                ColourRect object describing the colour values that are to be applied when rendering.
106       
107        \param quad_split_mode
108                One of the QuadSplitMode values specifying the way quads are split into triangles
109
110        \return
111                Nothing
112        */
113        virtual void    addQuad(const Rect& dest_rect, float z, const Texture* tex, const Rect& texture_rect, const ColourRect& colours, QuadSplitMode quad_split_mode) = 0;
114
115
116        /*!
117        \brief
118                Perform final rendering for all quads that have been queued for rendering
119
120                The contents of the rendering queue is retained and can be rendered again as required.  If the contents is not required call clearRenderList().
121
122        \return
123                Nothing
124        */
125        virtual void    doRender(void) = 0;
126
127
128        /*!
129        \brief
130                Clears all queued quads from the render queue.
131       
132        \return
133                Nothing
134        */
135        virtual void    clearRenderList(void) = 0;
136
137
138        /*!
139        \brief
140                Enable or disable the queueing of quads from this point on.
141
142                This only affects queueing.  If queueing is turned off, any calls to addQuad will cause the quad to be rendered directly.  Note that
143                disabling queueing will not cause currently queued quads to be rendered, nor is the queue cleared - at any time the queue can still
144                be drawn by calling doRender, and the list can be cleared by calling clearRenderList.  Re-enabling the queue causes subsequent quads
145                to be added as if queueing had never been disabled.
146
147        \param setting
148                true to enable queueing, or false to disable queueing (see notes above).
149
150        \return
151                Nothing
152        */
153        virtual void    setQueueingEnabled(bool setting) = 0;
154
155
156        /*!
157        \brief
158                Creates a 'null' Texture object.
159
160        \return
161                a newly created Texture object.  The returned Texture object has no size or imagery associated with it, and is
162                generally of little or no use.
163        */
164        virtual Texture*        createTexture(void) = 0;
165
166
167        /*!
168        \brief
169                Create a Texture object using the given image file.
170
171        \param filename
172                String object that specifies the path and filename of the image file to use when creating the texture.
173
174    \param resourceGroup
175        Resource group identifier to be passed to the resource provider when loading the texture file.
176
177        \return
178                a newly created Texture object.  The initial contents of the texture memory is the requested image file.
179
180        \note
181                Textures are always created with a size that is a power of 2.  If the file you specify is of a size that is not
182                a power of two, the final size will be rounded up.  Additionally, textures are always square, so the ultimate
183                size is governed by the larger of the width and height of the specified file.  You can check the ultimate sizes
184                by querying the texture after creation.
185        */
186        virtual Texture*        createTexture(const String& filename, const String& resourceGroup) = 0;
187
188
189        /*!
190        \brief
191                Create a Texture object with the given pixel dimensions as specified by \a size.  NB: Textures are always square.
192
193        \param size
194                float value that specifies the size to use for the width and height when creating the new texture.
195
196        \return
197                a newly created Texture object.  The initial contents of the texture memory is undefined / random.
198
199        \note
200                Textures are always created with a size that is a power of 2.  If you specify a size that is not a power of two, the final
201                size will be rounded up.  So if you specify a size of 1024, the texture will be (1024 x 1024), however, if you specify a size
202                of 1025, the texture will be (2048 x 2048).  You can check the ultimate size by querying the texture after creation.
203        */     
204        virtual Texture*        createTexture(float size) = 0;
205
206
207        /*!
208        \brief
209                Destroy the given Texture object.
210
211        \param texture
212                pointer to the Texture object to be destroyed
213
214        \return
215                Nothing
216        */
217        virtual void            destroyTexture(Texture* texture) = 0;
218
219       
220        /*!
221        \brief
222                Destroy all Texture objects.
223
224        \return
225                Nothing
226        */
227        virtual void            destroyAllTextures(void) = 0;
228
229
230        /*!
231        \brief
232                Return whether queueing is enabled.
233
234        \return
235                true if queueing is enabled, false if queueing is disabled.
236        */
237        virtual bool    isQueueingEnabled(void) const = 0;
238
239
240        /*!
241        \brief
242                Return the current width of the display in pixels
243
244        \return
245                float value equal to the current width of the display in pixels.
246        */
247        virtual float   getWidth(void) const    = 0;
248
249
250        /*!
251        \brief
252                Return the current height of the display in pixels
253
254        \return
255                float value equal to the current height of the display in pixels.
256        */
257        virtual float   getHeight(void) const   = 0;
258
259
260        /*!
261        \brief
262                Return the size of the display in pixels
263
264        \return
265                Size object describing the dimensions of the current display.
266        */
267        virtual Size    getSize(void) const             = 0;
268
269
270        /*!
271        \brief
272                Return a Rect describing the screen
273
274        \return
275                A Rect object that describes the screen area.  Typically, the top-left values are always 0, and the size of the area described is
276                equal to the screen resolution.
277        */
278        virtual Rect    getRect(void) const             = 0;
279
280
281        /*!
282        \brief
283                Return the maximum texture size available
284
285        \return
286                Size of the maximum supported texture in pixels (textures are always assumed to be square)
287        */
288        virtual uint    getMaxTextureSize(void) const   = 0;
289
290
291        /*!
292        \brief
293                Return the horizontal display resolution dpi
294
295        \return
296                horizontal resolution of the display in dpi.
297        */
298        virtual uint    getHorzScreenDPI(void) const    = 0;
299
300
301        /*!
302        \brief
303                Return the vertical display resolution dpi
304
305        \return
306                vertical resolution of the display in dpi.
307        */
308        virtual uint    getVertScreenDPI(void) const    = 0;
309
310
311        /*************************************************************************
312                Basic stuff we provide in base class
313        *************************************************************************/
314        /*!
315        \brief
316                Reset the z co-ordinate for rendering.
317       
318        \return
319                Nothing
320        */
321        void    resetZValue(void)                               {d_current_z = GuiZInitialValue;}
322
323
324        /*!
325        \brief
326                Update the z co-ordinate for the next major UI element (window).
327
328        \return
329                Nothing
330        */
331        void    advanceZValue(void)                             {d_current_z -= GuiZElementStep;}
332
333
334        /*!
335        \brief
336                return the current Z value to use (equates to layer 0 for this UI element).
337
338        \return
339                float value that specifies the z co-ordinate to be used for layer 0 on the current GUI element.
340        */
341        float   getCurrentZ(void) const                 {return d_current_z;}
342
343
344        /*!
345        \brief
346                return the z co-ordinate to use for the requested layer on the current GUI element.
347
348        \param layer
349                Specifies the layer to return the Z co-ordinate for.  Each GUI element can use up to 10 layers, so valid inputs are 0 to 9 inclusive.
350                If you specify an invalid value for \a layer, results are undefined.
351
352        \return
353                float value that specifies the Z co-ordinate for layer \a layer on the current GUI element.
354        */
355        float   getZLayer(uint layer) const             {return d_current_z - ((float)layer * GuiZLayerStep);}
356
357
358    /*!
359    \brief
360        Return identification string for the renderer module.  If the internal id string has not been
361        set by the Renderer module creator, a generic string of "Unknown renderer" will be returned.
362
363    \return
364        String object holding a string that identifies the Renderer in use.
365    */
366    const String& getIdentifierString() const;
367
368    virtual ResourceProvider* createResourceProvider(void);
369
370protected:
371        /*************************************************************************
372                Construction and Destruction
373        *************************************************************************/
374        Renderer(void);
375
376public:         // for luabind support
377        virtual ~Renderer(void);
378
379private:
380        /*************************************************************************
381                Implementation constants
382        *************************************************************************/
383        static const float      GuiZInitialValue;               //!< Initial value to use for 'z' each frame.
384        static const float      GuiZElementStep;                //!< Value to step 'z' for each GUI element.
385        static const float      GuiZLayerStep;                  //!< Value to step 'z' for each GUI layer.
386
387
388        /*************************************************************************
389                Implementation Data
390        *************************************************************************/
391        float   d_current_z;            //!< The current z co-ordinate value.
392
393protected:
394    ResourceProvider* d_resourceProvider;      //!< Holds the pointer to the ResourceProvider object.
395    String d_identifierString;                 //!< String that holds some id information about the renderer.
396};
397
398} // End of  CEGUI namespace section
399
400
401#endif  // end of guard _CEGUIRenderer_h_
Note: See TracBrowser for help on using the repository browser.