Context Navigation

CEGUIImageset.h @ 1809

Revision 1809, 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
47	namespace 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	*/
58	class CEGUIEXPORT Imageset
59	{
60	friend class Imageset_xmlHandler;
61	private:
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
131	public: // For luabind support
132	/*!
133	\brief
134	Destroys Imageset objects
135	*/
136	~Imageset(void);
137
138
139	public:
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
510	protected:
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.

Context Navigation

source: GTP/trunk/Lib/Geom/OgreStuff/include/CEGUI/CEGUIImageset.h @ 1809

Download in other formats: