# CEGUI::Imageset Class Reference

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:

[legend]
List of all members.

## 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
const String & | getName (void) const
| return String object holding the name of the Imageset
uint | getImageCount (void) const
| return number of images defined for this Imageset
bool | isImageDefined (const String &name) const
| return true if an Image with the specified name exists.
const Image & | getImage (const String &name) const
| return a copy of the Image object for the named image
void | undefineImage (const String &name)
| remove the definition for the Image with the specified name. If no such Image exists, nothing happens.
void | undefineAllImages (void)
| Removes the definitions for all Image objects currently defined in the Imageset.
Size | getImageSize (const String &name) const
| return a Size object describing the dimensions of the named image.
float | getImageWidth (const String &name) const
| return the width of the named image.
float | getImageHeight (const String &name) const
| return the height of the named image.
Point | getImageOffset (const String &name) const
| return the rendering offsets applied to the named image.
float | getImageOffsetX (const String &name) const
| return the x rendering offset for the named image.
float | getImageOffsetY (const String &name) const
| return the y rendering offset for the named image.
void | defineImage (const String &name, const Point &position, const Size &size, const Point &render_offset)
| Define a new Image for this Imageset.
void | defineImage (const String &name, const Rect &image_rect, const Point &render_offset)
| Define a new Image for this Imageset.
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!
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!
bool | isAutoScaled (void) const
| Return whether this Imageset is auto-scaled.
Size | getNativeResolution (void) const
| Return the native display size for this Imageset. This is only relevant if the Imageset is being auto-scaled.
void | setAutoScalingEnabled (bool setting)
| Enable or disable auto-scaling for this Imageset.
void | setNativeResolution (const Size &size)
| Set the native resolution for this Imageset.
void | notifyScreenResolution (const Size &size)
| Notify the Imageset of the current (usually new) display resolution.
ImageIterator | getIterator (void) const
| Return an Imageset::ImageIterator object that can be used to iterate over the Image objects in the Imageset.
void | writeXMLToStream (OutStream &out_stream) const
| Writes an xml representation of this Imageset to out_stream.

## Protected Member Functions

void | load (const String &filename, const String &resourceGroup)
| Initialise the Imageset with information taken from the specified file.
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!
void | updateImageScalingFactors (void)
| Sets the scaling factor for all Images that are a part of this Imageset.

## 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.

## 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 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::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::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

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

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::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.

Returns:
  Nothing

Exceptions:

  | FileIOException | thrown if something goes wrong while processing the file filename.

void CEGUI::Imageset::notifyScreenResolution | ( | const Size & | size | ) |

Notify the Imageset of the current (usually new) display resolution.

Parameters:

  | size | Size object describing the display resolution

Returns:
  Nothing

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.

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 | ( | OutStream & | out_stream | ) | const

Writes an xml representation of this Imageset to out_stream.

Parameters:

  | out_stream | Stream where xml data should be output.

Returns:
  Nothing.