Crazy Eddies GUI System: CEGUI::Imageset Class Reference

Crazy Eddies GUI System 0.7.6

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

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes
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 (const String &name, Texture &texture)
| Construct a new Imageset object. Object will initially have no Images defined.
| 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.
| ~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 (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!
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!
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 | notifyDisplaySizeChanged (const Size &size)
| Notify the Imageset that the display size may have changed.
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.
## Static Public Member Functions
static void | setDefaultResourceGroup (const String &resourceGroup)
| Sets the default resource group to be used when loading imageset data.
static const String & | getDefaultResourceGroup ()
| Returns the default resource group currently set for Imagesets.
## 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!
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 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 | ( |  | ) | `[inline, static]`

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 | ) | `[inline, static]`

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.