Context Navigation

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

Rev	Line
[657]	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: