Gamedev Framework (gf)  0.3.0
A C++11 framework for 2D games
TextureAtlas.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 #ifndef GF_TEXTURE_ATLAS_H
22 #define GF_TEXTURE_ATLAS_H
23 
24 #include <map>
25 #include <string>
26 
27 #include "Filesystem.h"
28 #include "Portability.h"
29 #include "Rect.h"
30 
31 namespace gf {
32 #ifndef DOXYGEN_SHOULD_SKIP_THIS
33 inline namespace v1 {
34 #endif
35 
36  class Texture;
37 
38  /**
39  * @ingroup game
40  * @brief A collection of sub-texture
41  *
42  * A texture atlas is a collection of sub-texture that have been packed
43  * together in a single texture. The description of the sub-textures is done
44  * in a XML file. This description is a name and the texture coordinates in
45  * the texture.
46  *
47  * Here is an example of a XML file containing an atlas:
48  *
49  * ~~~{.xml}
50  * <TextureAtlas imagePath="bricks.png">
51  * <SubTexture name="brickBlack01" x="718" y="500" width="32" height="32"/>
52  * <SubTexture name="brickBlack02" x="716" y="66" width="64" height="32"/>
53  * ...
54  * </TextureAtlas>
55  * ~~~
56  *
57  * gf::TextureAtlas is able to read the XML file and give the coordinates
58  * thanks to the name of the sub-texture, either in pixels or in texture
59  * normalized coordinates.
60  *
61  * @sa gf::Texture
62  * @sa [Texture Atlas (wikipedia)](https://en.wikipedia.org/wiki/Texture_atlas)
63  */
65  public:
66  /**
67  * @brief Default constructor
68  */
70  : m_texture(nullptr)
71  {
72 
73  }
74 
75  /**
76  * @brief Load an atlas from a XML file
77  *
78  * Load the data about the sub-textures from a XML file.
79  *
80  * @param filename The filename of the XML file
81  * @return True if the file has been loaded
82  */
83  bool loadFromFile(const Path& filename);
84 
85  /**
86  * @brief Set the texture path
87  *
88  * The texture path comes from the XML file when it is loaded.
89  *
90  * @param path The path to the texture
91  * @sa getTexturePath()
92  */
93  void setTexturePath(const Path& path) {
94  m_texturePath = path;
95  }
96 
97  /**
98  * @brief Get the texture path
99  *
100  * @return The path to the texture
101  * @sa setTexturePath()
102  */
103  const Path& getTexturePath() const {
104  return m_texturePath;
105  }
106 
107  /**
108  * @brief Change the source texture of the atlas
109  *
110  * The texture must exist as long as the atlas uses it. Indeed, the
111  * atlas doesn't store its own copy of the texture, but rather keeps
112  * a pointer to the one that you passed to this function.
113  * If the source texture is destroyed and the atlas tries to
114  * use it, the behavior is undefined.
115  *
116  * @param texture New texture
117  *
118  * @sa getTexture(), getTexturePath()
119  */
120  void setTexture(const Texture& texture) {
121  m_texture = &texture;
122  }
123 
124  /**
125  * @brief Get the source texture of the atlas
126  *
127  * If the atlas has no source texture, a `nullptr` pointer is returned.
128  * The returned pointer is const, which means that you can't
129  * modify the texture when you retrieve it with this function.
130  *
131  * @return Pointer to the atlas' texture
132  *
133  * @sa setTexture()
134  */
135  const Texture *getTexture() const {
136  return m_texture;
137  }
138 
139  /**
140  * @brief Unset the source texture of the atlas
141  *
142  * After a call to this function, the atlas has no source texture.
143  *
144  * @sa setTexture()
145  */
146  void unsetTexture() {
147  m_texture = nullptr;
148  }
149 
150  /**
151  * @brief Add a sub-texture to the atlas
152  *
153  * @param name The name of the sub-texture
154  * @param rect The rectangle inside the texture
155  */
156  void addSubTexture(std::string name, const RectU& rect);
157 
158  /**
159  * @brief Get the sub-texture rectangle
160  *
161  * @param name The name of the sub-texture
162  * @return The rectangle corresponding to the name
163  * @sa getTextureRect()
164  */
165  RectU getSubTexture(const std::string& name) const;
166 
167  /**
168  * @brief Get the texture rectangle in normalized coordinates
169  *
170  * @param name The name of the sub-texture
171  * @return The texture rectangle in normalized coordinates
172  * @sa getSubTexture()
173  */
174  RectF getTextureRect(const std::string& name) const;
175 
176  private:
177  Path m_texturePath;
178  const Texture *m_texture;
179  std::map<std::string, RectU> m_rects;
180  };
181 
182 #ifndef DOXYGEN_SHOULD_SKIP_THIS
183 }
184 #endif
185 }
186 
187 #endif // GF_TEXTURE_ATLAS_H
A collection of sub-texture.
Definition: TextureAtlas.h:64
void setTexture(const Texture &texture)
Change the source texture of the atlas.
Definition: TextureAtlas.h:120
A texture for colored images.
Definition: Texture.h:339
TextureAtlas()
Default constructor.
Definition: TextureAtlas.h:69
Definition: Action.h:34
RectF getTextureRect(const std::string &name) const
Get the texture rectangle in normalized coordinates.
const Path & getTexturePath() const
Get the texture path.
Definition: TextureAtlas.h:103
void addSubTexture(std::string name, const RectU &rect)
Add a sub-texture to the atlas.
const Texture * getTexture() const
Get the source texture of the atlas.
Definition: TextureAtlas.h:135
#define GF_API
Definition: Portability.h:35
void setTexturePath(const Path &path)
Set the texture path.
Definition: TextureAtlas.h:93
bool loadFromFile(const Path &filename)
Load an atlas from a XML file.
void unsetTexture()
Unset the source texture of the atlas.
Definition: TextureAtlas.h:146
RectU getSubTexture(const std::string &name) const
Get the sub-texture rectangle.