Gamedev Framework (gf)  0.3.0
A C++11 framework for 2D games
Image.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_IMAGE_H
25 #define GF_IMAGE_H
26 
27 #include <cstddef>
28 #include <cstdint>
29 #include <vector>
30 
31 #include "Filesystem.h"
32 #include "Portability.h"
33 #include "Vector.h"
34 
35 namespace gf {
36 #ifndef DOXYGEN_SHOULD_SKIP_THIS
37 inline namespace v1 {
38 #endif
39 
40  class InputStream;
41 
42  /**
43  * @ingroup graphics
44  * @brief Class for loading, manipulating and saving images
45  *
46  * gf::Image is an abstraction to manipulate images
47  * as bidimensional arrays of pixels. The class provides
48  * functions to load, read, write and save pixels, as well
49  * as many other useful functions.
50  *
51  * gf::Image can handle a unique internal representation of
52  * pixels, which is RGBA 32 bits. This means that a pixel
53  * must be composed of 8 bits red, green, blue and alpha
54  * channels -- just like a gf::Color4u.
55  *
56  * All the functions that return an array of pixels follow
57  * this rule, and all parameters that you pass to gf::Image
58  * functions (such as `loadFromMemory()`) must use this
59  * representation as well.
60  *
61  * A gf::Image can be copied, but it is a heavy resource and
62  * if possible you should always use (const) references to
63  * pass or return them to avoid useless copies.
64  *
65  * Usage example:
66  *
67  * ~~~{.cc}
68  * // Load an image file from a file
69  * gf::Image background;
70  *
71  * if (!background.loadFromFile("background.jpg")) {
72  * return -1;
73  * }
74  *
75  * // Create a 20x20 image filled with black color
76  * gf::Image image;
77  * image.create({ 20, 20 }, sf::Color4u{0xFF, 0xFF, 0xFF, 0xFF});
78  *
79  * // Make the top-left pixel transparent
80  * gf::Color4u color = image.getPixel({ 0, 0 });
81  * color.a = 0;
82  * image.setPixel({ 0, 0 }, color);
83  *
84  * // Save the image to a file
85  * if (!image.saveToFile("result.png")) {
86  * return -1;
87  * }
88  * ~~~
89  *
90  * @sa gf::Texture
91  */
92  class GF_API Image {
93  public:
94  /**
95  * @brief Default constructor
96  *
97  * Creates an empty image.
98  */
99  Image();
100 
101  /**
102  * @brief Default copy constructor
103  */
104  Image(const Image&) = default;
105 
106  /**
107  * @brief Default copy assignment
108  */
109  Image& operator=(const Image&) = default;
110 
111  /**
112  * @brief Default move constructor
113  */
114  Image(Image&&) = default;
115 
116  /**
117  * @brief Default move assignment
118  */
119  Image& operator=(Image&&) = default;
120 
121  /**
122  * @brief Create the image and fill it with a unique color
123  *
124  * @param size Size of the image
125  * @param color Fill color
126  */
127  void create(Vector2u size, const Color4u& color = Color4u{0x00, 0x00, 0x00, 0xFF});
128 
129  /**
130  * @brief Create the image from an array of pixels
131  *
132  * The @a pixel array is assumed to contain 32-bits RGBA pixels,
133  * and have the given @a size. If not, this is an undefined behavior.
134  * If @a pixels is null, an empty image is created.
135  *
136  * @param size Size of the image
137  * @param pixels Array of pixels to copy to the image
138  */
139  void create(Vector2u size, const uint8_t* pixels);
140 
141  /**
142  * @brief Create the image from an array of pixels
143  *
144  * The @a pixel array is assumed to contain 24-bits RGB pixels,
145  * and have the given @a size. If not, this is an undefined behavior.
146  * If @a pixels is null, an empty image is created.
147  *
148  * @param size Size of the image
149  * @param pixels Array of pixels to copy to the image
150  */
151  void createRGB(Vector2u size, const uint8_t* pixels);
152 
153  /**
154  * @brief Load the image from a file on disk
155  *
156  * The supported image formats are bmp, png, tga, jpg, gif,
157  * psd, hdr and pic. Some format options are not supported,
158  * like progressive jpeg.
159  * If this function fails, the image is left unchanged.
160  *
161  * @param filename Path of the image file to load
162  *
163  * @return true if loading was successful
164  *
165  * @sa loadFromMemory(), loadFromStream(), saveToFile()
166  */
167  bool loadFromFile(const Path& filename);
168 
169  /**
170  * @brief Load the image from a file in memory
171  *
172  * The supported image formats are bmp, png, tga, jpg, gif,
173  * psd, hdr and pic. Some format options are not supported,
174  * like progressive jpeg.
175  * If this function fails, the image is left unchanged.
176  *
177  * @param data Pointer to the file data in memory
178  * @param length Length of the data to load, in bytes
179  *
180  * @return true if loading was successful
181  *
182  * @sa loadFromFile(), loadFromStream(), saveToFile()
183  */
184  bool loadFromMemory(const uint8_t* data, std::size_t length);
185 
186  /**
187  * @brief Load the image from a custom stream
188  *
189  * The supported image formats are bmp, png, tga, jpg, gif,
190  * psd, hdr and pic. Some format options are not supported,
191  * like progressive jpeg.
192  * If this function fails, the image is left unchanged.
193  *
194  * @param stream Source stream to read from
195  *
196  * @return True if loading was successful
197  *
198  * @sa loadFromFile(), loadFromMemory()
199  */
200  bool loadFromStream(InputStream& stream);
201 
202  /**
203  * @brief Save the image to a file on disk
204  *
205  * The format of the image is automatically deduced from
206  * the extension. The supported image formats are bmp, png
207  * and tga. The destination file is overwritten if it already
208  * exists. This function fails if the image is empty.
209  *
210  * @param filename Path of the file to save
211  *
212  * @return true if saving was successful
213  *
214  * @sa create, loadFromFile(), loadFromMemory(), loadFromStream()
215  */
216  bool saveToFile(const Path& filename) const;
217 
218  /**
219  * @brief Return the size (width and height) of the image
220  *
221  * @return Size of the image, in pixels
222  */
223  Vector2u getSize() const;
224 
225  /**
226  * @brief Create a transparency mask from a specified color-key
227  *
228  * This function sets the alpha value of every pixel matching
229  * the given color to @a alpha (0 by default), so that they
230  * become transparent.
231  *
232  * @param color %Color to make transparent
233  * @param alpha Alpha value to assign to transparent pixels
234  */
235  void createMaskFromColor(const Color4u& color, uint8_t alpha = 0);
236 
237  /**
238  * @brief Change the color of a pixel
239  *
240  * This function doesn't check the validity of the pixel
241  * coordinates, using out-of-range values will result in
242  * an undefined behavior.
243  *
244  * @param pos Coordinate of pixel to change
245  * @param color New color of the pixel
246  *
247  * @sa getPixel
248  */
249  void setPixel(Vector2u pos, const Color4u& color);
250 
251  /**
252  * @brief Get the color of a pixel
253  *
254  * This function doesn't check the validity of the pixel
255  * coordinates, using out-of-range values will result in
256  * an undefined behavior.
257  *
258  * @param pos Coordinate of pixel to get
259  *
260  * @return %Color of the pixel at coordinates (x, y)
261  *
262  * @sa setPixel
263  */
264  Color4u getPixel(Vector2u pos) const;
265 
266  /**
267  * @brief Get a read-only pointer to the array of pixels
268  *
269  * The returned value points to an array of RGBA pixels made of
270  * 8 bits integers components. The size of the array is
271  * width * height * 4.
272  * Warning: the returned pointer may become invalid if you
273  * modify the image, so you should never store it for too long.
274  * If the image is empty, a null pointer is returned.
275  *
276  * @return Read-only pointer to the array of pixels
277  */
278  const uint8_t* getPixelsPtr() const;
279 
280  /**
281  * @brief Flip the pixels horizontally
282  *
283  * This function is needed internally. But you can use it if you want.
284  */
285  void flipHorizontally();
286 
287  private:
288  Vector2u m_size;
289  std::vector<uint8_t> m_pixels;
290 
291  };
292 
293 #ifndef DOXYGEN_SHOULD_SKIP_THIS
294 }
295 #endif
296 }
297 
298 #endif // GF_IMAGE_H
Image & operator=(Image &&)=default
Default move assignment.
Image()
Default constructor.
void create(Vector2u size, const uint8_t *pixels)
Create the image from an array of pixels.
bool loadFromStream(InputStream &stream)
Load the image from a custom stream.
Vector2u getSize() const
Return the size (width and height) of the image.
void flipHorizontally()
Flip the pixels horizontally.
Color4u getPixel(Vector2u pos) const
Get the color of a pixel.
bool saveToFile(const Path &filename) const
Save the image to a file on disk.
constexpr Vector(T x, T y, T z, T w)
Constructor that takes 4 components.
Definition: Vector.h:837
Image & operator=(const Image &)=default
Default copy assignment.
Class for loading, manipulating and saving images.
Definition: Image.h:92
Definition: Action.h:34
Image(const Image &)=default
Default copy constructor.
Abstract class for custom file input streams.
Definition: InputStream.h:51
void createMaskFromColor(const Color4u &color, uint8_t alpha=0)
Create a transparency mask from a specified color-key.
const uint8_t * getPixelsPtr() const
Get a read-only pointer to the array of pixels.
void createRGB(Vector2u size, const uint8_t *pixels)
Create the image from an array of pixels.
Image(Image &&)=default
Default move constructor.
void create(Vector2u size, const Color4u &color=Color4u{0x00, 0x00, 0x00, 0xFF})
Create the image and fill it with a unique color.
#define GF_API
Definition: Portability.h:35
bool loadFromFile(const Path &filename)
Load the image from a file on disk.
void setPixel(Vector2u pos, const Color4u &color)
Change the color of a pixel.
bool loadFromMemory(const uint8_t *data, std::size_t length)
Load the image from a file in memory.