Adonthell  0.4
surface.h
Go to the documentation of this file.
1 /*
2  $Id: surface.h,v 1.9 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 surface.h
18  * @author Alexandre Courbot <alexandrecourbot@linuxgames.com>
19  *
20  * @brief Declares the surface class.
21  *
22  *
23  */
24 
25 
26 #ifndef SURFACE_H_
27 #define SURFACE_H_
28 
29 
30 #include "drawable.h"
31 
32 
33 
34 /**
35  * Class where drawables can actually be drawn to.
36  * Another name for a surface could eventually be "pixmap". A surface
37  * is nothing more than an array of pixels where drawables can put their
38  * %image to. This class has only two purposes: to group methods shared by
39  * image and screen, and to ensure that every drawing operation can be performed
40  * on the screen or on an image.
41  *
42  * Every surface has two special parameters:
43  * @li a mask parameter, indicating whether the transparent color (which hex
44  * triplet is 0xFF00FF, and you can get with screen::trans_col ()) should
45  * be drawn or not.
46  * @li an alpha parameter, indicating the level of translucency of the surface.
47  * it's range go from 0 to 255, 0 being totally invisible and 255 totally
48  * opaque.
49  *
50  */
51 class surface : public drawable
52 {
53 public:
54 
55  /**
56  * Default constructor.
57  * The surface will be totally empty, that is
58  * (0, 0) sized, no mask, alpha value of 255 (opaque).
59  *
60  */
61  surface (bool mode = true);
62 
63  /**
64  * Destructor.
65  *
66  */
67  virtual ~surface ();
68 
69 
70  /**
71  * @name Settings.
72  * These methods sets the parameters of the surface.
73  *
74  */
75  //@{
76 
77 
78  /**
79  *
80  * Returns whether a surface is masked or not.
81  *
82  * @return true if the surface is masked, false if it isn't.
83  */
84  bool is_masked () const
85  {
86  return mask_on;
87  }
88 
89  /**
90  * Sets the mask parameter of the surface.
91  *
92  * @param m true if the surface should be masked, false otherwise.
93  */
94  void set_mask (bool m);
95 
96  /**
97  * Returns the alpha value of the surface.
98  *
99  *
100  * @return the alpha value of the surface.
101  */
102  u_int8 alpha () const
103  {
104  return alpha_;
105  }
106 
107  /**
108  * Sets the alpha value of the surface.
109  *
110  * @param a The new alpha value for this surface.
111  */
112  void set_alpha (u_int8 a);
113 
114 
115  bool is_dbl_mode () const { return dbl_mode; }
116 
117  void set_dbl_mode (bool mode) { dbl_mode = mode; }
118 
119  //@}
120 
121 
122  /**
123  * @name Drawing Methods.
124  *
125  */
126 
127  //@{
128 
129 
130  /**
131  * Draw the surface.
132  *
133  * @param x X position where to draw.
134  * @param y Y position where to draw.
135  * @param da_opt optional drawing_area to use during the drawing operation.
136  * @param target pointer to the surface where to draw the drawable. If NULL, draw on the screen.
137  */
138  void draw (s_int16 x, s_int16 y, const drawing_area * da_opt = NULL,
139  surface * target = NULL) const
140  {
141  draw (x, y, 0, 0, length (), height (), da_opt, target);
142  }
143 
144 #ifndef SWIG
145  /**
146  * Draw a part of the surface.
147  *
148  * @param x X position where to draw.
149  * @param y Y position where to draw.
150  * @param sx X position where to start drawing from this image.
151  * @param sy Y position where to start drawing from this image.
152  * @param sl length of the part of this image to draw.
153  * @param sh height of the part of this image to draw.
154  * @param da_opt optional drawing_area to use during the drawing operation.
155  * @param target pointer to the surface where to draw the drawable. If NULL, draw on the screen.
156  *
157  * @attention Not accessible from Python. Use draw_part () from Python instead.
158  * @sa draw_part ()
159  *
160  */
161  void draw (s_int16 x, s_int16 y, s_int16 sx, s_int16 sy, u_int16 sl,
162  u_int16 sh, const drawing_area * da_opt = NULL,
163  surface * target = NULL) const;
164 #endif
165 
166  /**
167  * Synonym of draw () to guarantee its access from Python.
168  *
169  * @sa draw ()
170  *
171  */
172  void draw_part (s_int16 x, s_int16 y, s_int16 sx, s_int16 sy, u_int16 sl,
173  u_int16 sh, const drawing_area * da_opt = NULL,
174  surface * target = NULL) const
175  {
176  draw (x, y, sx, sy, sl, sh, da_opt, target);
177  }
178 
179  /**
180  * Fills an area of the surface with a given color.
181  *
182  * The color you pass to this function MUST come from a game's function
183  * (like surface::get_pix () or screen::trans_col ()), because of the
184  * screen depth dependant value of the col argument.
185  *
186  * @param x X position where to fill.
187  * @param y Y position where to fill.
188  * @param l length of the area to fill.
189  * @param h height of the area to fill.
190  * @param col color to fill the surface with.
191  * @param da_opt optionnal drawing_area to use during the fill operation.
192  *
193  */
194  void fillrect (s_int16 x, s_int16 y, u_int16 l, u_int16 h,
195  u_int32 col, drawing_area * da_opt = NULL);
196 
197 #ifndef SWIG
198  /**
199  * Fills an area of the surface with a given color.
200  *
201  * This function is independant of the screen depth. You just give
202  * the red, green and blue triplets of the color you want to fill with.
203  *
204  * @param x X position where to fill.
205  * @param y Y position where to fill.
206  * @param l length of the area to fill.
207  * @param h height of the area to fill.
208  * @param r red value of the color to fill with.
209  * @param g green value of the color to fill with.
210  * @param b blue value of the color to fill with.
211  * @param da_opt optionnal drawing_area to use during the fill operation.
212  *
213  * @attention Not accessible from Python. Use fillrect_rgb from Python instead.
214  * @sa fillrect_rgb ()
215  */
217  u_int8 g, u_int8 b, drawing_area * da_opt = NULL)
218  {
219  fillrect (x, y, l, h, SDL_MapRGB (vis->format, r, g, b), da_opt);
220  }
221 #endif
222 
223  /**
224  * Synonym of fillrect () to guarantee its access from Python.
225  *
226  * @sa fillrect ()
227  */
229  u_int8 g, u_int8 b, drawing_area * da_opt = NULL)
230  {
231  fillrect (x, y, l, h, r, g, b, da_opt);
232  }
233 
234 
235  //@}
236 
237  /**
238  * @name Pixel manipulation Methods.
239  * Use these methods to directly and quickly manipulate
240  * pixels from a surface.
241  *
242  */
243  //@{
244 
245 
246  /**
247  * Locks the surface.
248  * Sometimes you may want to access directly the pixels of a surface. This
249  * can be done with the get_pix () and put_pix () methods, thus you must
250  * ABSOLUTELY lock the surface before doing so. This function is made for
251  * that. Note that using get_pix () or put_pix () without locking the surface
252  * may result in unpredictable behavior, crashes included.
253  *
254  */
255  void lock () const;
256 
257  /**
258  * Unlock the surface after you've worked on it's pixels with the
259  * get_pix () and put_pix () methods.
260  *
261  */
262  void unlock () const;
263 
264  /**
265  * Puts a pixel of a given color.
266  *
267  * The col parameter is specific to the current screen depth,
268  * and must come from a game's function like get_pix or
269  * screen::trans_col ().
270  *
271  * @param x X position of the pixel to change.
272  * @param y Y position of the pixel to change.
273  * @param col color to put.
274  */
275  void put_pix (u_int16 x, u_int16 y, u_int32 col);
276 
277 #ifndef SWIG
278  /**
279  * Puts a pixel of a given color.
280  *
281  * The r, g and b parameters are the hex triplets of the color
282  * to put.
283  *
284  * @param x X position of the pixel to change.
285  * @param y Y position of the pixel to change.
286  * @param r red value of the color to put.
287  * @param g green value of the color to put.
288  * @param b blue value of the color to put.
289  *
290  * @attention Not accessible from Python. Use put_pix_rgb from Python instead.
291  * @sa put_pix_rgb ()
292  *
293  */
294  void put_pix (u_int16 x, u_int16 y, u_int8 r, u_int8 g, u_int8 b)
295  {
296  put_pix (x, y, SDL_MapRGB (vis->format, r, g, b));
297  }
298 #endif
299 
300  /**
301  * Synonym of put_pix () to guarantee its access from Python.
302  *
303  * @sa put_pix ()
304  */
306  {
307  put_pix (x, y, r, g, b);
308  }
309 
310  /**
311  * Gets a pixel from the surface.
312  *
313  * The col parameter is specific to the current screen depth,
314  * and can be used with functions like put_pix ().
315  *
316  * @param x X position of the pixel to change.
317  * @param y Y position of the pixel to change.
318  * @param col returned color.
319  */
320  void get_pix (u_int16 x, u_int16 y, u_int32& col) const;
321 
322 #ifndef SWIG
323  /**
324  * Gets a pixel from a surface.
325  *
326  * The returned r, g and b values are the hex triplets of the color.
327  *
328  * @param x X position of the pixel to change.
329  * @param y Y position of the pixel to change.
330  * @param r red value of the color.
331  * @param g green value of the color.
332  * @param b blue value of the color.
333  *
334  * @attention Not accessible from Python. Use get_pix_rgb from Python instead.
335  * @sa get_pix_rgb ()
336  */
337  void get_pix (u_int16 x, u_int16 y, u_int8& r, u_int8& g, u_int8& b) const
338  {
339  u_int32 col;
340  get_pix (x, y, col);
341  SDL_GetRGB (col, vis->format, &r, &g, &b);
342  }
343 #endif
344 
345  /**
346  * Synonym of get_pix () to guarantee its access from Python.
347  *
348  * @sa get_pix ()
349  */
350  void get_pix_rgb (u_int16 x, u_int16 y, u_int8 r, u_int8 g, u_int8 b) const
351  {
352  get_pix (x, y, r, g, b);
353  }
354 
355  //@}
356 
357 
358 #ifndef SWIG
359  /**
360  * Surface copy (similar to copy ()).
361  *
362  * @attention Not available from Python. Use copy () from Python instead.
363  * @sa copy ()
364  */
365  surface& operator = (surface& src);
366 #endif
367 
368  /**
369  * Synonym of operator = to guarantee its access from Python.
370  *
371  * @sa operator =
372  */
373  void copy (surface& src)
374  {
375  *this = src;
376  }
377 
378  /**
379  * The actual surface.
380  *
381  */
382  SDL_Surface *vis;
383 protected:
384 
385  /**
386  * Resize this surface. All the content will be lost.
387  *
388  * @param l new length.
389  * @param h new height.
390  */
391  void resize (u_int16 l, u_int16 h);
392 
393  /**
394  * Resets the surface to it's initial state, that is totally
395  * empty.
396  *
397  */
398  void clear ();
399 
400  /**
401  * Must be set to true when you change the surface
402  * by something else than class surface operations.
403  *
404  */
405  mutable bool changed;
406 
407 #ifndef SWIG
408  void resize_aux (u_int16 l, u_int16 h);
409  void double_size(const surface & src);
410  void half_size(const surface & src);
411  void get_pix_aux (u_int16 x, u_int16 y, u_int32& col) const;
412  void put_pix_aux (u_int16 x, u_int16 y, u_int32 col);
413 #endif
414 
415  /// double mode
416  bool dbl_mode;
417 
418 private:
419 
420  /**
421  * Forbid value passing.
422  *
423  */
424  surface (surface & src);
425 
426  /// SDL_Rects used in every blitting function.
427  static SDL_Rect srcrect, dstrect;
428 
429  /// Mask
430  bool mask_on;
431 
432  /// Alpha value
433  u_int8 alpha_;
434 
435  /// Set at true by screen's contructor to prevent screen surface from
436  /// being deleted two times.
437  bool not_screen;
438 
439  /// Used internally for blitting operations with drawing_areas.
440  void setup_rects (u_int16 x, u_int16 y, const drawing_area * draw_to) const
441  {
442  setup_rects (x, y, 0, 0, length (), height (), draw_to);
443  }
444 
445  /// Used internally for blitting operations with drawing_areas.
446  void setup_rects (s_int16 x, s_int16 y, s_int16 sx, s_int16 sy,
447  u_int16 sl, u_int16 sh, const drawing_area * draw_to) const;
448 
449 #ifndef SWIG
450  friend class screen;
451 #endif
452 };
453 
454 #endif
void get_pix_rgb(u_int16 x, u_int16 y, u_int8 r, u_int8 g, u_int8 b) const
Synonym of get_pix () to guarantee its access from Python.
Definition: surface.h:350
u_int16 length() const
Returns the length of the drawable.
Definition: drawable.h:76
bool is_masked() const
Returns whether a surface is masked or not.
Definition: surface.h:84
#define u_int16
16 bits long unsigned integer
Definition: types.h:32
surface & operator=(surface &src)
Surface copy (similar to copy ()).
Definition: surface.cc:400
surface(bool mode=true)
Default constructor.
Definition: surface.cc:183
void put_pix_rgb(u_int16 x, u_int16 y, u_int8 r, u_int8 g, u_int8 b)
Synonym of put_pix () to guarantee its access from Python.
Definition: surface.h:305
bool dbl_mode
double mode
Definition: surface.h:416
Class where drawables can actually be drawn to.
Definition: surface.h:51
void fillrect(s_int16 x, s_int16 y, u_int16 l, u_int16 h, u_int32 col, drawing_area *da_opt=NULL)
Fills an area of the surface with a given color.
Definition: surface.cc:260
#define u_int32
32 bits long unsigned integer
Definition: types.h:35
void put_pix(u_int16 x, u_int16 y, u_int8 r, u_int8 g, u_int8 b)
Puts a pixel of a given color.
Definition: surface.h:294
void fillrect(s_int16 x, s_int16 y, u_int16 l, u_int16 h, u_int8 r, u_int8 g, u_int8 b, drawing_area *da_opt=NULL)
Fills an area of the surface with a given color.
Definition: surface.h:216
#define u_int8
8 bits long unsigned integer
Definition: types.h:29
void resize(u_int16 l, u_int16 h)
Resize this surface.
Definition: surface.cc:422
void draw_part(s_int16 x, s_int16 y, s_int16 sx, s_int16 sy, u_int16 sl, u_int16 sh, const drawing_area *da_opt=NULL, surface *target=NULL) const
Synonym of draw () to guarantee its access from Python.
Definition: surface.h:172
void get_pix(u_int16 x, u_int16 y, u_int8 &r, u_int8 &g, u_int8 &b) const
Gets a pixel from a surface.
Definition: surface.h:337
void fillrect_rgb(s_int16 x, s_int16 y, u_int16 l, u_int16 h, u_int8 r, u_int8 g, u_int8 b, drawing_area *da_opt=NULL)
Synonym of fillrect () to guarantee its access from Python.
Definition: surface.h:228
Declares the drawable class.
void unlock() const
Unlock the surface after you've worked on it's pixels with the get_pix () and put_pix () methods...
Definition: surface.cc:294
u_int8 alpha() const
Returns the alpha value of the surface.
Definition: surface.h:102
void clear()
Resets the surface to it's initial state, that is totally empty.
Definition: surface.cc:447
void draw(s_int16 x, s_int16 y, const drawing_area *da_opt=NULL, surface *target=NULL) const
Draw the surface.
Definition: surface.h:138
Implements "drawing zones" for drawing operations.
Definition: drawing_area.h:50
void copy(surface &src)
Synonym of operator = to guarantee its access from Python.
Definition: surface.h:373
Screen access is made through this class.
Definition: screen.h:41
void set_alpha(u_int8 a)
Sets the alpha value of the surface.
Definition: surface.cc:208
u_int16 height() const
Returns the height of the drawable.
Definition: drawable.h:87
#define s_int16
16 bits long signed integer
Definition: types.h:41
SDL_Surface * vis
The actual surface.
Definition: surface.h:382
Abstract class for drawable objects manipulation.
Definition: drawable.h:55
void get_pix(u_int16 x, u_int16 y, u_int32 &col) const
Gets a pixel from the surface.
Definition: surface.cc:360
bool changed
Must be set to true when you change the surface by something else than class surface operations...
Definition: surface.h:405
void set_mask(bool m)
Sets the mask parameter of the surface.
Definition: surface.cc:198
virtual ~surface()
Destructor.
Definition: surface.cc:193
void lock() const
Locks the surface.
Definition: surface.cc:287
void put_pix(u_int16 x, u_int16 y, u_int32 col)
Puts a pixel of a given color.
Definition: surface.cc:301