Offers functions to define, access, and draw, a set of image components on a single graphical surface or Texture. More...

Collaboration diagram for CEGUI::Imageset:

Public Types
typedef ConstBaseIterator < ImageRegistry >	ImageIterator
	Iterator type for this collection.

Public Member Functions
	~Imageset (void)
	Destroys Imageset objects.

Texture *	getTexture (void) const
	return Texture object for this Imageset More...

const String &	getName (void) const
	return String object holding the name of the Imageset More...

uint	getImageCount (void) const
	return number of images defined for this Imageset More...

bool	isImageDefined (const String &name) const
	return true if an Image with the specified name exists. More...

const Image &	getImage (const String &name) const
	return a copy of the Image object for the named image More...

void	undefineImage (const String &name)
	remove the definition for the Image with the specified name. If no such Image exists, nothing happens. More...

void	undefineAllImages (void)
	Removes the definitions for all Image objects currently defined in the Imageset. More...

Size	getImageSize (const String &name) const
	return a Size object describing the dimensions of the named image. More...

float	getImageWidth (const String &name) const
	return the width of the named image. More...

float	getImageHeight (const String &name) const
	return the height of the named image. More...

Point	getImageOffset (const String &name) const
	return the rendering offsets applied to the named image. More...

float	getImageOffsetX (const String &name) const
	return the x rendering offset for the named image. More...

float	getImageOffsetY (const String &name) const
	return the y rendering offset for the named image. More...

void	defineImage (const String &name, const Point &position, const Size &size, const Point &render_offset)
	Define a new Image for this Imageset. More...

void	defineImage (const String &name, const Rect &image_rect, const Point &render_offset)
	Define a new Image for this Imageset. More...

void	draw (const Rect &source_rect, const Rect &dest_rect, float z, const Rect &clip_rect, const ColourRect &colours, QuadSplitMode quad_split_mode) const
	Queues an area of the associated Texture the be drawn on the screen. Low-level routine to be used carefully! More...

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
	Queues an area of the associated Texture the be drawn on the screen. Low-level routine to be used carefully! More...

bool	isAutoScaled (void) const
	Return whether this Imageset is auto-scaled. More...

Size	getNativeResolution (void) const
	Return the native display size for this Imageset. This is only relevant if the Imageset is being auto-scaled. More...

void	setAutoScalingEnabled (bool setting)
	Enable or disable auto-scaling for this Imageset. More...

void	setNativeResolution (const Size &size)
	Set the native resolution for this Imageset. More...

void	notifyScreenResolution (const Size &size)
	Notify the Imageset of the current (usually new) display resolution. More...

ImageIterator	getIterator (void) const
	Return an Imageset::ImageIterator object that can be used to iterate over the Image objects in the Imageset.

void	writeXMLToStream (XMLSerializer &xml_stream) const
	Writes an xml representation of this Imageset to out_stream. More...

Static Public Member Functions
static void	setDefaultResourceGroup (const String &resourceGroup)
	Sets the default resource group to be used when loading imageset data. More...

static const String &	getDefaultResourceGroup ()
	Returns the default resource group currently set for Imagesets. More...

Protected Member Functions
void	load (const String &filename, const String &resourceGroup)
	Initialise the Imageset with information taken from the specified file. More...

void	unload (void)
	Unloads all loaded data and leaves the Imageset in a clean (but un-usable) state. This should be called for cleanup purposes only.

void	setTexture (Texture *texture)
	set the Texture object to be used by this Imageset. Changing textures on an Imageset that is in use is not a good idea! More...

void	updateImageScalingFactors (void)
	Sets the scaling factor for all Images that are a part of this Imageset. More...

Protected Attributes
String	d_name
	Holds the name of this imageset.

ImageRegistry	d_images
	Registry of Image objects for the images defined for this Imageset.

Texture *	d_texture
	Texture object that handles imagery for this Imageset.

String	d_textureFilename
	String holding the name of the texture filename (if any).

bool	d_autoScale
	true when auto-scaling is enabled.

float	d_horzScaling
	current horizontal scaling factor.

float	d_vertScaling
	current vertical scaling factor.

float	d_nativeHorzRes
	native horizontal resolution for this Imageset.

float	d_nativeVertRes
	native vertical resolution for this Imageset.

Static Protected Attributes
static const char	ImagesetSchemaName [] = "Imageset.xsd"
	Filename of the XML schema used for validating Imageset files.

static String	d_defaultResourceGroup
	Default resource group specifically for Imagesets.

Friends
class	Imageset_xmlHandler

Imageset *	ImagesetManager::createImageset (const String &name, Texture *texture)

Imageset *	ImagesetManager::createImageset (const String &filename, const String &resourceGroup)

Imageset *	ImagesetManager::createImagesetFromImageFile (const String &name, const String &filename, const String &resourceGroup)

void	ImagesetManager::destroyImageset (const String &name)

Detailed Description

Offers functions to define, access, and draw, a set of image components on a single graphical surface or Texture.

Imageset objects are a means by which a single graphical image (file, Texture, etc), can be split into a number of 'components' which can later be accessed via name. The components of an Imageset can queried for various details, and sent to the Renderer object for drawing.

Member Function Documentation

void CEGUI::Imageset::defineImage	(	const String &	name,
		const Point &	position,
		const Size &	size,
		const Point &	render_offset
	)

inline

Define a new Image for this Imageset.

Parameters

name	String object holding the name that will be assigned to the new Image, which must be unique within the Imageset.
position	Point object describing the pixel location of the Image on the image file / texture associated with this Imageset.
size	Size object describing the dimensions of the Image, in pixels.
render_offset	Point object describing the offsets, in pixels, that are to be applied to the Image when it is drawn.

Returns: Nothing

Exceptions

AlreadyExistsException thrown if an Image named name is already defined for this Imageset

Referenced by CEGUI::FreeTypeFont::rasterize().

void CEGUI::Imageset::defineImage	(	const String &	name,
		const Rect &	image_rect,
		const Point &	render_offset
	)

Define a new Image for this Imageset.

Parameters

name	String object holding the name that will be assigned to the new Image, which must be unique within the Imageset.
image_rect	Rect object describing the area on the image file / texture associated with this Imageset that will be used for the Image.
render_offset	Point object describing the offsets, in pixels, that are to be applied to the Image when it is drawn.

Returns: Nothing

Exceptions

AlreadyExistsException thrown if an Image named name is already defined for this Imageset

References d_autoScale, d_horzScaling, d_images, d_name, d_vertScaling, and isImageDefined().

void CEGUI::Imageset::draw	(	const Rect &	source_rect,
		const Rect &	dest_rect,
		float	z,
		const Rect &	clip_rect,
		const ColourRect &	colours,
		QuadSplitMode	quad_split_mode
	)		const

Queues an area of the associated Texture the be drawn on the screen. Low-level routine to be used carefully!

Parameters

source_rect	Rect object describing the area of the image file / texture that is to be queued for drawing
dest_rect	Rect describing the area of the screen that will be filled with the imagery from source_rect.
z	float value specifying 'z' order. 0 is topmost with increasing values moving back into the screen.
clip_rect	Rect object describing a 'clipping rectangle' that will be applied when drawing the requested imagery
colours	ColourRect object holding the ARGB colours to be applied to the four corners of the rendered imagery.
quad_split_mode	One of the QuadSplitMode values specifying the way quads are split into triangles

Returns: Nothing

References CEGUI::Renderer::addQuad(), d_texture, CEGUI::Rect::getHeight(), CEGUI::Rect::getIntersection(), CEGUI::Texture::getRenderer(), CEGUI::Rect::getWidth(), CEGUI::Texture::getXScale(), and CEGUI::Texture::getYScale().

Referenced by CEGUI::Image::draw().

void CEGUI::Imageset::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

inline

Queues an area of the associated Texture the be drawn on the screen. Low-level routine to be used carefully!

Parameters

source_rect	Rect object describing the area of the image file / texture that is to be queued for drawing
dest_rect	Rect describing the area of the screen that will be filled with the imagery from source_rect.
z	float value specifying 'z' order. 0 is topmost with increasing values moving back into the screen.
clip_rect	Rect object describing a 'clipping rectangle' that will be applied when drawing the requested imagery
top_left_colour	colour to be applied to the top left corner of the rendered imagery.
top_right_colour	colour to be applied to the top right corner of the rendered imagery.
bottom_left_colour	colour to be applied to the bottom left corner of the rendered imagery.
bottom_right_colour	colour to be applied to the bottom right corner of the rendered imagery.
quad_split_mode	One of the QuadSplitMode values specifying the way quads are split into triangles

Returns: Nothing

static const String& CEGUI::Imageset::getDefaultResourceGroup ( void )

inlinestatic

Returns the default resource group currently set for Imagesets.

Returns: String describing the default resource group identifier that will be used when loading Imageset data.

const Image & CEGUI::Imageset::getImage ( const String & name ) const

return a copy of the Image object for the named image

Parameters

name	String object holding the name of the Image object to be returned

Returns: constant Image object that has the requested name.

Exceptions

UnknownObjectException thrown if no Image named name is defined for the Imageset

References d_images, and d_name.

Referenced by CEGUI::PixmapFont::defineMapping(), CEGUI::ImageDim::getValue_impl(), CEGUI::FreeTypeFont::rasterize(), CEGUI::FrameWindow::setEWSizingCursorImage(), CEGUI::ImageryComponent::setImage(), CEGUI::FrameComponent::setImage(), CEGUI::Window::setMouseCursor(), CEGUI::FrameWindow::setNESWSizingCursorImage(), CEGUI::FrameWindow::setNSSizingCursorImage(), and CEGUI::FrameWindow::setNWSESizingCursorImage().

uint CEGUI::Imageset::getImageCount ( void ) const

inline

return number of images defined for this Imageset

Returns: uint value equal to the number of Image objects defined for the Imageset

float CEGUI::Imageset::getImageHeight ( const String & name ) const

inline

return the height of the named image.

Parameters

name	String object holding the name of the Image.

Returns: float value equalling the height of the requested Image.

Exceptions

UnknownObjectException thrown if no Image named name is defined for the Imageset

Point CEGUI::Imageset::getImageOffset ( const String & name ) const

inline

return the rendering offsets applied to the named image.

Parameters

name	String object holding the name of the Image.

Returns: Point object that holds the rendering offsets for the requested Image.

Exceptions

UnknownObjectException thrown if no Image named name is defined for the Imageset

float CEGUI::Imageset::getImageOffsetX ( const String & name ) const

inline

return the x rendering offset for the named image.

Parameters

name	String object holding the name of the Image.

Returns: float value equal to the x rendering offset applied when drawing the requested Image.

Exceptions

UnknownObjectException thrown if no Image named name is defined for the Imageset

float CEGUI::Imageset::getImageOffsetY ( const String & name ) const

inline

return the y rendering offset for the named image.

Parameters

name	String object holding the name of the Image.

Returns: float value equal to the y rendering offset applied when drawing the requested Image.

Exceptions

UnknownObjectException thrown if no Image named name is defined for the Imageset

Size CEGUI::Imageset::getImageSize ( const String & name ) const

inline

return a Size object describing the dimensions of the named image.

Parameters

name	String object holding the name of the Image.

Returns: Size object holding the dimensions of the requested Image.

Exceptions

UnknownObjectException thrown if no Image named name is defined for the Imageset

float CEGUI::Imageset::getImageWidth ( const String & name ) const

inline

return the width of the named image.

Parameters

name	String object holding the name of the Image.

Returns: float value equalling the width of the requested Image.

Exceptions

UnknownObjectException thrown if no Image named name is defined for the Imageset

const String& CEGUI::Imageset::getName ( void ) const

inline

return String object holding the name of the Imageset

Returns: String object that holds the name of the Imageset.

Referenced by CEGUI::ImagesetManager::createImageset(), CEGUI::ImagesetManager::destroyImageset(), CEGUI::FontProperties::PixmapImageset::get(), and CEGUI::Image::getImagesetName().

Size CEGUI::Imageset::getNativeResolution ( void ) const

inline

Return the native display size for this Imageset. This is only relevant if the Imageset is being auto-scaled.

Returns: Size object describing the native display size for this Imageset.

Texture* CEGUI::Imageset::getTexture ( void ) const

inline

return Texture object for this Imageset

Returns: Texture object that holds the imagery for this Imageset

Referenced by CEGUI::FreeTypeFont::rasterize().

bool CEGUI::Imageset::isAutoScaled ( void ) const

inline

Return whether this Imageset is auto-scaled.

Returns: true if Imageset is auto-scaled, false if not.

bool CEGUI::Imageset::isImageDefined ( const String & name ) const

inline

return true if an Image with the specified name exists.

Parameters

name	String object holding the name of the Image to look for.

Returns: true if an Image object named name is defined for this Imageset, else false.

Referenced by defineImage().

void CEGUI::Imageset::load	(	const String &	filename,
		const String &	resourceGroup
	)

protected

Initialise the Imageset with information taken from the specified file.

Parameters

filename	String object that holds the name of the Imageset data file that is to be processed.
resourceGroup	Resource group identifier to be passed to the resource manager. NB: This affects the imageset xml file only, the texture loaded may have its own group specified in the XML file.