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 (const String &name, Texture &texture)
	Construct a new Imageset object. Object will initially have no Images defined. More...

	Imageset (const String &name, const String &filename, const String &resourceGroup)
	Construct a new Imageset using the specified image file and imageset name. The created imageset will, by default, have a single Image defined named "full_image" which represents the entire area of the loaded image file. More...

	~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 (GeometryBuffer &buffer, const Rect &source_rect, const Rect &dest_rect, 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 (GeometryBuffer &buffer, const Rect &source_rect, const Rect &dest_rect, 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	notifyDisplaySizeChanged (const Size &size)
	Notify the Imageset that the display size may have changed. 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	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 String	d_defaultResourceGroup
	Default resource group specifically for Imagesets.

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.

Constructor & Destructor Documentation

CEGUI::Imageset::Imageset	(	const String &	name,
		Texture &	texture
	)

Construct a new Imageset object. Object will initially have no Images defined.

Parameters

texture Texture object that holds the imagery for the Imageset being created.

CEGUI::Imageset::Imageset	(	const String &	name,
		const String &	filename,
		const String &	resourceGroup
	)

Construct a new Imageset using the specified image file and imageset name. The created imageset will, by default, have a single Image defined named "full_image" which represents the entire area of the loaded image file.

Note: Under certain renderers it may be required that the source image dimensions be some power of 2, if this condition is not met then stretching and other undesired side-effects may be experienced. To be safe from such effects it is generally recommended that all images that you load have dimensions that are some power of 2.

Parameters

name	String object holding the name to be assigned to the created imageset.
filename	String object holding the filename of the image that is to be loaded. The image should be of some format that is supported by the Renderer that is in use.
resourceGroup	Resource group identifier to be passed to the resource manager, which may specify a group from which the image file is to be loaded.

Exceptions

FileIOException thrown if something goes wrong while loading the image.

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

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

void CEGUI::Imageset::draw	(	GeometryBuffer &	buffer,
		const Rect &	source_rect,
		const Rect &	dest_rect,
		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

buffer	GeometryBuffer object where the geometry for the area to be drawn will be queued.
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.
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 the quad geometry for the image is to be split into triangles.

Returns: Nothing

void CEGUI::Imageset::draw	(	GeometryBuffer &	buffer,
		const Rect &	source_rect,
		const Rect &	dest_rect,
		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

buffer	GeometryBuffer object where the geometry for the area to be drawn will be queued.
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.
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 the quad geometry for the image is to be split into triangles.

Returns: Nothing

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

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

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.

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

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.

void CEGUI::Imageset::notifyDisplaySizeChanged ( const Size & size )

Notify the Imageset that the display size may have changed.

Parameters

size	Size object describing the display resolution

void CEGUI::Imageset::setAutoScalingEnabled ( bool setting )

Enable or disable auto-scaling for this Imageset.

Parameters

setting true to enable auto-scaling, false to disable auto-scaling.

Returns: Nothing.

static void CEGUI::Imageset::setDefaultResourceGroup ( const String & resourceGroup )

inlinestatic

Sets the default resource group to be used when loading imageset data.

Parameters

resourceGroup String describing the default resource group identifier to be used.

Returns: Nothing.

void CEGUI::Imageset::setNativeResolution ( const Size & size )

Set the native resolution for this Imageset.

Parameters

size	Size object describing the new native screen resolution for this Imageset.

Returns: Nothing

void CEGUI::Imageset::setTexture ( Texture * texture )

protected

set the Texture object to be used by this Imageset. Changing textures on an Imageset that is in use is not a good idea!

Parameters

texture Texture object to be used by the Imageset. The old texture is NOT disposed of, that is the clients responsibility.

Returns: Nothing

Exceptions

NullObjectException thrown if texture is NULL

void CEGUI::Imageset::undefineAllImages ( void )

Removes the definitions for all Image objects currently defined in the Imageset.

Returns: Nothing

void CEGUI::Imageset::undefineImage ( const String & name )

remove the definition for the Image with the specified name. If no such Image exists, nothing happens.

Parameters

name	String object holding the name of the Image object to be removed from the Imageset,

Returns: Nothing.

void CEGUI::Imageset::updateImageScalingFactors ( void )

protected

Sets the scaling factor for all Images that are a part of this Imageset.

Returns: Nothing.

void CEGUI::Imageset::writeXMLToStream ( XMLSerializer & xml_stream ) const

Writes an xml representation of this Imageset to out_stream.

Parameters

out_stream	Stream where xml data should be output.
indentLevel	Current XML indentation level

Returns: Nothing.

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation