lauchmelder/SFML
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated the API documentation of the graphics module

Browse source 
sf::Image now uses GL_CLAMP_TO_EDGE instead of GL_CLAMP (removes black border when the image is smooth)

git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1511 4e206d99-4929-0410-ac5d-dfc041789085
This commit is contained in:
LaurentGom 2010-04-20 11:10:34 +00:00
parent 7d68f59a5a
commit 073e7864ef
24 changed files with 931 additions and 649 deletions
Download patch file Download diff file Expand all files Collapse all files

148
include/SFML/Graphics/Drawable.hpp
View file

@ -39,141 +39,207 @@ class Renderer;
class RenderTarget;
////////////////////////////////////////////////////////////
/// Enumerate the blending modes for drawable objects
/// \brief Available blending modes for drawable objects
///
////////////////////////////////////////////////////////////
namespace Blend
{
enum Mode
{
Alpha, ///< Pixel = Src * a + Dest * (1 - a)
Alpha, ///< Pixel = Src * Src.a + Dest * (1 - Src.a)
Add, ///< Pixel = Src + Dest
Multiply, ///< Pixel = Src * Dest
None ///< No blending
None ///< Pixel = Src
};
}
////////////////////////////////////////////////////////////
/// Abstract base class for every object that can be drawn
/// into a render window
/// \brief Abstract base class for objects that can be drawn
/// to a render target
///
////////////////////////////////////////////////////////////
class SFML_API Drawable
{
public :
////////////////////////////////////////////////////////////
/// Default constructor
/// \brief Default constructor
///
/// \param position : Position of the object
/// \param scale : Scale factor
/// \param rotation : Orientation, in degrees
/// \param color : Color of the object
/// \param position Position of the object
/// \param scale Scale factor
/// \param rotation Orientation, in degrees
/// \param color Global color of the object
///
////////////////////////////////////////////////////////////
Drawable(const Vector2f& position = Vector2f(0, 0), const Vector2f& scale = Vector2f(1, 1), float rotation = 0.f, const Color& color = Color(255, 255, 255));
////////////////////////////////////////////////////////////
/// Virtual destructor
/// \brief Virtual destructor
///
////////////////////////////////////////////////////////////
virtual ~Drawable();
////////////////////////////////////////////////////////////
/// Set the position of the object (take 2 values)
/// \brief Set the position of the object
///
/// \param x : New X coordinate
/// \param y : New Y coordinate
/// This function completely overwrites the previous position.
/// See Move to apply an offset based on the previous position instead.
/// The default position of a drawable object is (0, 0).
///
/// \param x X coordinate of the new position
/// \param y Y coordinate of the new position
///
/// \see Move, SetX, SetY, GetPosition
///
////////////////////////////////////////////////////////////
void SetPosition(float x, float y);
////////////////////////////////////////////////////////////
/// Set the position of the object (take a 2D vector)
/// \brief Set the position of the object
///
/// \param position : New position
/// This function completely overwrites the previous position.
/// See Move to apply an offset based on the previous position instead.
/// The default position of a drawable object is (0, 0).
///
/// \param position New position
///
/// \see Move, SetX, SetY, GetPosition
///
////////////////////////////////////////////////////////////
void SetPosition(const Vector2f& position);
////////////////////////////////////////////////////////////
/// Set the X position of the object
/// \brief Set the X position of the object
///
/// \param x : New X coordinate
/// \param x New X coordinate
///
/// \see SetY, SetPosition, GetPosition
///
////////////////////////////////////////////////////////////
void SetX(float x);
////////////////////////////////////////////////////////////
/// Set the Y position of the object
/// \brief Set the Y position of the object
///
/// \param y : New Y coordinate
/// \param y New Y coordinate
///
/// \see SetX, SetPosition, GetPosition
///
////////////////////////////////////////////////////////////
void SetY(float y);
////////////////////////////////////////////////////////////
/// Set the scale of the object (take 2 values)
/// \brief Set the scale factors of the object
///
/// \param factorX : New horizontal scale (must be strictly positive)
/// \param factorY : New vertical scale (must be strictly positive)
/// \a factorX and \a factorY must be strictly positive,
/// otherwise they are ignored.
/// This function completely overwrites the previous scale.
/// See Scale to add a factor based on the previous scale instead.
/// The default scale of a drawable object is (1, 1).
///
/// \param factorX New horizontal scale factor
/// \param factorY New vertical scale factor
///
/// \see Scale, SetScaleX, SetScaleY, GetScale
///
////////////////////////////////////////////////////////////
void SetScale(float factorX, float factorY);
////////////////////////////////////////////////////////////
/// Set the scale of the object (take a 2D vector)
/// \brief Set the scale factors of the object
///
/// \param Scale : New scale (both values must be strictly positive)
/// \a scale.x and \a scale.y must be strictly positive,
/// otherwise they are ignored.
/// This function completely overwrites the previous scale.
/// See Scale to add a factor based on the previous scale instead.
/// The default scale of a drawable object is (1, 1).
///
/// \param scale New scale factors
///
/// \see Scale, SetScaleX, SetScaleY, GetScale
///
////////////////////////////////////////////////////////////
void SetScale(const Vector2f& scale);
////////////////////////////////////////////////////////////
/// Set the X scale factor of the object
/// \brief Set the X scale factor of the object
///
/// \param factor : New X scale factor
/// \a factor must be strictly positive, otherwise it is ignored.
///
/// \param factor New horizontal scale factor
///
/// \see SetScaleY, SetScale, GetScale
///
////////////////////////////////////////////////////////////
void SetScaleX(float factor);
////////////////////////////////////////////////////////////
/// Set the Y scale factor of the object
/// \brief Set the Y scale factor of the object
///
/// \param factor : New Y scale factor
/// \a factor must be strictly positive, otherwise it is ignored.
///
/// \param factor New vertical scale factor
///
/// \see SetScaleX, SetScale, GetScale
///
////////////////////////////////////////////////////////////
void SetScaleY(float factor);
////////////////////////////////////////////////////////////
/// Set the local origin of the object, in coordinates relative to the
/// top-left of the object (take 2 values).
/// The default origin is (0, 0)
/// \brief Set the local origin of the object
///
/// \param x : X coordinate of the origin
/// \param y : Y coordinate of the origin
/// The origin of an object defines the center point for
/// all transformations (position, scale, rotation).
/// The coordinates of this point must be relative to the
/// top-left corner of the object, and ignore all
/// transformations (position, scale, rotation).
/// The default origin of a drawable object is (0, 0).
///
/// \param x X coordinate of the new origin
/// \param y Y coordinate of the new origin
///
/// \see GetOrigin
///
////////////////////////////////////////////////////////////
void SetOrigin(float x, float y);
////////////////////////////////////////////////////////////
/// Set the local origin of the object, in coordinates relative to the
/// top-left of the object (take a 2D vector).
/// The default origin is (0, 0)
/// \brief Set the local origin of the object
///
/// \param origin : New origin
/// The origin of an object defines the center point for
/// all transformations (position, scale, rotation).
/// The coordinates of this point must be relative to the
/// top-left corner of the object, and ignore all
/// transformations (position, scale, rotation).
/// The default origin of a drawable object is (0, 0).
///
/// \param origin New origin
///
/// \see GetOrigin
///
////////////////////////////////////////////////////////////
void SetOrigin(const Vector2f& origin);
////////////////////////////////////////////////////////////
/// Set the orientation of the object
/// \brief Set the orientation of the object
///
/// \param angle : Angle of rotation, in degrees
/// This function completely overwrites the previous rotation.
/// See Rotate to add an angle based on the previous rotation instead.
/// The default rotation of a drawable object is 0.
///
/// \param angle New rotation, in degrees
///
/// \see Rotate, GetRotation
///
////////////////////////////////////////////////////////////
void SetRotation(float angle);
////////////////////////////////////////////////////////////
/// Set the color of the object.
/// \brief Set the global color of the object
///
/// This global color affects the entire object, and modulates
/// (multiplies) its original pixels.
///
/// The default color is white
///
/// \param color : New color

2
include/SFML/Graphics/Font.hpp
View file

@ -294,7 +294,7 @@ private :
/// \class sf::Font
///
/// Fonts can be loaded from a file or from memory, from
/// the most common types of fonts. See the LoadFromFile()
/// the most common types of fonts. See the LoadFromFile
/// function for the complete list of supported formats.
///
/// Once it is loaded, a sf::Font instance provides three

21
include/SFML/Graphics/Glyph.hpp
View file

@ -35,14 +35,15 @@
namespace sf
{
////////////////////////////////////////////////////////////
/// Structure describing a glyph (a visual character)
/// \brief Structure describing a glyph
///
////////////////////////////////////////////////////////////
class SFML_API Glyph
{
public :
////////////////////////////////////////////////////////////
/// Default constructor
/// \brief Default constructor
///
////////////////////////////////////////////////////////////
Glyph() : Advance(0) {}
@ -59,3 +60,19 @@ public :
#endif // SFML_GLYPH_HPP
////////////////////////////////////////////////////////////
/// \class sf::Glyph
///
/// A glyph is the visual representation of a character.
///
/// The sf::Glyph structure provides the information needed
/// to handle the glyph:
/// \li its coordinates in the font's image
/// \li its bounding rect
/// \li the offset to apply to get the starting position of the next glyph
///
/// \see sf::Font
///
////////////////////////////////////////////////////////////

351
include/SFML/Graphics/Image.hpp
View file

@ -42,82 +42,115 @@ class RenderImage;
class RenderWindow;
////////////////////////////////////////////////////////////
/// Image is the low-level class for loading and
/// manipulating images
/// \brief Class for loading, manipulating and saving images
///
////////////////////////////////////////////////////////////
class SFML_API Image : public Resource<Image>
{
public :
////////////////////////////////////////////////////////////
/// Default constructor
/// \brief Default constructor
///
/// Creates an empty image.
///
////////////////////////////////////////////////////////////
Image();
////////////////////////////////////////////////////////////
/// Copy constructor
/// \brief Copy constructor
///
/// \param copy : instance to copy
/// \param copy instance to copy
///
////////////////////////////////////////////////////////////
Image(const Image& copy);
////////////////////////////////////////////////////////////
/// Destructor
/// \brief Destructor
///
////////////////////////////////////////////////////////////
~Image();
////////////////////////////////////////////////////////////
/// Load the image from a file
/// \brief Load the image from a file on disk
///
/// \param Filename : Path of the image file to load
/// The supported image formats are bmp, png, tga, jpg, dds
/// and psd. Some format options are not supported, like
/// progressive jpeg.
/// The maximum size for an image depends on the graphics
/// driver and can be retrieve with the GetMaximumSize function.
///
/// \param filename Path of the image file to load
///
/// \return True if loading was successful
///
/// \see LoadFromMemory, LoadFromPixels, SaveToFile
///
////////////////////////////////////////////////////////////
bool LoadFromFile(const std::string& filename);
////////////////////////////////////////////////////////////
/// Load the image from a file in memory
/// \brief Load the image from a file in memory
///
/// \param data : Pointer to the file data in memory
/// \param sizeInBytes : Size of the data to load, in bytes
/// The supported image formats are bmp, png, tga, jpg, dds
/// and psd. Some format options are not supported, like
/// progressive jpeg.
/// The maximum size for an image depends on the graphics
/// driver and can be retrieve with the GetMaximumSize function.
///
/// \param data Pointer to the file data in memory
/// \param size Size of the data to load, in bytes
///
/// \return True if loading was successful
///
/// \see LoadFromFile, LoadFromPixels, SaveToFile
///
////////////////////////////////////////////////////////////
bool LoadFromMemory(const void* data, std::size_t sizeInBytes);
bool LoadFromMemory(const void* data, std::size_t size);
////////////////////////////////////////////////////////////
/// Load the image directly from an array of pixels
/// \brief Load the image from an array of pixels
///
/// \param width : Image width
/// \param height : Image height
/// \param pixels : Pointer to the pixels in memory (assumed format is RGBA)
/// The \a pixels argument must point to an array of 32 bits
/// RGBA pixels. In other words, the pixel array must have
/// this memory layout:
///
/// [r0 g0 b0 a0 r1 g1 b1 a1 r2...]
///
/// \param width Width of the image
/// \param height Height of the image
/// \param pixels Pointer to the pixels in memory
///
/// \return True if loading was successful
///
/// \see LoadFromFile, LoadFromMemory, SaveToFile
///
////////////////////////////////////////////////////////////
bool LoadFromPixels(unsigned int width, unsigned int height, const Uint8* pixels);
////////////////////////////////////////////////////////////
/// Save the content of the image to a file
/// \brief Save the image to a file on disk
///
/// \param filename : Path of the file to save (overwritten if already exist)
/// The format of the image is automatically deduced from
/// the extension. The supported image formats are bmp, png,
/// tga, jpg, dds and psd. The destination file is overwritten
/// if it already exists.
///
/// \param filename Path of the file to save
///
/// \return True if saving was successful
///
/// \see LoadFromFile, LoadFromMemory, LoadFromPixels
///
////////////////////////////////////////////////////////////
bool SaveToFile(const std::string& filename) const;
////////////////////////////////////////////////////////////
/// Create an empty image
/// \brief Create the image and fill it with a unique color
///
/// \param width : Image width
/// \param height : Image height
/// \param color : Image color
/// \param width Width of the image
/// \param height Height of the image
/// \param color Fill color
///
/// \return True if creation was successful
///
@ -125,34 +158,49 @@ public :
bool Create(unsigned int width, unsigned int height, const Color& color = Color(0, 0, 0));
////////////////////////////////////////////////////////////
/// Create transparency mask from a specified colorkey
/// \brief Create a transparency mask from a specified colorkey
///
/// \param color : Color to become transparent
/// \param alpha : Alpha value to assign to transparent pixels
/// This function sets the alpha value of every pixel matching
/// the given color to \a alpha (0 by default), so that they
/// become transparent.
///
/// \param color Color to make transparent
/// \param alpha Alpha value to assign to transparent pixels
///
////////////////////////////////////////////////////////////
void CreateMaskFromColor(const Color& color, Uint8 alpha = 0);
////////////////////////////////////////////////////////////
/// Copy pixels from another image onto this one.
/// This function does a slow pixel copy and should only
/// be used at initialization time
/// \brief Copy pixels from another image onto this one
///
/// \param source : Source image to copy
/// \param destX : X coordinate of the destination position
/// \param destY : Y coordinate of the destination position
/// \param sourceRect : Sub-rectangle of the source image to copy
/// \param applyAlpha : Should the copy take in account the source transparency?
/// This function does a slow pixel copy and should only
/// be used at initialization time. It can be used to prepare
/// a complex static image from several others, but if you
/// need this kind of feature in real-time you'd better use
/// sf::RenderImage.
/// If \a sourceRect is empty, the whole image is copied.
/// If \a applyAlpha is set to true, the transparency of
/// source pixels is applied. If it is false, the pixels are
/// copied unchanged with their alpha value.
///
/// \param source Source image to copy
/// \param destX X coordinate of the destination position
/// \param destY Y coordinate of the destination position
/// \param sourceRect Sub-rectangle of the source image to copy
/// \param applyAlpha Should the copy take in account the source transparency?
///
////////////////////////////////////////////////////////////
void Copy(const Image& source, unsigned int destX, unsigned int destY, const IntRect& sourceRect = IntRect(0, 0, 0, 0), bool applyAlpha = false);
////////////////////////////////////////////////////////////
/// Create the image from the current contents of the
/// given window
/// \brief Copy the contents of a window to the image
///
/// \param window : Window to capture
/// \param sourceRect : Sub-rectangle of the screen to copy (empty by default - entire image)
/// If \a sourceRect is empty, the whole window is copied.
/// Warning: this is a slow operation, if you need to draw
/// dynamic contents to an image then use sf::RenderImage.
///
/// \param window Window to capture
/// \param sourceRect Sub-rectangle of the screen to copy
///
/// \return True if copy was successful
///
@ -160,30 +208,44 @@ public :
bool CopyScreen(RenderWindow& window, const IntRect& sourceRect = IntRect(0, 0, 0, 0));
////////////////////////////////////////////////////////////
/// Change the color of a pixel
/// \brief Change the color of a pixel
///
/// \param x : X coordinate of pixel in the image
/// \param y : Y coordinate of pixel in the image
/// \param color : New color for pixel (x, y)
/// This function doesn't check the validity of the pixel
/// coordinates, using out-of-range values will result in
/// an undefined behaviour.
///
/// \param x X coordinate of pixel to change
/// \param y Y coordinate of pixel to change
/// \param color New color of the pixel
///
/// \see GetPixel
///
////////////////////////////////////////////////////////////
void SetPixel(unsigned int x, unsigned int y, const Color& color);
////////////////////////////////////////////////////////////
/// Get a pixel from the image
/// \brief Get the color of a pixel
///
/// \param x : X coordinate of pixel in the image
/// \param y : Y coordinate of pixel in the image
/// This function doesn't check the validity of the pixel
/// coordinates, using out-of-range values will result in
/// an undefined behaviour.
///
/// \return Color of pixel (x, y)
/// \param x X coordinate of pixel to get
/// \param y Y coordinate of pixel to get
///
/// \return Color of the pixel at coordinates (x, y)
///
////////////////////////////////////////////////////////////
Color GetPixel(unsigned int x, unsigned int y) const;
////////////////////////////////////////////////////////////
/// Get a read-only pointer to the array of pixels (RGBA 8 bits integers components)
/// Array size is GetWidth() x GetHeight() x 4
/// This pointer becomes invalid if you reload or resize the image
/// \brief Get a read-only pointer to the array of pixels
///
/// The returned value points to an array of RGBA pixels made of
/// 8 bits integers components. The size of the array is
/// width * height * 4.
/// Warning: the returned pointer may become invalid if you
/// modify the image, so you should never store it for too long.
///
/// \return Const pointer to the array of pixels
///
@ -191,79 +253,112 @@ public :
const Uint8* GetPixelsPtr() const;
////////////////////////////////////////////////////////////
/// Update the whole image from an array of pixels
/// \brief Update the whole image from an array of pixels
///
/// \param pixels : Array of pixels to write to the image
/// The \a pixels array is assumed to have the same size as
/// the image, and to store RGBA 32 bits pixels.
/// See the other overload of this function to update only
/// a sub-rectangle of the image.
///
/// \param pixels Array of pixels to write to the image
///
////////////////////////////////////////////////////////////
void UpdatePixels(const Uint8* pixels);
////////////////////////////////////////////////////////////
/// Update a sub-rectangle of the image from an array of pixels
/// \brief Update a sub-rectangle of the image from an array of pixels
///
/// The \a pixels array is assumed to store RGBA 32 bits pixels.
/// Warning: for performances reasons, this function doesn't
/// perform any check; thus you're responsible of ensuring that
/// \a rectangle does not exceed the image size, and that
/// \a pixels contains enough elements.
/// See the other overload of this function to update the
/// whole image.
///
/// \param rectangle : Sub-rectangle of the image to update
/// \param pixels : Array of pixels to write to the image
/// \param rectangle Sub-rectangle of the image to update
/// \param pixels Array of pixels to write to the image
///
////////////////////////////////////////////////////////////
void UpdatePixels(const Uint8* pixels, const IntRect& rectangle);
////////////////////////////////////////////////////////////
/// Bind the image for rendering
/// \brief Activate the image for rendering
///
/// This function is mainly used internally by the SFML
/// render system. However it can be useful when
/// using sf::Image together with OpenGL code (it calls
/// glBindTexture).
///
////////////////////////////////////////////////////////////
void Bind() const;
////////////////////////////////////////////////////////////
/// Enable or disable image smooth filter.
/// This parameter is enabled by default
/// \brief Enable or disable the smooth filter
///
/// \param smooth : True to enable smoothing filter, false to disable it
/// When the filter is activated, the image appears smoother
/// so that pixels are less noticeable. However if you want
/// the image to look exactly the same as its source file, you
/// should disable it.
/// The smooth filter is enabled by default.
///
/// \param smooth True to enable smoothing, false to disable it
///
/// \see IsSmooth
///
////////////////////////////////////////////////////////////
void SetSmooth(bool smooth);
////////////////////////////////////////////////////////////
/// Return the width of the image
/// \brief Tell whether the smooth filter is enabled or not
///
/// \return Width in pixels
/// \return True if smoothing is enabled, false if it is disabled
///
////////////////////////////////////////////////////////////
unsigned int GetWidth() const;
////////////////////////////////////////////////////////////
/// Return the height of the image
///
/// \return Height in pixels
///
////////////////////////////////////////////////////////////
unsigned int GetHeight() const;
////////////////////////////////////////////////////////////
/// Tells whether the smooth filtering is enabled or not
///
/// \return True if image smoothing is enabled
/// \see SetSmooth
///
////////////////////////////////////////////////////////////
bool IsSmooth() const;
////////////////////////////////////////////////////////////
/// Convert a subrect expressed in pixels, into float
/// texture coordinates
/// \brief Return the width of the image
///
/// \param rectangle : Sub-rectangle of image to convert
/// \return Width in pixels
///
/// \return Texture coordinates corresponding to the sub-rectangle
/// \see GetHeight
///
////////////////////////////////////////////////////////////
unsigned int GetWidth() const;
////////////////////////////////////////////////////////////
/// \brief Return the height of the image
///
/// \return Height in pixels
///
/// \see GetWidth
///
////////////////////////////////////////////////////////////
unsigned int GetHeight() const;
////////////////////////////////////////////////////////////
/// \brief Convert a rectangle of pixels into texture coordinates
///
/// This function is used by code that needs to map the image
/// to some OpenGL geometry. It converts the source rectangle,
/// expressed in pixels, to float coordinates in the range [0, 1].
///
/// \param rectangle Rectangle to convert
///
/// \return Texture coordinates corresponding to \a rectangle
///
////////////////////////////////////////////////////////////
FloatRect GetTexCoords(const IntRect& rectangle) const;
////////////////////////////////////////////////////////////
/// Get the maximum image size according to hardware support
/// \brief Get the maximum image size allowed
///
/// This maximum size is defined by the graphics driver.
/// You can expect a value of 512 pixels for low-end graphics
/// card, and up to 8192 pixels for newer hardware.
///
/// \return Maximum size allowed for images, in pixels
///
@ -271,21 +366,11 @@ public :
static unsigned int GetMaximumSize();
////////////////////////////////////////////////////////////
/// Get a valid image size according to hardware support
/// \brief Overload of assignment operator
///
/// \param Size : size to convert
/// \param right Instance to assign
///
/// \return Valid nearest size (greater than or equal to specified size)
///
////////////////////////////////////////////////////////////
static unsigned int GetValidSize(unsigned int size);
////////////////////////////////////////////////////////////
/// Assignment operator
///
/// \param other : instance to assign
///
/// \return Reference to the image
/// \return Reference to self
///
////////////////////////////////////////////////////////////
Image& operator =(const Image& other);
@ -296,7 +381,22 @@ private :
friend class RenderImage;
////////////////////////////////////////////////////////////
/// Create the OpenGL texture
/// \brief Get a valid image size according to hardware support
///
/// This function checks whether the graphics driver supports
/// non power of two sizes or not, and adjusts the size
/// accordingly.
/// The returned size is greater than or equal to the original size.
///
/// \param Size size to convert
///
/// \return Valid nearest size (greater than or equal to specified size)
///
////////////////////////////////////////////////////////////
static unsigned int GetValidSize(unsigned int size);
////////////////////////////////////////////////////////////
/// \brief Create the OpenGL texture
///
/// \return True if texture has been successfully created
///
@ -304,33 +404,33 @@ private :
bool CreateTexture();
////////////////////////////////////////////////////////////
/// Make sure the texture in video memory is updated with the
/// array of pixels
/// \brief Make sure that the texture in video memory is
/// synchronized with the pixels cache
///
////////////////////////////////////////////////////////////
void EnsureTextureUpdate() const;
////////////////////////////////////////////////////////////
/// Make sure the array of pixels is updated with the
/// texture in video memory
/// \brief Make sure the pixels cache is synchronized with
/// the texture in video memory
///
////////////////////////////////////////////////////////////
void EnsureArrayUpdate() const;
////////////////////////////////////////////////////////////
/// Make sure that the image is ready to be used
/// \brief Make sure that the image is ready to be used
///
////////////////////////////////////////////////////////////
void Use() const;
////////////////////////////////////////////////////////////
/// Reset the image attributes
/// \brief Reset the image attributes and leave a clean empty image
///
////////////////////////////////////////////////////////////
void Reset();
////////////////////////////////////////////////////////////
/// Destroy the OpenGL texture
/// \brief Destroy the OpenGL texture
///
////////////////////////////////////////////////////////////
void DestroyTexture();
@ -359,3 +459,54 @@ private :
#endif // SFML_IMAGE_HPP
////////////////////////////////////////////////////////////
/// \class sf::Image
///
/// sf::Image is an abstraction to manipulate images
/// as bidimensional arrays of pixels. The class provides
/// functions to load, read, write and save pixels, as well
/// as many other useful functions to...
///
/// sf::Image can handle a unique internal representation of
/// pixels, which is RGBA 32 bits. This means that a pixel
/// must be composed of 8 bits red, green, blue and alpha
/// channels -- just like a sf::Color.
/// All the functions that return an array of pixels follow
/// this rule, and all parameters that you pass to sf::Image
/// functions (such as LoadFromPixels or UpdatePixels) must
/// use this representation as well.
///
/// A sf::Image can be copied, but it is a heavy resource and
/// if possible you should always use [const] references to
/// pass or return them to avoid useless copies.
///
/// Usage example:
/// \code
/// // Load an image file
/// sf::Image background;
/// if (!background.LoadFromFile("background.jpg"))
/// return -1;
///
/// // Create a 20x20 image filled with black color
/// sf::Image image;
/// if (!image.Create(20, 20, sf::Color::Black))
/// return -1;
///
/// // Copy image1 on image2 at position (10, 10)
/// image.Copy(background, 10, 10);
///
/// // Make the top-left pixel transparent
/// sf::Color color = image.GetPixel(0, 0);
/// color.a = 0;
/// image.SetPixel(0, 0, color);
///
/// // Save the image to a file
/// if (!image.SaveToFile("result.png"))
/// return -1;
/// \endcode
///
/// \see sf::Sprite
///
////////////////////////////////////////////////////////////

296
include/SFML/Graphics/Shape.hpp
View file

@ -36,42 +36,48 @@
namespace sf
{
////////////////////////////////////////////////////////////
/// Shape defines a drawable convex shape ; it also defines
/// helper functions to draw simple shapes like
/// lines, rectangles, circles, etc.
/// \brief A convex, colored polygon with an optional outline
///
////////////////////////////////////////////////////////////
class SFML_API Shape : public Drawable
{
public :
////////////////////////////////////////////////////////////
/// Default constructor
/// \brief Default constructor
///
/// Creates an empty shape (no point).
///
////////////////////////////////////////////////////////////
Shape();
////////////////////////////////////////////////////////////
/// Add a point to the shape
/// \brief Add a new point to the shape
///
/// \param x, y : Position of the point
/// \param color : Color of the point
/// \param outlineColor : Outline color of the point
/// The new point is inserted at the end of the shape.
///
/// \param x X position of the point
/// \param y Y position of the point
/// \param color Color of the point
/// \param outlineColor Outline color of the point
///
////////////////////////////////////////////////////////////
void AddPoint(float x, float y, const Color& color = Color(255, 255, 255), const Color& outlineColor = Color(0, 0, 0));
////////////////////////////////////////////////////////////
/// Add a point to the shape
/// \brief Add a new point to the shape
///
/// \param position : Position of the point
/// \param color : Color of the point
/// \param outlineColor : Outline color of the point
/// The new point is inserted at the end of the shape.
///
/// \param position Position of the point
/// \param color Color of the point
/// \param outlineColor Outline color of the point
///
////////////////////////////////////////////////////////////
void AddPoint(const Vector2f& position, const Color& color = Color(255, 255, 255), const Color& outlineColor = Color(0, 0, 0));
////////////////////////////////////////////////////////////
/// Get the number of points composing the shape
/// \brief Get the number of points composing the shape
///
/// \param Total number of points
///
@ -79,175 +85,284 @@ public :
unsigned int GetPointsCount() const;
////////////////////////////////////////////////////////////
/// Enable or disable filling the shape.
/// Fill is enabled by default
/// \brief Enable or disable the shape's filling
///
/// \param enable : True to enable, false to disable
/// This option is enabled by default.
///
/// \param enable True to enable, false to disable
///
/// \see EnableOutline
///
////////////////////////////////////////////////////////////
void EnableFill(bool enable);
////////////////////////////////////////////////////////////
/// Enable or disable drawing the shape outline.
/// Outline is enabled by default
/// \brief Enable or disable the shape's outline
///
/// \param enable : True to enable, false to disable
/// This option is enabled by default.
///
/// \param enable True to enable, false to disable
///
/// \see EnableFill
///
////////////////////////////////////////////////////////////
void EnableOutline(bool enable);
////////////////////////////////////////////////////////////
/// Set the position of a point
/// \brief Change the position of a point
///
/// \param index : Index of the point, in range [0, GetPointsCount() - 1]
/// \param position : New position of the index-th point
/// Warning: this function doesn't check the validity of
/// \a index, if it is out of bounds (ie. in the range
/// [0, GetPointscount() - 1]) the behaviour is undefined.
///
/// \param index Index of the point
/// \param position New position of the point
///
/// \see GetPointPosition, SetPointColor, SetPointOutlineColor
///
////////////////////////////////////////////////////////////
void SetPointPosition(unsigned int index, const Vector2f& position);
////////////////////////////////////////////////////////////
/// Set the position of a point
/// \brief Change the position of a point
///
/// \param index : Index of the point, in range [0, GetPointsCount() - 1]
/// \param x : New X coordinate of the index-th point
/// \param y : New Y coordinate of the index-th point
/// Warning: this function doesn't check the validity of
/// \a index, if it is out of bounds (ie. in the range
/// [0, GetPointscount() - 1]) the behaviour is undefined.
///
/// \param index Index of the point
/// \param x New X coordinate of the point
/// \param y New Y coordinate of the point
///
/// \see GetPointPosition, SetPointColor, SetPointOutlineColor
///
////////////////////////////////////////////////////////////
void SetPointPosition(unsigned int index, float x, float y);
////////////////////////////////////////////////////////////
/// Set the color of a point
/// \brief Change the color of a point
///
/// \param index : Index of the point, in range [0, GetPointsCount() - 1]
/// \param color : New color of the index-th point
/// Warning: this function doesn't check the validity of
/// \a index, if it is out of bounds (ie. in the range
/// [0, GetPointscount() - 1]) the behaviour is undefined.
///
/// \param index Index of the point
/// \param color New color of the point
///
/// \see GetPointColor, SetPointPosition, SetPointOutlineColor
///
////////////////////////////////////////////////////////////
void SetPointColor(unsigned int index, const Color& color);
////////////////////////////////////////////////////////////
/// Set the outline color of a point
/// \brief Change the outline color of a point
///
/// \param index : Index of the point, in range [0, GetPointsCount() - 1]
/// \param outlineColor : New outline color of the index-th point
/// Warning: this function doesn't check the validity of
/// \a index, if it is out of bounds (ie. in the range
/// [0, GetPointscount() - 1]) the behaviour is undefined.
///
/// \param index Index of the point
/// \param color New outline color of the point
///
/// \see GetPointOutlineColor, SetPointPosition, SetPointColor
///
////////////////////////////////////////////////////////////
void SetPointOutlineColor(unsigned int index, const Color& outlineColor);
void SetPointOutlineColor(unsigned int index, const Color& color);
////////////////////////////////////////////////////////////
/// Change the width of the shape outline
/// \brief Change the thickness of the shape outline
///
/// \param width : New width
/// \param width New width of the outline
///
/// \see GetOutlineWidth, EnableOutline
///
////////////////////////////////////////////////////////////
void SetOutlineWidth(float width);
////////////////////////////////////////////////////////////
/// Get the position of a point
/// \brief Get the position of a point
///
/// \param index : Index of the point, in range [0, GetPointsCount() - 1]
/// Warning: this function doesn't check the validity of
/// \a index, if it is out of bounds (ie. in the range
/// [0, GetPointscount() - 1]) the behaviour is undefined.
///
/// \param index Index of the point
///
/// \return Position of the index-th point
///
/// \see SetPointPosition, GetPointColor, GetPointOutlineColor
///
////////////////////////////////////////////////////////////
const Vector2f& GetPointPosition(unsigned int index) const;
////////////////////////////////////////////////////////////
/// Get the color of a point
/// \brief Get the color of a point
///
/// \param Index : index of the point, in range [0, GetPointsCount() - 1]
/// Warning: this function doesn't check the validity of
/// \a index, if it is out of bounds (ie. in the range
/// [0, GetPointscount() - 1]) the behaviour is undefined.
///
/// \param Index index of the point
///
/// \return Color of the index-th point
///
/// \see SetPointColor, GetPointPosition, GetPointOutlineColor
///
////////////////////////////////////////////////////////////
const Color& GetPointColor(unsigned int index) const;
////////////////////////////////////////////////////////////
/// Get the outline color of a point
/// \brief Get the outline color of a point
///
/// \param index : Index of the point, in range [0, GetPointsCount() - 1]
/// Warning: this function doesn't check the validity of
/// \a index, if it is out of bounds (ie. in the range
/// [0, GetPointscount() - 1]) the behaviour is undefined.
///
/// \param index Index of the point
///
/// \return Outline color of the index-th point
///
/// \see SetPointOutlineColor, GetPointPosition, GetPointColor
///
////////////////////////////////////////////////////////////
const Color& GetPointOutlineColor(unsigned int index) const;
////////////////////////////////////////////////////////////
/// Get the width of the shape outline
/// \brief Get the thickness of the shape outline
///
/// \return Current outline width
///
/// \see SetOutlineWidth
///
////////////////////////////////////////////////////////////
float GetOutlineWidth() const;
////////////////////////////////////////////////////////////
/// Create a shape made of a single line (use floats)
/// \brief Create a new line
///
/// \param p1x, p1y : Position of the first point
/// \param p2x, p2y : Position second point
/// \param thickness : Line thickness
/// \param color : Color used to draw the line
/// \param outline : Outline width
/// \param outlineColor : Color used to draw the outline
/// This is a static function that returns a new object,
/// don't try to call it on an existing object to modify it.
/// \begincode
/// sf::Shape line = sf::Shape::Line(0, 0, 10, 20, 2.5f, sf::Color::Green);
/// \endcode
///
/// \param x0 X coordinate of the start point
/// \param y0 Y coordinate of the start point
/// \param x1 X coordinate of the end point
/// \param y1 Y coordinate of the end point
/// \param thickness Thickness of the line
/// \param color Color of the shape's points
/// \param outline Outline width
/// \param outlineColor Outline color of the shape's points
///
/// \see Rectangle, Circle
///
////////////////////////////////////////////////////////////
static Shape Line(float p1x, float p1y, float p2x, float p2y, float thickness, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
////////////////////////////////////////////////////////////
/// Create a shape made of a single line (use vectors)
/// \brief Create a new line
///
/// \param p1 : Position of the first point
/// \param p2 : Position second point
/// \param thickness : Line thickness
/// \param color : Color used to draw the line
/// \param outline : Outline width
/// \param outlineColor : Color used to draw the outline
/// This is a static function that returns a new object,
/// don't try to call it on an existing object to modify it.
/// \begincode
/// sf::Vector2f start(0, 0);
/// sf::Vector2f end(10, 20);
/// sf::Shape line = sf::Shape::Line(start, end, 2.5f, sf::Color::Green);
/// \endcode
///
/// \param start Start point
/// \param end End point
/// \param thickness Thickness of the line
/// \param color Color of the shape's points
/// \param outline Outline width
/// \param outlineColor Outline color of the shape's points
///
/// \see Rectangle, Circle
///
////////////////////////////////////////////////////////////
static Shape Line(const Vector2f& p1, const Vector2f& p2, float thickness, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
static Shape Line(const Vector2f& start, const Vector2f& end, float thickness, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
////////////////////////////////////////////////////////////
/// Create a shape made of a single rectangle
/// \brief Create a new rectangular shape
///
/// \param left, top : Position of the top-left corner
/// \param width, height : Size of the rectangle
/// \param color : Color used to fill the rectangle
/// \param outline : Outline width
/// \param outlineColor : Color used to draw the outline
/// This is a static function that returns a new object,
/// don't try to call it on an existing object to modify it.
/// \begincode
/// sf::Shape rect = sf::Shape::Rectangle(10, 20, 50, 100, sf::Color::Red);
/// \endcode
///
/// \param left Left coordinate of the rectangle
/// \param top Top coordinate of the rectangle
/// \param width Width of the rectangle
/// \param height Height of the rectangle
/// \param color Color of the shape's points
/// \param outline Outline width
/// \param outlineColor Outline color of the shape's points
///
/// \see Line, Circle
///
////////////////////////////////////////////////////////////
static Shape Rectangle(float left, float top, float width, float height, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
////////////////////////////////////////////////////////////
/// Create a shape made of a single rectangle
/// \brief Create a new rectangular shape
///
/// \param rectangle : Rectangle
/// \param color : Color used to fill the rectangle
/// \param outline : Outline width
/// \param outlineColor : Color used to draw the outline
/// This is a static function that returns a new object,
/// don't try to call it on an existing object to modify it.
/// \begincode
/// sf::FloatRect source(10, 20, 50, 100);
/// sf::Shape rect = sf::Shape::Rectangle(source, sf::Color::Red);
/// \endcode
///
/// \param rectangle Rectangle defining the shape
/// \param color Color of the shape's points
/// \param outline Outline width
/// \param outlineColor Outline color of the shape's points
///
/// \see Line, Circle
///
////////////////////////////////////////////////////////////
static Shape Rectangle(const FloatRect& rectangle, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
////////////////////////////////////////////////////////////
/// Create a shape made of a single circle (use floats)
/// \brief Create a new circular shape
///
/// \param x, y : Position of the center
/// \param radius : Radius
/// \param color : Color used to fill the circle
/// \param outline : Outline width
/// \param outlineColor : Color used to draw the outline
/// This is a static function that returns a new object,
/// don't try to call it on an existing object to modify it.
/// \begincode
/// sf::Shape circle = sf::Shape::Circle(0, 0, 7, sf::Color::Blue);
/// \endcode
///
/// \param x X coordinate of the center
/// \param y Y coordinate of the center
/// \param radius Radius of the circle
/// \param color Color of the shape's points
/// \param outline Outline width
/// \param outlineColor Outline color of the shape's points
///
/// \see Line, Rectangle
///
////////////////////////////////////////////////////////////
static Shape Circle(float x, float y, float radius, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
////////////////////////////////////////////////////////////
/// Create a shape made of a single circle (use vectors)
/// \brief Create a new circular shape
///
/// \param center : Position of the center
/// \param radius : Radius
/// \param color : Color used to fill the circle
/// \param outline : Outline width
/// \param outlineColor : Color used to draw the outline
/// This is a static function that returns a new object,
/// don't try to call it on an existing object to modify it.
/// \begincode
/// sf::Vector2f center(0, 0);
/// sf::Shape circle = sf::Shape::Circle(center, 7, sf::Color::Blue);
/// \endcode
///
/// \param center Center of the circle
/// \param radius Radius of the circle
/// \param color Color of the shape's points
/// \param outline Outline width
/// \param outlineColor Outline color of the shape's points
///
/// \see Line, Rectangle
///
////////////////////////////////////////////////////////////
static Shape Circle(const Vector2f& center, float radius, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
@ -255,7 +370,10 @@ public :
protected :
////////////////////////////////////////////////////////////
/// /see Drawable::Render
/// \brief Draw the object to a render target
///
/// \param target Render target
/// \param renderer Renderer providing low-level rendering commands
///
////////////////////////////////////////////////////////////
virtual void Render(RenderTarget& target, Renderer& renderer) const;
@ -263,17 +381,20 @@ protected :
private :
////////////////////////////////////////////////////////////
/// Compile the shape : compute its center and its outline
/// \brief Compile the shape
///
/// This function precomputes all the internal parameters
/// needed to properly render the shape (center, outline points).
///
////////////////////////////////////////////////////////////
void Compile();
////////////////////////////////////////////////////////////
/// Compute the normal of a given 2D segment
/// \brief Compute the normal of a given 2D segment
///
/// \param p1 : First point of the segment
/// \param p2 : Second point of the segment
/// \param normal : Calculated normal
/// \param p1 First point of the segment
/// \param p2 Second point of the segment
/// \param normal Variable to fill with the calculated normal
///
/// \return False if the normal couldn't be calculated (segment is null)
///
@ -281,7 +402,8 @@ private :
static bool ComputeNormal(const Vector2f& p1, const Vector2f& p2, Vector2f& normal);
////////////////////////////////////////////////////////////
/// Defines a simple 2D point
/// \brief Define a simple 2D point with position, normal and colors
///
////////////////////////////////////////////////////////////
struct Point
{

138
include/SFML/Graphics/Sprite.hpp
View file

@ -38,116 +38,177 @@ namespace sf
class Image;
////////////////////////////////////////////////////////////
/// Sprite defines a sprite : texture, transformations,
/// color, and draw on screen
/// \brief Drawable representation of an image, with its
/// own transformations, color, blend mode, etc.
///
////////////////////////////////////////////////////////////
class SFML_API Sprite : public Drawable
{
public :
////////////////////////////////////////////////////////////
/// Default constructor
/// \brief Default constructor
///
/// Creates an empty sprite with no source image.
///
////////////////////////////////////////////////////////////
Sprite();
////////////////////////////////////////////////////////////
/// Construct the sprite from a source image
/// \brief Construct the sprite from a source image
///
/// \param image : Image of the sprite
/// \param position : Position of the sprite
/// \param scale : Scale factor
/// \param rotation : Orientation, in degrees
/// \param color : Color of the sprite
/// \param image Source image, that the sprite will display
/// \param position Position of the sprite in the scene
/// \param scale Scale factor of the sprite
/// \param rotation Rotation angle, in degrees
/// \param color Global color of the sprite
///
/// \see SetImage
///
////////////////////////////////////////////////////////////
explicit Sprite(const Image& image, const Vector2f& position = Vector2f(0, 0), const Vector2f& scale = Vector2f(1, 1), float rotation = 0.f, const Color& color = Color(255, 255, 255, 255));
////////////////////////////////////////////////////////////
/// Change the image of the sprite
/// \brief Change the source image of the sprite
///
/// \param image : New image
/// \param adjustToNewSize : If true, the SubRect of the sprite will be adjusted to the size of the new image
/// The \a image argument refers to an image that must
/// exist as long as the sprite uses it. Indeed, the sprite
/// doesn't store its own copy of the image, but rather keeps
/// a pointer to the one that you passed to this function.
/// If the source image is destroyed and the sprite tries to
/// use it, it may appear as a white rectangle.
/// If \a adjustToNewSize is true, the SubRect property of
/// the sprite is adjusted to the size of the new image. If
/// it is false, the SubRect is unchanged.
///
/// \param image New image
/// \param adjustToNewSize Should the sub-rect be adjusted to the size of the new image?
///
/// \see GetImage, SetSubRect
///
////////////////////////////////////////////////////////////
void SetImage(const Image& image, bool adjustToNewSize = false);
////////////////////////////////////////////////////////////
/// Set the sub-rectangle of the sprite inside the source image.
/// By default, the subrect covers the entire source image
/// \brief Set the part of the image that the sprite will display
///
/// \param rectangle : New sub-rectangle
/// The sub-rectangle is useful when you don't want to display
/// the whole image, but rather a part of it.
/// By default, the sub-rectangle covers the entire image.
///
/// \param rectangle Rectangle defining the region of the image to display
///
/// \see GetSubRect, SetImage
///
////////////////////////////////////////////////////////////
void SetSubRect(const IntRect& rectangle);
////////////////////////////////////////////////////////////
/// Resize the sprite (by changing its scale factors) (take 2 values).
/// The default size is defined by the subrect
/// \brief Change the size of the sprite
///
/// \param width : New width (must be strictly positive)
/// \param height : New height (must be strictly positive)
/// This function is just a shortcut that calls SetScale
/// with the proper values, calculated from the size of
/// the current subrect.
/// If \a width or \a height is not strictly positive,
/// this functions does nothing.
///
/// \param width New width of the sprite
/// \param height New height of the sprite
///
/// \see GetSize
///
////////////////////////////////////////////////////////////
void Resize(float width, float height);
////////////////////////////////////////////////////////////
/// Resize the sprite (by changing its scale factors) (take a 2D vector).
/// The default size is defined by the subrect
/// \brief Change the size of the sprite
///
/// \param size : New size (both coordinates must be strictly positive)
/// This function is just a shortcut that calls SetScale
/// with the proper values, calculated from the size of
/// the current subrect.
/// If \a size.x or \a size.y is not strictly positive,
/// this functions does nothing.
///
/// \param size New size of the sprite
///
/// \see GetSize
///
////////////////////////////////////////////////////////////
void Resize(const Vector2f& size);
////////////////////////////////////////////////////////////
/// Flip the sprite horizontally
/// \brief Flip the sprite horizontally
///
/// \param flipped : True to flip the sprite
/// \param flipped True to flip the sprite
///
/// \see FlipY
///
////////////////////////////////////////////////////////////
void FlipX(bool flipped);
////////////////////////////////////////////////////////////
/// Flip the sprite vertically
/// \brief Flip the sprite vertically
///
/// \param flipped : True to flip the sprite
/// \param flipped True to flip the sprite
///
/// \see FlipX
///
////////////////////////////////////////////////////////////
void FlipY(bool flipped);
////////////////////////////////////////////////////////////
/// Get the source image of the sprite
/// \brief Get the source image of the sprite
///
/// \return Pointer to the image (can be NULL)
/// If the sprite has no source image, or if the image
/// doesn't exist anymore, a NULL pointer is returned.
/// The returned pointer is const, which means that you can't
/// modify the image when you retrieve it with this function.
///
/// \return Pointer to the sprite's image
///
/// \see SetImage
///
////////////////////////////////////////////////////////////
const Image* GetImage() const;
////////////////////////////////////////////////////////////
/// Get the sub-rectangle of the sprite inside the source image
/// \brief Get the region of the image displayed by the sprite
///
/// \return Sub-rectangle
/// \return Rectangle defining the region of the image
///
/// \see SetSubRect
///
////////////////////////////////////////////////////////////
const IntRect& GetSubRect() const;
////////////////////////////////////////////////////////////
/// Get the sprite size
/// \brief Get the global size of the sprite
///
/// This function is a shortcut that multiplies the
/// size of the subrect by the scale factors.
///
/// \return Size of the sprite
///
/// \see Resize
///
////////////////////////////////////////////////////////////
Vector2f GetSize() const;
////////////////////////////////////////////////////////////
/// Get the color of a given pixel in the sprite
/// (point is in local coordinates)
/// \brief Get the color of a given pixel in the sprite
///
/// \param x : X coordinate of the pixel to get
/// \param y : Y coordinate of the pixel to get
/// This function returns the source image pixel, multiplied
/// by the global color of the sprite.
/// The input point must be in local coordinates. If you have
/// a global point, you can use the TransformToLocal function
/// to make it local.
/// This function doesn't perform any check, you must ensure that
/// the \a x and \a y coordinates are not out of bounds.
///
/// \return Color of pixel (x, y)
/// \param x X coordinate of the pixel to get
/// \param y Y coordinate of the pixel to get
///
/// \return Color of the pixel
///
////////////////////////////////////////////////////////////
Color GetPixel(unsigned int x, unsigned int y) const;
@ -155,7 +216,10 @@ public :
protected :
////////////////////////////////////////////////////////////
/// /see Drawable::Render
/// \brief Draw the object to a render target
///
/// \param target Render target
/// \param renderer Renderer providing low-level rendering commands
///
////////////////////////////////////////////////////////////
virtual void Render(RenderTarget& target, Renderer& renderer) const;

133
include/SFML/Graphics/Text.hpp
View file

@ -39,121 +39,179 @@
namespace sf
{
////////////////////////////////////////////////////////////
/// Text defines a graphical 2D text, that can be drawn on screen
/// \brief Graphical text that can be drawn to a render target
///
////////////////////////////////////////////////////////////
class SFML_API Text : public Drawable
{
public :
////////////////////////////////////////////////////////////
/// Enumerate the string drawing styles
/// \brief Enumeration of the string drawing styles
///
////////////////////////////////////////////////////////////
enum Style
{
Regular = 0, ///< Regular characters, no style
Bold = 1 << 0, ///< Characters are bold
Italic = 1 << 1, ///< Characters are in italic
Underlined = 1 << 2 ///< Characters are underlined
Bold = 1 << 0, ///< Bold characters
Italic = 1 << 1, ///< Italic characters
Underlined = 1 << 2 ///< Underlined characters
};
////////////////////////////////////////////////////////////
/// Default constructor
/// \brief Default constructor
///
/// Creates an empty text.
///
////////////////////////////////////////////////////////////
Text();
////////////////////////////////////////////////////////////
/// Construct the string from any kind of text
/// \brief Construct the string from a string, font and size
///
/// \param string : Text assigned to the string
/// \param font : Font used to draw the string
/// \param characterSize : Base size of characters, in pixels
/// \param string Text assigned to the string
/// \param font Font used to draw the string
/// \param characterSize Base size of characters, in pixels
///
////////////////////////////////////////////////////////////
explicit Text(const String& string, const Font& font = Font::GetDefaultFont(), unsigned int characterSize = 30);
////////////////////////////////////////////////////////////
/// Set the text (from any kind of string)
/// \brief Set the text's string
///
/// \param string : New text
/// The \a string argument is a sf::String, which can
/// automatically be constructed from standard string types.
/// So, the following calls are all valid:
/// \begincode
/// text.SetString("hello");
/// text.SetString(L"hello");
/// text.SetString(std::string("hello"));
/// text.SetString(std::wstring(L"hello"));
/// \endcode
/// A text's string is empty by default.
///
/// \param string New string
///
/// \see GetString
///
////////////////////////////////////////////////////////////
void SetString(const String& string);
////////////////////////////////////////////////////////////
/// Set the font of the string
/// \brief Set the text's font
///
/// \param font : Font to use
/// Texts have a valid font by default, which the built-in
/// Font::GetDefaultFont().
///
/// \param font New font
///
/// \see GetFont
///
////////////////////////////////////////////////////////////
void SetFont(const Font& font);
////////////////////////////////////////////////////////////
/// Set the base size for the characters.
/// The default size is 30
/// \brief Set the character size
///
/// \param size : New size, in pixels
/// The default size is 30.
///
/// \param size New character size, in pixels
///
/// \see GetCharacterSize
///
////////////////////////////////////////////////////////////
void SetCharacterSize(unsigned int size);
////////////////////////////////////////////////////////////
/// Set the style of the text
/// The default style is Regular
/// \brief Set the text's style
///
/// \param style : New text style (combination of Style enum values)
/// You can pass a combination of one or more styles, for
/// example sf::Text::Bold | sf::Text::Italic.
/// The default style is sf::Text::Regular.
///
/// \param style New style
///
/// \see GetStyle
///
////////////////////////////////////////////////////////////
void SetStyle(unsigned long style);
////////////////////////////////////////////////////////////
/// Get the text (the returned text can be converted implicitely to any kind of string)
/// \brief Get the text's string
///
/// \return String's text
/// The returned string is a sf::String, which can automatically
/// be converted to standard string types. So, the following
/// lines of code are all valid:
/// \begincode
/// sf::String s1 = text.GetString();
/// std::string s2 = text.GetString();
/// std::wstring s3 = text.GetString();
/// \endcode
///
/// \return Text's string
///
/// \see GetString
///
////////////////////////////////////////////////////////////
const String& GetString() const;
////////////////////////////////////////////////////////////
/// Get the font used by the string
/// \brief Get the text's font
///
/// \return Font used
/// The returned reference is const, which means that you
/// cannot modify the font when you get it from this function.
///
/// \return Text's font
///
/// \see SetFont
///
////////////////////////////////////////////////////////////
const Font& GetFont() const;
////////////////////////////////////////////////////////////
/// Get the base size of characters
/// \brief Get the character size
///
/// \return Size of the characters, in pixels
///
/// \see SetCharacterSize
///
////////////////////////////////////////////////////////////
unsigned int GetCharacterSize() const;
////////////////////////////////////////////////////////////
/// Get the style of the text
/// \brief Get the text's style
///
/// \return Current string style (combination of Style enum values)
/// \return Text's style
///
/// \see SetStyle
///
////////////////////////////////////////////////////////////
unsigned long GetStyle() const;
////////////////////////////////////////////////////////////
/// Return the visual position of the Index-th character of the string,
/// in coordinates relative to the string
/// (note : translation, center, rotation and scale are not applied)
/// \brief Return the position of the \a index-th character
///
/// \param index : Index of the character
/// This function computes the visual position of a character
/// from its index in the string. The returned position is
/// in local coordinates (translation, rotation, scale and
/// origin are not applied). You can easily get the corresponding
/// global position with the TransformToGlobal function.
/// If \a index is out of range, the position of the end of
/// the string is returned.
///
/// \return Position of the index-th character (end of string if Index is out of range)
/// \param index Index of the character
///
/// \return Position of the character
///
////////////////////////////////////////////////////////////
Vector2f GetCharacterPos(std::size_t index) const;
////////////////////////////////////////////////////////////
/// Get the string rectangle on screen
/// \brief Get the bounding rectangle of the text
///
/// \return Rectangle contaning the string in screen coordinates
/// The returned rectangle is in global coordinates.
///
/// \return Bounding rectangle of the text
///
////////////////////////////////////////////////////////////
FloatRect GetRect() const;
@ -161,7 +219,10 @@ public :
protected :
////////////////////////////////////////////////////////////
/// /see Drawable::Render
/// \brief Draw the object to a render target
///
/// \param target Render target
/// \param renderer Renderer providing low-level rendering commands
///
////////////////////////////////////////////////////////////
virtual void Render(RenderTarget& target, Renderer& renderer) const;
@ -169,7 +230,7 @@ protected :
private :
////////////////////////////////////////////////////////////
/// Recompute the bounding rectangle of the text
/// \brief Recompute the bounding rectangle
///
////////////////////////////////////////////////////////////
void UpdateRect() const;