Adonthell  0.4
image.h
Go to the documentation of this file.
1 /*
2  $Id: image.h,v 1.28 2004/10/25 06:55:01 ksterker Exp $
3 
4  Copyright (C) 1999/2000/2001/2004 Alexandre Courbot
5  Part of the Adonthell Project http://adonthell.linuxgames.com
6 
7  This program is free software; you can redistribute it and/or modify
8  it under the terms of the GNU General Public License.
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY.
11 
12  See the COPYING file for more details.
13 */
14 
15 
16 /**
17  * @file image.h
18  * @author Alexandre Courbot <alexandrecourbot@linuxgames.com>
19  *
20  * @brief Declares the image class.
21  *
22  *
23  */
24 
25 
26 #ifndef IMAGE_H_
27 #define IMAGE_H_
28 
29 #include "fileops.h"
30 #include "screen.h"
31 
32 
33 /**
34  * Image manipulation class.
35  * Designed to work with single images, without having to care about the bit
36  * depth. This class is widely used through the %game - in fact it handles
37  * everything that is displayed on the %screen.
38  * This class highly relies on surface, so you'll probably want to have a look
39  * at it before using image.
40  */
41 class image : public surface
42 {
43 public:
44  /**
45  * Default constructor.
46  * The image created via this constructor is totally empty.
47  */
48  image ();
49 
50 #ifndef SWIG
51  /** Creates an image with a specified size.
52  * @param l length of the image.
53  * @param h height of the image.
54  * @param mode use screen::dblmode or set dbl_mode to false
55  *
56  * @attention Not accessible from Python.
57  */
58  image (u_int16 l, u_int16 h, bool mode = true);
59 
60  /**
61  * Create image from SDL_Surface.
62  * @param s surface
63  */
64  image (SDL_Surface *s, const SDL_Color & color);
65 #endif
66 
67  /** Destructor.
68  */
69  ~image ();
70 
71  /**
72  * Resize this image.
73  * All the content will be lost.
74  * If you want to zoom the image you'll want to see the zoom () function
75  * instead.
76  *
77  * @param l new length.
78  * @param h new height.
79  * @sa zoom ()
80  */
81  void resize (u_int16 l, u_int16 h);
82 
83  /**
84  * Resets the image to it's initial state, that is totally
85  * empty.
86  *
87  */
88  void clear ();
89 
90 
91  /**
92  * @name Loading / Saving Methods.
93  * These methods allows you to load and save
94  * an image in different formats.
95  *
96  */
97  //@{
98 
99 
100  /** Loads an image from an opened file, saved in %game internal format,
101  * with alpha and mask values.
102  * @param file the opened file from which to read.
103  * @return
104  * @li 0 in case of success.
105  * @li -1 in case of error.
106  * @sa load ()
107  */
108  s_int8 get (igzstream& file);
109 
110  /** Loads an image from a file name, in game internal format, with alpha
111  * and mask values.
112  * @param fname the name of the file to load.
113  * @return
114  * @li 0 in case of success.
115  * @li -1 in case of error.
116  * @sa get ()
117  */
118  s_int8 load (string fname);
119 
120  /** Loads an image from an opened file, saved in %game internal format,
121  * without alpha and mask values.
122  * @param file the opened file from which to read.
123  * @return
124  * @li 0 in case of success.
125  * @li -1 in case of error.
126  * @sa load_raw ()
127  */
128  s_int8 get_raw (igzstream& file);
129 
130  /** Loads an image from a file name, in game internal format, without alpha
131  * and mask values.
132  * @param fname the name of the file to load.
133  * @return
134  * @li 0 in case of success.
135  * @li -1 in case of error.
136  * @sa get_raw ()
137  */
138  s_int8 load_raw (string fname);
139 
140  /** Loads an image from an opened file, in PNM format, without
141  * alpha and mask values.
142  * @param file the opened file from which to read.
143  * @return
144  * @li 0 in case of success.
145  * @li -1 in case of error.
146  * @sa load_pnm ()
147  */
148  s_int8 get_pnm (SDL_RWops * file);
149 
150  /** Loads an image from a file name, in PNM format, without
151  * alpha and mask values.
152  * @param fname the name of the file to load.
153  * @return
154  * @li 0 in case of success.
155  * @li -1 in case of error.
156  * @sa get_pnm ()
157  */
158  s_int8 load_pnm (string fname);
159 
160  /** Saves an image into an opened file, in %game format, with
161  * alpha and mask values.
162  * @warning as the image which is saved comes from a %screen's depth
163  * surface, it will be slightly altered during the save.
164  * If you want a class capable of saving images with full
165  * truecolor quality, use image_edit instead.
166  * @param file opened file where to save into.
167  * @return
168  * @li 0 in case of success.
169  * @li -1 in case of error.
170  * @sa save ()
171  */
172  s_int8 put (ogzstream& file) const;
173 
174  /** Saves an image into an file, in %game format, with
175  * alpha and mask values.
176  * @warning as the image which is saved comes from a %screen's depth
177  * surface, it will be slightly altered during the save.
178  * If you want a class capable of saving images with full
179  * truecolor quality, use image_edit instead.
180  * @param fname file name where to save into.
181  * @return
182  * @li 0 in case of success.
183  * @li -1 in case of error.
184  * @sa put ()
185  */
186  s_int8 save (string fname) const;
187 
188  /** Saves an image into an opened file, in %game format, without
189  * alpha and mask values.
190  * @warning as the image which is saved comes from a %screen's depth
191  * surface, it will be slightly altered during the save.
192  * If you want a class capable of saving images with full
193  * truecolor quality, use image_edit instead.
194  * @param file opened file where to save into.
195  * @return
196  * @li 0 in case of success.
197  * @li -1 in case of error.
198  * @sa save_raw ()
199  */
200  s_int8 put_raw (ogzstream& file) const;
201 
202  /** Saves an image into an file, in %game format, without
203  * alpha and mask values.
204  * @warning as the image which is saved comes from a %screen's depth
205  * surface, it will be slightly altered during the save.
206  * If you want a class capable of saving images with full
207  * truecolor quality, use image_edit instead.
208  * @param fname file name where to save into.
209  * @return
210  * @li 0 in case of success.
211  * @li -1 in case of error.
212  * @sa put_raw ()
213  */
214  s_int8 save_raw (string fname) const;
215 
216  /** Saves an image into an opened file, in PNM format, without
217  * alpha and mask values.
218  * @warning as the image which is saved comes from a %screen's depth
219  * surface, it will be slightly altered during the save.
220  * If you want a class capable of saving images with full
221  * truecolor quality, use image_edit instead.
222  * @param file opened file where to save into.
223  * @return
224  * @li 0 in case of success.
225  * @li -1 in case of error.
226  * @sa save_pnm ()
227  */
228  s_int8 put_pnm (SDL_RWops * file) const;
229 
230  /** Saves an image into an file, in PNM format, without
231  * alpha and mask values.
232  * @warning as the image which is saved comes from a %screen's depth
233  * surface, it will be slightly altered during the save.
234  * If you want a class capable of saving images with full
235  * truecolor quality, use image_edit instead.
236  * @param fname file name where to save into.
237  * @return
238  * @li 0 in case of success.
239  * @li -1 in case of error.
240  * @sa put_pnm ()
241  */
242  s_int8 save_pnm (string fname) const;
243 
244 
245  //@}
246 
247 
248  /**
249  * @name Special FX Methods.
250  * Allows you to put fantasy in your image manipulations! Can
251  * eventually even be usefull...
252  *
253  */
254  //@{
255 
256 
257  /** Zooms a surface.
258  * Zoom the content of the src surface into this image, to it's own size.
259  * @param src the source image to zoom.
260  */
261  void zoom (const surface& src)
262  {
263  zoom (src, length (), height (), 0, 0);
264  }
265 
266 #ifndef SWIG
267  /**
268  * Zooms a surface.
269  * Zoom the content of the src surface into this image, to the size
270  * (l, h), at position (x, y) on this image.
271  *
272  * @param src The source surface to zoom.
273  * @param l length of the zoomed image.
274  * @param h height of the zoomed image.
275  * @param x X offset on the destination image.
276  * @param y Y offset on the destination image.
277  *
278  * @attention Not available from Python. Use zoom_to () from Python instead.
279  * @sa zoom_to ()
280  */
281  void zoom (const surface& src, u_int16 l, u_int16 h, u_int16 x = 0, u_int16 y = 0);
282 #endif
283 
284  /**
285  * Synonym of zoom () to guarantee its access from Python.
286  *
287  * @sa zoom ()
288  *
289  */
290  void zoom_to (const surface& src, u_int16 l, u_int16 h, u_int16 x = 0, u_int16 y = 0)
291  {
292  zoom (src, l, h, x, y);
293  }
294 
295  /** Tiles a surface.
296  * Tiles the src surface so this image is totally filled.
297  * @param source the source surface to tile.
298  */
299  void tile (const surface& src)
300  {
301  tile (src, length (), height ());
302  }
303 
304 #ifndef SWIG
305  /**
306  * Tiles a surface.
307  * Tiles the src surface so the area of this image starting at position
308  * (x, y) and (l, h) sized is totally filled.
309  * @param source the source surface to tile.
310  * @param l length of the area to tile.
311  * @param h height of the area to tile.
312  * @param x X offset on the destination image.
313  * @param y Y offset on the destination image.
314  *
315  * @attention Not available from Python. Use tile_to () from Python instead.
316  * @sa tile_to ()
317  */
318  void tile (const surface& src, u_int16 l, u_int16 h, u_int16 x = 0, u_int16 y = 0);
319 #endif
320 
321  /**
322  * Synonym of tile () to guarantee its access from Python.
323  *
324  * @sa tile ()
325  *
326  */
327  void tile_to (const surface& src, u_int16 l, u_int16 h, u_int16 x = 0, u_int16 y = 0)
328  {
329  tile (src, l, h, x, y);
330  }
331 
332  /**
333  * Applies a "brightness" to a surface.
334  * Lighten (or darken) the src surface and put the result into this image.
335  * This image will be resized to the src surface's size.
336  * @param src the source surface to lighten/darken.
337  * @param cont the "brightness" value, if < 256 the image will be
338  * darkened.
339  * @todo modify it so when < 128 -> darken, > 128 -> brighten.
340  * @param proceed_mask if set to true, then the translucent pixels will
341  * be lightened/darkened too.
342  */
343  void brightness (const surface& src, u_int8 cont, bool proceed_mask = false);
344  //@}
345 
346 
347 #ifndef SWIG
348  /**
349  * Image copy (similar to copy ()).
350  *
351  * @attention Not available from Python. Use copy () from Python instead.
352  * @sa copy ()
353  */
354  image& operator = (const image& src);
355 #endif
356 
357  /**
358  * Synonym of operator = to guarantee its access from Python.
359  *
360  * @sa operator =
361  */
362  void copy (const image& src)
363  {
364  *this = src;
365  }
366 
367 private:
368  /**
369  * Forbid value passing.
370  */
371  image(const image& src);
372 
373  /**
374  * Converts a raw image source recorded in RGB to the current screen depth
375  * and put it to this image.
376  *
377  * @param rawdata raw data to convert.
378  * @param l length of the raw image.
379  * @param h height of the raw image.
380  */
381  void raw2display (void * rawdata, u_int16 l, u_int16 h);
382 };
383 
384 
385 #endif