source: OGRE/trunk/ogrenew/Dependencies/include/CEGUI/CEGUIImageset.h @ 657

Revision 657, 16.7 KB checked in by mattausch, 19 years ago (diff)

added ogre dependencies and patched ogre sources

Line 
1/************************************************************************
2        filename:       CEGUIImageset.h
3        created:        21/2/2004
4        author:         Paul D Turner
5       
6        purpose:        Defines the interface for the Imageset 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 _CEGUIImageset_h_
27#define _CEGUIImageset_h_
28
29#include "CEGUIBase.h"
30#include "CEGUIString.h"
31#include "CEGUIRect.h"
32#include "CEGUIColourRect.h"
33#include "CEGUIImagesetManager.h"
34#include "CEGUIImage.h"
35#include "CEGUIIteratorBase.h"
36
37#include <map>
38
39
40#if defined(_MSC_VER)
41#       pragma warning(push)
42#       pragma warning(disable : 4251)
43#endif
44
45
46// Start of CEGUI namespace section
47namespace CEGUI
48{
49
50/*!
51\brief
52        Offers functions to define, access, and draw, a set of image components on a single graphical surface or Texture.
53
54        Imageset objects are a means by which a single graphical image (file, Texture, etc), can be split into a number
55        of 'components' which can later be accessed via name.  The components of an Imageset can queried for
56        various details, and sent to the Renderer object for drawing.
57*/
58class CEGUIEXPORT Imageset
59{
60        friend class Imageset_xmlHandler;
61private:
62        typedef std::map<String, Image> ImageRegistry;
63
64        /*************************************************************************
65                Friends to allow access to constructors and destructors
66        *************************************************************************/
67        friend Imageset*        ImagesetManager::createImageset(const String& name, Texture* texture);
68        friend Imageset*        ImagesetManager::createImageset(const String& filename, const String& resourceGroup);
69        friend void                     ImagesetManager::destroyImageset(const String& name);
70
71
72        /*************************************************************************
73                Construction and Destruction (private, only ImagesetManager can
74                create and destroy Imageset objects).
75        *************************************************************************/
76        /*!
77        \brief
78                Construct a new Imageset object.  Object will initially have no Images defined
79
80        \param texture
81                Texture object that holds the imagery for the Imageset being created.
82        */
83        Imageset(const String& name, Texture* texture);
84
85
86        /*!
87        \brief
88                Construct a new Imageset object using data contained in the specified file.
89
90        \param filename
91                String object that holds the name of the Imageset data file that is to be processed.
92
93    \param resourceGroup
94        Resource group identifier to be passed to the resource manager.  NB: This affects the
95        imageset xml file only, the texture loaded may have its own group specified in the XML file.
96
97        \exception      FileIOException         thrown if something goes wrong while processing the file \a filename.
98        */
99        Imageset(const String& filename, const String& resourceGroup);
100
101
102public: // For luabind support
103        /*!
104        \brief
105                Destroys Imageset objects
106        */
107        ~Imageset(void);
108
109
110public:
111        typedef ConstBaseIterator<ImageRegistry>        ImageIterator;  //!< Iterator type for this collection
112
113        /*************************************************************************
114                Public interface
115        *************************************************************************/
116        /*!
117        \brief
118                return Texture object for this Imageset
119
120        \return
121                Texture object that holds the imagery for this Imageset
122        */
123        Texture*        getTexture(void) const                                          {return d_texture;}
124
125
126        /*!
127        \brief
128                return String object holding the name of the Imageset
129
130        \return
131                String object that holds the name of the Imageset.
132        */
133        const String&   getName(void) const                                             {return d_name;}
134
135
136        /*!
137        \brief
138                return number of images defined for this Imageset
139
140        \return
141                uint value equal to the number of Image objects defined for the Imageset
142        */
143        uint      getImageCount(void) const               {return (uint)d_images.size();}
144
145 
146        /*!
147        \brief
148                return true if an Image with the specified name exists.
149
150        \param name
151                String object holding the name of the Image to look for.
152
153        \return
154                true if an Image object named \a name is defined for this Imageset, else false.
155        */
156        bool            isImageDefined(const String& name) const        {return d_images.find(name) != d_images.end();}
157
158 
159        /*!
160        \brief
161                return a copy of the Image object for the named image
162
163        \param name
164                String object holding the name of the Image object to be returned
165
166        \return
167                constant Image object that has the requested name.
168
169        \exception UnknownObjectException       thrown if no Image named \a name is defined for the Imageset
170        */
171        const Image&    getImage(const String& name) const;
172
173
174        /*!
175        \brief
176                remove the definition for the Image with the specified name.  If no such Image exists, nothing happens.
177
178        \param name
179                String object holding the name of the Image object to be removed from the Imageset,
180        \return
181                Nothing.
182        */
183        void    undefineImage(const String& name);
184
185
186        /*!
187        \brief
188                Removes the definitions for all Image objects currently defined in the Imageset
189
190        \return
191                Nothing
192        */
193        void    undefineAllImages(void);
194
195
196        /*!
197        \brief
198                return a Size object describing the dimensions of the named image.
199
200        \param name
201                String object holding the name of the Image.
202
203        \return
204                Size object holding the dimensions of the requested Image.
205
206        \exception UnknownObjectException       thrown if no Image named \a name is defined for the Imageset
207        */
208        Size    getImageSize(const String& name) const                  {return getImage(name).getSize();}
209
210
211        /*!
212        \brief
213                return the width of the named image.
214
215        \param name
216                String object holding the name of the Image.
217
218        \return
219                float value equalling the width of the requested Image.
220
221        \exception UnknownObjectException       thrown if no Image named \a name is defined for the Imageset
222        */
223        float   getImageWidth(const String& name) const                 {return getImage(name).getWidth();}
224
225
226        /*!
227        \brief
228                return the height of the named image.
229
230        \param name
231                String object holding the name of the Image.
232
233        \return
234                float value equalling the height of the requested Image.
235
236        \exception UnknownObjectException       thrown if no Image named \a name is defined for the Imageset
237        */
238        float   getImageHeight(const String& name) const                {return getImage(name).getHeight();}
239
240
241        /*!
242        \brief
243                return the rendering offsets applied to the named image.
244
245        \param name
246                String object holding the name of the Image.
247
248        \return
249                Point object that holds the rendering offsets for the requested Image.
250
251        \exception UnknownObjectException       thrown if no Image named \a name is defined for the Imageset
252        */
253        Point   getImageOffset(const String& name) const                {return getImage(name).getOffsets();}
254
255
256        /*!
257        \brief
258                return the x rendering offset for the named image.
259
260        \param name
261                String object holding the name of the Image.
262
263        \return
264                float value equal to the x rendering offset applied when drawing the requested Image.
265
266        \exception UnknownObjectException       thrown if no Image named \a name is defined for the Imageset
267        */
268        float   getImageOffsetX(const String& name) const               {return getImage(name).getOffsetX();}
269
270
271        /*!
272        \brief
273                return the y rendering offset for the named image.
274
275        \param name
276                String object holding the name of the Image.
277
278        \return
279                float value equal to the y rendering offset applied when drawing the requested Image.
280
281        \exception UnknownObjectException       thrown if no Image named \a name is defined for the Imageset
282        */
283        float   getImageOffsetY(const String& name) const               {return getImage(name).getOffsetY();}
284
285       
286        /*!
287        \brief
288                Define a new Image for this Imageset
289
290        \param name
291                String object holding the name that will be assigned to the new Image, which must be unique within the Imageset.
292
293        \param position
294                Point object describing the pixel location of the Image on the image file / texture associated with this Imageset.
295
296        \param size
297                Size object describing the dimensions of the Image, in pixels.
298
299        \param render_offset
300                Point object describing the offsets, in pixels, that are to be applied to the Image when it is drawn.
301
302        \return
303                Nothing
304
305        \exception AlreadyExistsException       thrown if an Image named \a name is already defined for this Imageset
306        */
307        void    defineImage(const String& name, const Point& position, const Size& size, const Point& render_offset)
308        {
309                defineImage(name, Rect(position.d_x, position.d_y, position.d_x + size.d_width, position.d_y + size.d_height), render_offset);
310        }
311
312
313        /*!
314        \brief
315                Define a new Image for this Imageset
316
317        \param name
318                String object holding the name that will be assigned to the new Image, which must be unique within the Imageset.
319
320        \param image_rect
321                Rect object describing the area on the image file / texture associated with this Imageset that will be used for the Image.
322
323        \param render_offset
324                Point object describing the offsets, in pixels, that are to be applied to the Image when it is drawn.
325
326        \return
327                Nothing
328
329        \exception AlreadyExistsException       thrown if an Image named \a name is already defined for this Imageset
330        */
331        void    defineImage(const String& name, const Rect& image_rect, const Point& render_offset);
332
333
334        /*!
335        \brief
336                Queues an area of the associated Texture the be drawn on the screen.  Low-level routine to be used carefully!
337
338        \param source_rect
339                Rect object describing the area of the image file / texture that is to be queued for drawing
340
341        \param dest_rect
342                Rect describing the area of the screen that will be filled with the imagery from \a source_rect.
343
344        \param z
345                float value specifying 'z' order.  0 is topmost with increasing values moving back into the screen.
346
347        \param clip_rect
348                Rect object describing a 'clipping rectangle' that will be applied when drawing the requested imagery
349
350        \param colours
351                ColourRect object holding the ARGB colours to be applied to the four corners of the rendered imagery.
352       
353        \param quad_split_mode
354                One of the QuadSplitMode values specifying the way quads are split into triangles
355
356        \return
357                Nothing
358        */
359        void    draw(const Rect& source_rect, const Rect& dest_rect, float z, const Rect& clip_rect,const ColourRect& colours, QuadSplitMode quad_split_mode) const;
360
361
362        /*!
363        \brief
364                Queues an area of the associated Texture the be drawn on the screen.  Low-level routine to be used carefully!
365
366        \param source_rect
367                Rect object describing the area of the image file / texture that is to be queued for drawing
368
369        \param dest_rect
370                Rect describing the area of the screen that will be filled with the imagery from \a source_rect.
371
372        \param z
373                float value specifying 'z' order.  0 is topmost with increasing values moving back into the screen.
374
375        \param clip_rect
376                Rect object describing a 'clipping rectangle' that will be applied when drawing the requested imagery
377
378        \param top_left_colour
379                colour to be applied to the top left corner of the rendered imagery.
380
381        \param top_right_colour
382                colour to be applied to the top right corner of the rendered imagery.
383
384        \param bottom_left_colour
385                colour to be applied to the bottom left corner of the rendered imagery.
386
387        \param bottom_right_colour
388                colour to be applied to the bottom right corner of the rendered imagery.
389       
390        \param quad_split_mode
391                One of the QuadSplitMode values specifying the way quads are split into triangles
392
393        \return
394                Nothing
395        */
396        void    draw(const Rect& source_rect, const Rect& dest_rect, float z, const Rect& clip_rect, const colour& top_left_colour = 0xFFFFFFFF, const colour& top_right_colour = 0xFFFFFFFF,  const colour& bottom_left_colour = 0xFFFFFFFF, const colour& bottom_right_colour = 0xFFFFFFFF, QuadSplitMode quad_split_mode = TopLeftToBottomRight) const
397        {
398                draw(source_rect, dest_rect, z, clip_rect, ColourRect(top_left_colour, top_right_colour, bottom_left_colour, bottom_right_colour), quad_split_mode);
399        }
400
401
402        /*!
403        \brief
404                Return whether this Imageset is auto-scaled.
405
406        \return
407                true if Imageset is auto-scaled, false if not.
408        */
409        bool    isAutoScaled(void) const                {return d_autoScale;}
410
411
412        /*!
413        \brief
414                Return the native display size for this Imageset.  This is only relevant if the Imageset is being auto-scaled.
415
416        \return
417                Size object describing the native display size for this Imageset.
418        */
419        Size    getNativeResolution(void) const {return Size(d_nativeHorzRes, d_nativeVertRes);}
420
421
422        /*!
423        \brief
424                Enable or disable auto-scaling for this Imageset.
425
426        \param setting
427                true to enable auto-scaling, false to disable auto-scaling.
428
429        \return
430                Nothing.
431        */
432        void    setAutoScalingEnabled(bool setting);
433
434
435        /*!
436        \brief
437                Set the native resolution for this Imageset
438
439        \param size
440                Size object describing the new native screen resolution for this Imageset.
441
442        \return
443                Nothing
444        */
445        void    setNativeResolution(const Size& size);
446
447
448        /*!
449        \brief
450                Notify the Imageset of the current (usually new) display resolution.
451
452        \param size
453                Size object describing the display resolution
454
455        \return
456                Nothing
457        */
458        void    notifyScreenResolution(const Size& size);
459
460
461        /*!
462        \brief
463                Return an Imageset::ImageIterator object that can be used to iterate over the Image objects in the Imageset.
464        */
465        ImageIterator   getIterator(void) const;
466
467
468protected:
469        /*************************************************************************
470                Implementation Constants
471        *************************************************************************/
472        static const char       ImagesetSchemaName[];                   //!< Filename of the XML schema used for validating Imageset files.
473
474
475        /*************************************************************************
476                Implementation Functions
477        *************************************************************************/
478        /*!
479        \brief
480                Initialise the Imageset with information taken from the specified file.
481
482        \param filename
483                String object that holds the name of the Imageset data file that is to be processed.
484
485    \param resourceGroup
486        Resource group identifier to be passed to the resource manager.  NB: This affects the
487        imageset xml file only, the texture loaded may have its own group specified in the XML file.
488
489        \return
490                Nothing
491
492        \exception      FileIOException         thrown if something goes wrong while processing the file \a filename.
493        */     
494        void    load(const String& filename, const String& resourceGroup);
495
496
497        /*!
498        \brief
499                Unloads all loaded data and leaves the Imageset in a clean (but un-usable) state.  This should be called for cleanup purposes only.
500        */
501        void    unload(void);
502
503
504        /*!
505        \brief
506                set the Texture object to be used by this Imageset.  Changing textures on an Imageset that is in use is not a good idea!
507
508        \param texture
509                Texture object to be used by the Imageset.  The old texture is NOT disposed of, that is the clients responsibility.
510
511        \return
512                Nothing
513
514        \exception      NullObjectException             thrown if \a texture is NULL
515        */
516        void    setTexture(Texture* texture);
517
518
519        /*!
520        \brief
521                Sets the scaling factor for all Images that are a part of this Imageset.
522
523        \return
524                Nothing.
525        */
526        void    updateImageScalingFactors(void);
527
528        /*************************************************************************
529                Implementation Data
530        *************************************************************************/
531        String                  d_name;                                         //!< Holds the name of this imageset.
532        ImageRegistry   d_images;                                       //!< Registry of Image objects for the images defined for this Imageset
533        Texture*                d_texture;                                      //!< Texture object that handles imagery for this Imageset
534
535        // auto-scaling fields
536        bool    d_autoScale;                    //!< true when auto-scaling is enabled.
537        float   d_horzScaling;                  //!< current horizontal scaling factor.
538        float   d_vertScaling;                  //!< current vertical scaling factor.
539        float   d_nativeHorzRes;                //!< native horizontal resolution for this Imageset.
540        float   d_nativeVertRes;                //!< native vertical resolution for this Imageset.
541};
542
543} // End of  CEGUI namespace section
544
545#if defined(_MSC_VER)
546#       pragma warning(pop)
547#endif
548
549#endif  // end of guard _CEGUIImageset_h_
Note: See TracBrowser for help on using the repository browser.