Crazy Eddies GUI System: CEGUI::Imageset Class Reference

- Main Page
- Namespaces
- Classes
- Files
- Directories
- Related Pages

- Class List
- Alphabetical List
- Class Hierarchy
- Class Members

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