Crazy Eddies GUI System  0.7.9
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Pages
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:

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.
 
TexturegetTexture (void) const
 return Texture object for this Imageset More...
 
const StringgetName (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 ImagegetImage (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 StringgetDefaultResourceGroup ()
 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.
 
Textured_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
textureTexture 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
nameString object holding the name to be assigned to the created imageset.
filenameString 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.
resourceGroupResource group identifier to be passed to the resource manager, which may specify a group from which the image file is to be loaded.
Exceptions
FileIOExceptionthrown 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
nameString object holding the name that will be assigned to the new Image, which must be unique within the Imageset.
positionPoint object describing the pixel location of the Image on the image file / texture associated with this Imageset.
sizeSize object describing the dimensions of the Image, in pixels.
render_offsetPoint object describing the offsets, in pixels, that are to be applied to the Image when it is drawn.
Returns
Nothing
Exceptions
AlreadyExistsExceptionthrown 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
nameString object holding the name that will be assigned to the new Image, which must be unique within the Imageset.
image_rectRect object describing the area on the image file / texture associated with this Imageset that will be used for the Image.
render_offsetPoint object describing the offsets, in pixels, that are to be applied to the Image when it is drawn.
Returns
Nothing
Exceptions
AlreadyExistsExceptionthrown 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
bufferGeometryBuffer object where the geometry for the area to be drawn will be queued.
source_rectRect object describing the area of the image file / texture that is to be queued for drawing
dest_rectRect describing the area of the screen that will be filled with the imagery from source_rect.
clip_rectRect object describing a 'clipping rectangle' that will be applied when drawing the requested imagery
coloursColourRect object holding the ARGB colours to be applied to the four corners of the rendered imagery.
quad_split_modeOne 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
bufferGeometryBuffer object where the geometry for the area to be drawn will be queued.
source_rectRect object describing the area of the image file / texture that is to be queued for drawing.
dest_rectRect describing the area of the screen that will be filled with the imagery from source_rect.
clip_rectRect object describing a 'clipping rectangle' that will be applied when drawing the requested imagery.
top_left_colourcolour to be applied to the top left corner of the rendered imagery.
top_right_colourcolour to be applied to the top right corner of the rendered imagery.
bottom_left_colourcolour to be applied to the bottom left corner of the rendered imagery.
bottom_right_colourcolour to be applied to the bottom right corner of the rendered imagery.
quad_split_modeOne 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
nameString object holding the name of the Image object to be returned
Returns
constant Image object that has the requested name.
Exceptions
UnknownObjectExceptionthrown 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
nameString object holding the name of the Image.
Returns
float value equalling the height of the requested Image.
Exceptions
UnknownObjectExceptionthrown 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
nameString object holding the name of the Image.
Returns
Point object that holds the rendering offsets for the requested Image.
Exceptions
UnknownObjectExceptionthrown 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
nameString object holding the name of the Image.
Returns
float value equal to the x rendering offset applied when drawing the requested Image.
Exceptions
UnknownObjectExceptionthrown 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
nameString object holding the name of the Image.
Returns
float value equal to the y rendering offset applied when drawing the requested Image.
Exceptions
UnknownObjectExceptionthrown 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
nameString object holding the name of the Image.
Returns
Size object holding the dimensions of the requested Image.
Exceptions
UnknownObjectExceptionthrown 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
nameString object holding the name of the Image.
Returns
float value equalling the width of the requested Image.
Exceptions
UnknownObjectExceptionthrown 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
nameString 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
sizeSize object describing the display resolution
void CEGUI::Imageset::setAutoScalingEnabled ( bool  setting)

Enable or disable auto-scaling for this Imageset.

Parameters
settingtrue 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
resourceGroupString 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
sizeSize 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
textureTexture object to be used by the Imageset. The old texture is NOT disposed of, that is the clients responsibility.
Returns
Nothing
Exceptions
NullObjectExceptionthrown 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
nameString 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_streamStream where xml data should be output.
indentLevelCurrent XML indentation level
Returns
Nothing.