source: GTP/trunk/App/Demos/Geom/OgreStuff/include/CEGUI/CEGUIImageset.h @ 1812

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