Gamedev Framework (gf)  0.3.0
A C++11 framework for 2D games
Sprite.h
1 /*
2  * Gamedev Framework (gf)
3  * Copyright (C) 2016 Julien Bernard
4  *
5  * This software is provided 'as-is', without any express or implied
6  * warranty. In no event will the authors be held liable for any damages
7  * 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
11  * freely, subject to the following restrictions:
12  *
13  * 1. The origin of this software must not be misrepresented; you must not
14  * claim that you wrote the original software. If you use this software
15  * in a product, an acknowledgment in the product documentation would be
16  * appreciated but is not required.
17  * 2. Altered source versions must be plainly marked as such, and must not be
18  * misrepresented as being the original software.
19  * 3. This notice may not be removed or altered from any source distribution.
20  *
21  * Part of this file comes from SFML, with the same license:
22  * Copyright (C) 2007-2015 Laurent Gomila (laurent@sfml-dev.org)
23  */
24 #ifndef GF_SPRITE_H
25 #define GF_SPRITE_H
26 
27 #include "Transformable.h"
28 #include "Portability.h"
29 #include "Vertex.h"
30 #include "VertexBuffer.h"
31 
32 namespace gf {
33 #ifndef DOXYGEN_SHOULD_SKIP_THIS
34 inline namespace v1 {
35 #endif
36  class Texture;
37 
38  /**
39  * @ingroup graphics
40  * @brief A drawable representation of a texture, with its
41  * own transformations, color, etc.
42  *
43  * gf::Sprite is a drawable class that allows to easily display
44  * a texture (or a part of it) on a render target.
45  *
46  * It inherits all the functions from gf::Transformable:
47  * position, rotation, scale, origin. It also adds sprite-specific
48  * properties such as the texture to use, the part of it to display,
49  * and some convenience functions to change the overall color of the
50  * sprite, or to get its bounding rectangle.
51  *
52  * gf::Sprite works in combination with the gf::Texture class, which
53  * loads and provides the pixel data of a given texture.
54  *
55  * The separation of gf::Sprite and gf::Texture allows more flexibility
56  * and better performances: indeed a gf::Texture is a heavy resource,
57  * and any operation on it is slow (often too slow for real-time
58  * applications). On the other side, a gf::Sprite is a lightweight
59  * object which can use the pixel data of a gf::Texture and draw
60  * it with its own transformation/color/blending attributes.
61  *
62  * It is important to note that the gf::Sprite instance doesn't
63  * copy the texture that it uses, it only keeps a reference to it.
64  * Thus, a gf::Texture must not be destroyed while it is
65  * used by a gf::Sprite (i.e. never write a function that
66  * uses a local gf::Texture instance for creating a sprite).
67  *
68  * Usage example:
69  * ~~~{.cc}
70  * // Declare and load a texture
71  * gf::Texture texture;
72  * texture.loadFromFile("texture.png");
73  *
74  * // Create a sprite
75  * gf::Sprite sprite;
76  * sprite.setTexture(texture);
77  * sprite.setTextureRect({ 0.1f, 0.1f, 0.5f, 0.3f });
78  * sprite.setColor({ 1.0f, 1.0f, 1.0f, 0.8f });
79  * sprite.setPosition({ 100.0f, 25.0f });
80  *
81  * // Draw it
82  * renderer.draw(sprite);
83  * ~~~
84  *
85  * @sa gf::Texture, gf::Transformable
86  */
87  class GF_API Sprite : public Transformable {
88  public:
89  /**
90  * @brief Default constructor
91  *
92  * Creates an empty sprite with no source texture.
93  */
94  Sprite();
95 
96  /**
97  * @brief Construct the sprite from a source texture
98  *
99  * @param texture Source texture
100  *
101  * @sa setTexture()
102  */
103  Sprite(const Texture& texture);
104 
105  /**
106  * @brief Construct the sprite from a sub-rectangle of a source texture
107  *
108  * @param texture Source texture
109  * @param textureRect Sub-rectangle of the texture to assign to the sprite
110  *
111  * @sa setTexture(), setTextureRect()
112  */
113  Sprite(const Texture& texture, const RectF& textureRect);
114 
115  /**
116  * @brief Change the source texture of the sprite
117  *
118  * The texture must exist as long as the sprite uses it. Indeed, the
119  * sprite doesn't store its own copy of the texture, but rather keeps
120  * a pointer to the one that you passed to this function.
121  * If the source texture is destroyed and the sprite tries to
122  * use it, the behavior is undefined.
123  *
124  * If `resetRect` is true, the texture rect property of
125  * the sprite is automatically adjusted to the size of the new
126  * texture. If it is false, the texture rect is left unchanged.
127  *
128  * @param texture New texture
129  * @param resetRect Should the texture rect be reset to the size of the new texture?
130  *
131  * @sa getTexture(), setTextureRect()
132  */
133  void setTexture(const Texture& texture, bool resetRect = false);
134 
135  /**
136  * @brief Get the source texture of the sprite
137  *
138  * If the sprite has no source texture, a `nullptr` pointer is returned.
139  * The returned pointer is const, which means that you can't
140  * modify the texture when you retrieve it with this function.
141  *
142  * @return Pointer to the sprite's texture
143  *
144  * @sa setTexture()
145  */
146  const Texture *getTexture() const {
147  return m_texture;
148  }
149 
150  /**
151  * @brief Unset the source texture of the sprite
152  *
153  * After a call to this function, the sprite has no source texture.
154  *
155  * @sa setTexture()
156  */
157  void unsetTexture();
158 
159  /**
160  * @brief Set the sub-rectangle of the texture that the sprite will display
161  *
162  * The texture rect is useful when you don't want to display
163  * the whole texture, but rather a part of it.
164  * By default, the texture rect covers the entire texture.
165  *
166  * The rectangle is given in texture coordinates, meaning that
167  * @f$(0,0)@f$ is the top left corner and @f$(1,1)@f$ is the
168  * bottom right corner.
169  *
170  * @param rect Rectangle defining the region of the texture to display
171  *
172  * @sa getTextureRect(), setTexture()
173  */
174  void setTextureRect(const RectF& rect);
175 
176  /**
177  * @brief Get the sub-rectangle of the texture displayed by the sprite
178  *
179  * @return Texture rectangle of the sprite in texture coordinates
180  *
181  * @sa setTextureRect()
182  */
183  const RectF& getTextureRect() const {
184  return m_textureRect;
185  }
186 
187  /**
188  * @brief Set the global color of the sprite
189  *
190  * This color is modulated (multiplied) with the sprite's
191  * texture. It can be used to colorize the sprite, or change
192  * its global opacity.
193  *
194  * By default, the sprite's color is opaque white.
195  *
196  * @param color New color of the sprite
197  *
198  * @sa getColor()
199  */
200  void setColor(const Color4f& color);
201 
202  /**
203  * @brief Get the global color of the sprite
204  *
205  * @return Global color of the sprite
206  *
207  * @sa setColor()
208  */
209  const Color4f& getColor() const;
210 
211 
212  /**
213  * @brief Get the local bounding rectangle of the entity
214  *
215  * The returned rectangle is in local coordinates, which means
216  * that it ignores the transformations (translation, rotation,
217  * scale, ...) that are applied to the entity.
218  * In other words, this function returns the bounds of the
219  * entity in the entity's coordinate system.
220  *
221  * @return Local bounding rectangle of the entity
222  */
223  RectF getLocalBounds() const;
224 
225  /**
226  * @brief Set the anchor origin of the entity
227  *
228  * Compute the origin of the entity based on the local bounds and
229  * the specified anchor. Internally, this function calls
230  * `Transformable::setOrigin()`.
231  *
232  * @param anchor The anchor of the entity
233  * @sa getLocalBounds(), Transformable::setOrigin()
234  */
235  void setAnchor(Anchor anchor);
236 
237  /**
238  * @brief Create a buffer with the current geometry
239  *
240  * The geometry is uploaded in the graphics memory so that it's faster
241  * to draw.
242  *
243  * @return A buffer with the current geometry
244  */
246 
247  virtual void draw(RenderTarget& target, RenderStates states) override;
248 
249  private:
250  void updatePositions();
251  void updateTexCoords();
252 
253  private:
254  const Texture *m_texture;
255  RectF m_textureRect;
256  Vertex m_vertices[4];
257  RectF m_bounds;
258  };
259 
260 #ifndef DOXYGEN_SHOULD_SKIP_THIS
261 }
262 #endif
263 }
264 
265 #endif // GF_SPRITE_H
Decomposed transform defined by a position, a rotation and a scale.
Definition: Transformable.h:113
Sprite()
Default constructor.
Sprite(const Texture &texture)
Construct the sprite from a source texture.
void setAnchor(Anchor anchor)
Set the anchor origin of the entity.
RectF getLocalBounds() const
Get the local bounding rectangle of the entity.
Base class for all render targets (window, texture, ...)
Definition: RenderTarget.h:65
const Color4f & getColor() const
Get the global color of the sprite.
Define the states used for drawing to a RenderTarget.
Definition: RenderStates.h:82
A point associated with a color and a texture coordinate.
Definition: Vertex.h:75
A drawable representation of a texture, with its own transformations, color, etc. ...
Definition: Sprite.h:87
Data in the graphics memory.
Definition: VertexBuffer.h:70
void setColor(const Color4f &color)
Set the global color of the sprite.
Sprite(const Texture &texture, const RectF &textureRect)
Construct the sprite from a sub-rectangle of a source texture.
A texture for colored images.
Definition: Texture.h:339
virtual void draw(RenderTarget &target, RenderStates states) override
Draw the object to a render target.
const Texture * getTexture() const
Get the source texture of the sprite.
Definition: Sprite.h:146
Definition: Action.h:34
VertexBuffer commitGeometry() const
Create a buffer with the current geometry.
void setTexture(const Texture &texture, bool resetRect=false)
Change the source texture of the sprite.
Anchor
The origin anchor of the transformable object.
Definition: Transformable.h:45
void unsetTexture()
Unset the source texture of the sprite.
void setTextureRect(const RectF &rect)
Set the sub-rectangle of the texture that the sprite will display.
#define GF_API
Definition: Portability.h:35
const RectF & getTextureRect() const
Get the sub-rectangle of the texture displayed by the sprite.
Definition: Sprite.h:183