Context Navigation

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

Revision 657, 16.7 KB checked in by mattausch, 18 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
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 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
102	public: // For luabind support
103	/*!
104	\brief
105	Destroys Imageset objects
106	*/
107	~Imageset(void);
108
109
110	public:
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
468	protected:
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.

Download in other formats: