git.sesse.net Git - casparcg/blob - dependencies64/sfml/include/SFML/Graphics/Sprite.hpp

   1 ////////////////////////////////////////////////////////////
   2 //
   3 // SFML - Simple and Fast Multimedia Library
   4 // Copyright (C) 2007-2014 Laurent Gomila (laurent.gom@gmail.com)
   5 //
   6 // This software is provided 'as-is', without any express or implied warranty.
   7 // In no event will the authors be held liable for any damages arising from the use of this software.
   8 //
   9 // Permission is granted to anyone to use this software for any purpose,
  10 // including commercial applications, and to alter it and redistribute it freely,
  11 // subject to the following restrictions:
  12 //
  13 // 1. The origin of this software must not be misrepresented;
  14 //    you must not claim that you wrote the original software.
  15 //    If you use this software in a product, an acknowledgment
  16 //    in the product documentation would be appreciated but is not required.
  17 //
  18 // 2. Altered source versions must be plainly marked as such,
  19 //    and must not be misrepresented as being the original software.
  20 //
  21 // 3. This notice may not be removed or altered from any source distribution.
  22 //
  23 ////////////////////////////////////////////////////////////
  24
  25 #ifndef SFML_SPRITE_HPP
  26 #define SFML_SPRITE_HPP
  27
  28 ////////////////////////////////////////////////////////////
  29 // Headers
  30 ////////////////////////////////////////////////////////////
  31 #include <SFML/Graphics/Export.hpp>
  32 #include <SFML/Graphics/Drawable.hpp>
  33 #include <SFML/Graphics/Transformable.hpp>
  34 #include <SFML/Graphics/Vertex.hpp>
  35 #include <SFML/Graphics/Rect.hpp>
  36
  37
  38 namespace sf
  39 {
  40 class Texture;
  41
  42 ////////////////////////////////////////////////////////////
  43 /// \brief Drawable representation of a texture, with its
  44 ///        own transformations, color, etc.
  45 ///
  46 ////////////////////////////////////////////////////////////
  47 class SFML_GRAPHICS_API Sprite : public Drawable, public Transformable
  48 {
  49 public:
  50
  51     ////////////////////////////////////////////////////////////
  52     /// \brief Default constructor
  53     ///
  54     /// Creates an empty sprite with no source texture.
  55     ///
  56     ////////////////////////////////////////////////////////////
  57     Sprite();
  58
  59     ////////////////////////////////////////////////////////////
  60     /// \brief Construct the sprite from a source texture
  61     ///
  62     /// \param texture Source texture
  63     ///
  64     /// \see setTexture
  65     ///
  66     ////////////////////////////////////////////////////////////
  67     explicit Sprite(const Texture& texture);
  68
  69     ////////////////////////////////////////////////////////////
  70     /// \brief Construct the sprite from a sub-rectangle of a source texture
  71     ///
  72     /// \param texture   Source texture
  73     /// \param rectangle Sub-rectangle of the texture to assign to the sprite
  74     ///
  75     /// \see setTexture, setTextureRect
  76     ///
  77     ////////////////////////////////////////////////////////////
  78     Sprite(const Texture& texture, const IntRect& rectangle);
  79
  80     ////////////////////////////////////////////////////////////
  81     /// \brief Change the source texture of the sprite
  82     ///
  83     /// The \a texture argument refers to a texture that must
  84     /// exist as long as the sprite uses it. Indeed, the sprite
  85     /// doesn't store its own copy of the texture, but rather keeps
  86     /// a pointer to the one that you passed to this function.
  87     /// If the source texture is destroyed and the sprite tries to
  88     /// use it, the behavior is undefined.
  89     /// If \a resetRect is true, the TextureRect property of
  90     /// the sprite is automatically adjusted to the size of the new
  91     /// texture. If it is false, the texture rect is left unchanged.
  92     ///
  93     /// \param texture   New texture
  94     /// \param resetRect Should the texture rect be reset to the size of the new texture?
  95     ///
  96     /// \see getTexture, setTextureRect
  97     ///
  98     ////////////////////////////////////////////////////////////
  99     void setTexture(const Texture& texture, bool resetRect = false);
 100
 101     ////////////////////////////////////////////////////////////
 102     /// \brief Set the sub-rectangle of the texture that the sprite will display
 103     ///
 104     /// The texture rect is useful when you don't want to display
 105     /// the whole texture, but rather a part of it.
 106     /// By default, the texture rect covers the entire texture.
 107     ///
 108     /// \param rectangle Rectangle defining the region of the texture to display
 109     ///
 110     /// \see getTextureRect, setTexture
 111     ///
 112     ////////////////////////////////////////////////////////////
 113     void setTextureRect(const IntRect& rectangle);
 114
 115     ////////////////////////////////////////////////////////////
 116     /// \brief Set the global color of the sprite
 117     ///
 118     /// This color is modulated (multiplied) with the sprite's
 119     /// texture. It can be used to colorize the sprite, or change
 120     /// its global opacity.
 121     /// By default, the sprite's color is opaque white.
 122     ///
 123     /// \param color New color of the sprite
 124     ///
 125     /// \see getColor
 126     ///
 127     ////////////////////////////////////////////////////////////
 128     void setColor(const Color& color);
 129
 130     ////////////////////////////////////////////////////////////
 131     /// \brief Get the source texture of the sprite
 132     ///
 133     /// If the sprite has no source texture, a NULL pointer is returned.
 134     /// The returned pointer is const, which means that you can't
 135     /// modify the texture when you retrieve it with this function.
 136     ///
 137     /// \return Pointer to the sprite's texture
 138     ///
 139     /// \see setTexture
 140     ///
 141     ////////////////////////////////////////////////////////////
 142     const Texture* getTexture() const;
 143
 144     ////////////////////////////////////////////////////////////
 145     /// \brief Get the sub-rectangle of the texture displayed by the sprite
 146     ///
 147     /// \return Texture rectangle of the sprite
 148     ///
 149     /// \see setTextureRect
 150     ///
 151     ////////////////////////////////////////////////////////////
 152     const IntRect& getTextureRect() const;
 153
 154     ////////////////////////////////////////////////////////////
 155     /// \brief Get the global color of the sprite
 156     ///
 157     /// \return Global color of the sprite
 158     ///
 159     /// \see setColor
 160     ///
 161     ////////////////////////////////////////////////////////////
 162     const Color& getColor() const;
 163
 164     ////////////////////////////////////////////////////////////
 165     /// \brief Get the local bounding rectangle of the entity
 166     ///
 167     /// The returned rectangle is in local coordinates, which means
 168     /// that it ignores the transformations (translation, rotation,
 169     /// scale, ...) that are applied to the entity.
 170     /// In other words, this function returns the bounds of the
 171     /// entity in the entity's coordinate system.
 172     ///
 173     /// \return Local bounding rectangle of the entity
 174     ///
 175     ////////////////////////////////////////////////////////////
 176     FloatRect getLocalBounds() const;
 177
 178     ////////////////////////////////////////////////////////////
 179     /// \brief Get the global bounding rectangle of the entity
 180     ///
 181     /// The returned rectangle is in global coordinates, which means
 182     /// that it takes in account the transformations (translation,
 183     /// rotation, scale, ...) that are applied to the entity.
 184     /// In other words, this function returns the bounds of the
 185     /// sprite in the global 2D world's coordinate system.
 186     ///
 187     /// \return Global bounding rectangle of the entity
 188     ///
 189     ////////////////////////////////////////////////////////////
 190     FloatRect getGlobalBounds() const;
 191
 192 private:
 193
 194     ////////////////////////////////////////////////////////////
 195     /// \brief Draw the sprite to a render target
 196     ///
 197     /// \param target Render target to draw to
 198     /// \param states Current render states
 199     ///
 200     ////////////////////////////////////////////////////////////
 201     virtual void draw(RenderTarget& target, RenderStates states) const;
 202
 203     ////////////////////////////////////////////////////////////
 204     /// \brief Update the vertices' positions
 205     ///
 206     ////////////////////////////////////////////////////////////
 207     void updatePositions();
 208
 209     ////////////////////////////////////////////////////////////
 210     /// \brief Update the vertices' texture coordinates
 211     ///
 212     ////////////////////////////////////////////////////////////
 213     void updateTexCoords();
 214
 215     ////////////////////////////////////////////////////////////
 216     // Member data
 217     ////////////////////////////////////////////////////////////
 218     Vertex         m_vertices[4]; ///< Vertices defining the sprite's geometry
 219     const Texture* m_texture;     ///< Texture of the sprite
 220     IntRect        m_textureRect; ///< Rectangle defining the area of the source texture to display
 221 };
 222
 223 } // namespace sf
 224
 225
 226 #endif // SFML_SPRITE_HPP
 227
 228
 229 ////////////////////////////////////////////////////////////
 230 /// \class sf::Sprite
 231 /// \ingroup graphics
 232 ///
 233 /// sf::Sprite is a drawable class that allows to easily display
 234 /// a texture (or a part of it) on a render target.
 235 ///
 236 /// It inherits all the functions from sf::Transformable:
 237 /// position, rotation, scale, origin. It also adds sprite-specific
 238 /// properties such as the texture to use, the part of it to display,
 239 /// and some convenience functions to change the overall color of the
 240 /// sprite, or to get its bounding rectangle.
 241 ///
 242 /// sf::Sprite works in combination with the sf::Texture class, which
 243 /// loads and provides the pixel data of a given texture.
 244 ///
 245 /// The separation of sf::Sprite and sf::Texture allows more flexibility
 246 /// and better performances: indeed a sf::Texture is a heavy resource,
 247 /// and any operation on it is slow (often too slow for real-time
 248 /// applications). On the other side, a sf::Sprite is a lightweight
 249 /// object which can use the pixel data of a sf::Texture and draw
 250 /// it with its own transformation/color/blending attributes.
 251 ///
 252 /// It is important to note that the sf::Sprite instance doesn't
 253 /// copy the texture that it uses, it only keeps a reference to it.
 254 /// Thus, a sf::Texture must not be destroyed while it is
 255 /// used by a sf::Sprite (i.e. never write a function that
 256 /// uses a local sf::Texture instance for creating a sprite).
 257 ///
 258 /// See also the note on coordinates and undistorted rendering in sf::Transformable.
 259 ///
 260 /// Usage example:
 261 /// \code
 262 /// // Declare and load a texture
 263 /// sf::Texture texture;
 264 /// texture.loadFromFile("texture.png");
 265 ///
 266 /// // Create a sprite
 267 /// sf::Sprite sprite;
 268 /// sprite.setTexture(texture);
 269 /// sprite.setTextureRect(sf::IntRect(10, 10, 50, 30));
 270 /// sprite.setColor(sf::Color(255, 255, 255, 200));
 271 /// sprite.setPosition(100, 25);
 272 ///
 273 /// // Draw it
 274 /// window.draw(sprite);
 275 /// \endcode
 276 ///
 277 /// \see sf::Texture, sf::Transformable
 278 ///
 279 ////////////////////////////////////////////////////////////