Panda3D
 All Classes Functions Variables Enumerations
pnmImage.h
1 // Filename: pnmImage.h
2 // Created by: drose (14Jun00)
3 //
4 ////////////////////////////////////////////////////////////////////
5 //
6 // PANDA 3D SOFTWARE
7 // Copyright (c) Carnegie Mellon University. All rights reserved.
8 //
9 // All use of this software is subject to the terms of the revised BSD
10 // license. You should have received a copy of this license along
11 // with this source code in a file named "LICENSE."
12 //
13 ////////////////////////////////////////////////////////////////////
14 
15 #ifndef PNMIMAGE_H
16 #define PNMIMAGE_H
17 
18 #include "pandabase.h"
19 
20 #include "pnmImageHeader.h"
21 #include "pnmBrush.h"
22 #include "stackedPerlinNoise2.h"
23 #include "convert_srgb.h"
24 #include "luse.h"
25 
26 class PNMReader;
27 class PNMWriter;
28 class PNMFileType;
29 
30 ////////////////////////////////////////////////////////////////////
31 // Class : PNMImage
32 // Description : The name of this class derives from the fact that we
33 // originally implemented it as a layer on top of the
34 // "pnm library", based on netpbm, which was built to
35 // implement pbm, pgm, and pbm files, and is the
36 // underlying support of a number of public-domain image
37 // file converters. Nowadays we are no longer derived
38 // directly from the pnm library, mainly to allow
39 // support of C++ iostreams instead of the C stdio FILE
40 // interface.
41 //
42 // Conceptually, a PNMImage is a two-dimensional array
43 // of xels, which are the PNM-defined generic pixel
44 // type. Each xel may have a red, green, and blue
45 // component, or (if the image is grayscale) a gray
46 // component. The image may be read in, the individual
47 // xels manipulated, and written out again, or a black
48 // image may be constructed from scratch.
49 //
50 // A PNMImage has a color space and a maxval, the
51 // combination of which defines how a floating-point
52 // linear color value is encoded as an integer value in
53 // memory. The functions ending in _val operate on
54 // encoded colors, whereas the regular ones work with
55 // linear floating-point values. All operations are
56 // color space correct unless otherwise specified.
57 //
58 // The image is of size XSize() by YSize() xels,
59 // numbered from top to bottom, left to right, beginning
60 // at zero.
61 //
62 // Files can be specified by filename, or by an iostream
63 // pointer. The filename "-" refers to stdin or stdout.
64 //
65 // This class is not inherently thread-safe; use it
66 // from a single thread or protect access using a mutex.
67 ////////////////////////////////////////////////////////////////////
68 class EXPCL_PANDA_PNMIMAGE PNMImage : public PNMImageHeader {
69 PUBLISHED:
70  INLINE PNMImage();
71  PNMImage(const Filename &filename, PNMFileType *type = NULL);
72  INLINE PNMImage(int x_size, int y_size, int num_channels = 3,
73  xelval maxval = 255, PNMFileType *type = NULL,
74  ColorSpace color_space = CS_linear);
75  INLINE PNMImage(const PNMImage &copy);
76  INLINE void operator = (const PNMImage &copy);
77 
78  INLINE ~PNMImage();
79 
80  INLINE xelval clamp_val(int input_value) const;
81  INLINE xelval to_val(float input_value) const;
82  INLINE xelval to_alpha_val(float input_value) const;
83  INLINE float from_val(xelval input_value) const;
84  INLINE float from_alpha_val(xelval input_value) const;
85 
86  void clear();
87  void clear(int x_size, int y_size, int num_channels = 3,
88  xelval maxval = 255, PNMFileType *type = NULL,
89  ColorSpace color_space = CS_linear);
90 
91  void copy_from(const PNMImage &copy);
92  void copy_channel(const PNMImage &copy, int src_channel, int dest_channel);
93  void copy_header_from(const PNMImageHeader &header);
94  void take_from(PNMImage &orig);
95 
96  INLINE void fill(float red, float green, float blue);
97  INLINE void fill(float gray = 0.0);
98 
99  void fill_val(xelval red, xelval green, xelval blue);
100  INLINE void fill_val(xelval gray = 0);
101 
102  INLINE void alpha_fill(float alpha = 0.0);
103  void alpha_fill_val(xelval alpha = 0);
104 
105  INLINE void set_read_size(int x_size, int y_size);
106  INLINE void clear_read_size();
107  INLINE bool has_read_size() const;
108  INLINE int get_read_x_size() const;
109  INLINE int get_read_y_size() const;
110  INLINE ColorSpace get_color_space() const;
111 
112  BLOCKING bool read(const Filename &filename, PNMFileType *type = NULL,
113  bool report_unknown_type = true);
114  BLOCKING bool read(istream &data, const string &filename = string(),
115  PNMFileType *type = NULL,
116  bool report_unknown_type = true);
117  BLOCKING bool read(PNMReader *reader);
118 
119  BLOCKING bool write(const Filename &filename, PNMFileType *type = NULL) const;
120  BLOCKING bool write(ostream &data, const string &filename = string(),
121  PNMFileType *type = NULL) const;
122  BLOCKING bool write(PNMWriter *writer) const;
123 
124  INLINE bool is_valid() const;
125 
126  INLINE void set_num_channels(int num_channels);
127  void set_color_type(ColorType color_type);
128  void set_color_space(ColorSpace color_space);
129 
130  INLINE void add_alpha();
131  INLINE void remove_alpha();
132  INLINE void make_grayscale();
133  void make_grayscale(float rc, float gc, float bc);
134  INLINE void make_rgb();
135 
136  void premultiply_alpha();
137  void unpremultiply_alpha();
138 
139  BLOCKING void reverse_rows();
140  BLOCKING void flip(bool flip_x, bool flip_y, bool transpose);
141 
142  BLOCKING void set_maxval(xelval maxval);
143 
144  // The *_val() functions return or set the color values in the range
145  // [0..get_maxval()]. This range may be different for different
146  // images! Use the corresponding functions (without _val()) to work
147  // in the normalized range [0..1]. These return values in the
148  // image's stored color space.
149 
150  INLINE xel &get_xel_val(int x, int y);
151  INLINE xel get_xel_val(int x, int y) const;
152  INLINE void set_xel_val(int x, int y, const xel &value);
153  INLINE void set_xel_val(int x, int y, xelval r, xelval g, xelval b);
154  INLINE void set_xel_val(int x, int y, xelval gray);
155 
156  INLINE xelval get_red_val(int x, int y) const;
157  INLINE xelval get_green_val(int x, int y) const;
158  INLINE xelval get_blue_val(int x, int y) const;
159  INLINE xelval get_gray_val(int x, int y) const;
160  INLINE xelval get_alpha_val(int x, int y) const;
161 
162  INLINE void set_red_val(int x, int y, xelval r);
163  INLINE void set_green_val(int x, int y, xelval g);
164  INLINE void set_blue_val(int x, int y, xelval b);
165  INLINE void set_gray_val(int x, int y, xelval gray);
166  INLINE void set_alpha_val(int x, int y, xelval a);
167 
168  xelval get_channel_val(int x, int y, int channel) const;
169  void set_channel_val(int x, int y, int channel, xelval value);
170  float get_channel(int x, int y, int channel) const;
171  void set_channel(int x, int y, int channel, float value);
172 
173  PixelSpec get_pixel(int x, int y) const;
174  void set_pixel(int x, int y, const PixelSpec &pixel);
175 
176  // The corresponding get_xel(), set_xel(), get_red(), etc. functions
177  // automatically scale their values by get_maxval() into the range
178  // [0..1], and into the linear color space.
179 
180  INLINE LRGBColorf get_xel(int x, int y) const;
181  INLINE void set_xel(int x, int y, const LRGBColorf &value);
182  INLINE void set_xel(int x, int y, float r, float g, float b);
183  INLINE void set_xel(int x, int y, float gray);
184 
185  INLINE LColorf get_xel_a(int x, int y) const;
186  INLINE void set_xel_a(int x, int y, const LColorf &value);
187  INLINE void set_xel_a(int x, int y, float r, float g, float b, float a);
188 
189  INLINE float get_red(int x, int y) const;
190  INLINE float get_green(int x, int y) const;
191  INLINE float get_blue(int x, int y) const;
192  INLINE float get_gray(int x, int y) const;
193  INLINE float get_alpha(int x, int y) const;
194 
195  INLINE void set_red(int x, int y, float r);
196  INLINE void set_green(int x, int y, float g);
197  INLINE void set_blue(int x, int y, float b);
198  INLINE void set_gray(int x, int y, float gray);
199  INLINE void set_alpha(int x, int y, float a);
200 
201  INLINE float get_bright(int x, int y) const;
202  INLINE float get_bright(int x, int y, float rc, float gc,
203  float bc) const;
204  INLINE float get_bright(int x, int y, float rc, float gc,
205  float bc, float ac) const;
206 
207  INLINE void blend(int x, int y, const LRGBColorf &val, float alpha);
208  void blend(int x, int y, float r, float g, float b, float alpha);
209 
210  void copy_sub_image(const PNMImage &copy, int xto, int yto,
211  int xfrom = 0, int yfrom = 0,
212  int x_size = -1, int y_size = -1);
213  void blend_sub_image(const PNMImage &copy, int xto, int yto,
214  int xfrom = 0, int yfrom = 0,
215  int x_size = -1, int y_size = -1,
216  float pixel_scale = 1.0);
217  void add_sub_image(const PNMImage &copy, int xto, int yto,
218  int xfrom = 0, int yfrom = 0,
219  int x_size = -1, int y_size = -1,
220  float pixel_scale = 1.0);
221  void mult_sub_image(const PNMImage &copy, int xto, int yto,
222  int xfrom = 0, int yfrom = 0,
223  int x_size = -1, int y_size = -1,
224  float pixel_scale = 1.0);
225  void darken_sub_image(const PNMImage &copy, int xto, int yto,
226  int xfrom = 0, int yfrom = 0,
227  int x_size = -1, int y_size = -1,
228  float pixel_scale = 1.0);
229  void lighten_sub_image(const PNMImage &copy, int xto, int yto,
230  int xfrom = 0, int yfrom = 0,
231  int x_size = -1, int y_size = -1,
232  float pixel_scale = 1.0);
233  void threshold(const PNMImage &select_image, int channel, float threshold,
234  const PNMImage &lt, const PNMImage &ge);
235  BLOCKING void fill_distance_inside(const PNMImage &mask, float threshold, int radius, bool shrink_from_border);
236  BLOCKING void fill_distance_outside(const PNMImage &mask, float threshold, int radius);
237 
238  void rescale(float min_val, float max_val);
239 
240  void copy_channel(const PNMImage &copy, int xto, int yto, int cto,
241  int xfrom = 0, int yfrom = 0, int cfrom = 0,
242  int x_size = -1, int y_size = -1);
243 
244  void render_spot(const LColorf &fg, const LColorf &bg,
245  float min_radius, float max_radius);
246 
247  void expand_border(int left, int right, int bottom, int top,
248  const LColorf &color);
249 
250  // The bodies for the non-inline *_filter() functions can be found
251  // in the file pnm-image-filter.cxx.
252 
253  INLINE void box_filter(float radius = 1.0);
254  INLINE void gaussian_filter(float radius = 1.0);
255 
256  void unfiltered_stretch_from(const PNMImage &copy);
257  void box_filter_from(float radius, const PNMImage &copy);
258  void gaussian_filter_from(float radius, const PNMImage &copy);
259  void quick_filter_from(const PNMImage &copy,
260  int xborder = 0, int yborder = 0);
261 
262  void make_histogram(Histogram &hist);
263  void perlin_noise_fill(float sx, float sy, int table_size = 256,
264  unsigned long seed = 0);
265  void perlin_noise_fill(StackedPerlinNoise2 &perlin);
266 
267  void remix_channels(const LMatrix4 &conv);
268  INLINE void gamma_correct(float from_gamma, float to_gamma);
269  INLINE void gamma_correct_alpha(float from_gamma, float to_gamma);
270  INLINE void apply_exponent(float gray_exponent);
271  INLINE void apply_exponent(float gray_exponent, float alpha_exponent);
272  INLINE void apply_exponent(float red_exponent, float green_exponent, float blue_exponent);
273  void apply_exponent(float red_exponent, float green_exponent, float blue_exponent, float alpha_exponent);
274 
275  LRGBColorf get_average_xel() const;
276  LColorf get_average_xel_a() const;
277  float get_average_gray() const;
278 
279  void do_fill_distance(int xi, int yi, int d);
280 
281 PUBLISHED:
282  // Provides an accessor for reading or writing the contents of one row
283  // of the image in-place.
284  class EXPCL_PANDA_PNMIMAGE Row {
285  PUBLISHED:
286  INLINE size_t size() const;
287  INLINE LColorf operator[](int x) const;
288 #ifdef HAVE_PYTHON
289  INLINE void __setitem__(int x, const LColorf &v);
290 #endif
291  INLINE xel &get_xel_val(int x);
292  INLINE void set_xel_val(int x, const xel &v);
293  INLINE xelval get_alpha_val(int x) const;
294  INLINE void set_alpha_val(int x, xelval v);
295 
296  public:
297  INLINE Row(PNMImage &image, int y);
298 
299  private:
300  PNMImage &_image;
301  int _y;
302  };
303 
304  // Provides an accessor for reading the contents of one row of the
305  // image in-place.
306  class EXPCL_PANDA_PNMIMAGE CRow {
307  PUBLISHED:
308  INLINE size_t size() const;
309  INLINE LColorf operator[](int x) const;
310  INLINE xel get_xel_val(int x) const;
311  INLINE xelval get_alpha_val(int x) const;
312 
313  public:
314  INLINE CRow(const PNMImage &image, int y);
315 
316  private:
317  const PNMImage &_image;
318  int _y;
319  };
320 
321  INLINE Row operator [] (int y);
322  INLINE CRow operator [] (int y) const;
323 
324 public:
325  // Know what you are doing if you access the underlying data arrays
326  // directly.
327  INLINE xel *get_array();
328  INLINE const xel *get_array() const;
329  INLINE xelval *get_alpha_array();
330  INLINE const xelval *get_alpha_array() const;
331 
332  INLINE xel *take_array();
333  INLINE xelval *take_alpha_array();
334  void set_array(xel *array);
335  void set_alpha_array(xelval *alpha);
336 
337 private:
338  INLINE void allocate_array();
339  INLINE void allocate_alpha();
340 
341  INLINE xel *row(int row) const;
342  INLINE xelval *alpha_row(int row) const;
343 
344  INLINE void setup_sub_image(const PNMImage &copy, int &xto, int &yto,
345  int &xfrom, int &yfrom, int &x_size, int &y_size,
346  int &xmin, int &ymin, int &xmax, int &ymax);
347 
348  INLINE static void compute_spot_pixel(LColorf &c, float d2,
349  float min_radius, float max_radius,
350  const LColorf &fg, const LColorf &bg);
351 
352  void setup_rc();
353  void setup_encoding();
354 
355 PUBLISHED:
356  PNMImage operator ~() const;
357 
358  INLINE PNMImage operator + (const PNMImage &other) const;
359  INLINE PNMImage operator + (const LColorf &other) const;
360  INLINE PNMImage operator - (const PNMImage &other) const;
361  INLINE PNMImage operator - (const LColorf &other) const;
362  INLINE PNMImage operator * (const PNMImage &other) const;
363  INLINE PNMImage operator * (float multiplier) const;
364  INLINE PNMImage operator * (const LColorf &other) const;
365  void operator += (const PNMImage &other);
366  void operator += (const LColorf &other);
367  void operator -= (const PNMImage &other);
368  void operator -= (const LColorf &other);
369  void operator *= (const PNMImage &other);
370  void operator *= (float multiplier);
371  void operator *= (const LColorf &other);
372 
373 private:
374  friend class Row;
375 
376  xel *_array;
377  xelval *_alpha;
378  float _default_rc, _default_gc, _default_bc;
379 
380  int _read_x_size, _read_y_size;
381  bool _has_read_size;
382 
383  // The reciprocal of _maxval, as an optimization for from_val.
384  float _inv_maxval;
385 
386  // These method pointers contain the implementation for to_val and
387  // from_val, respectively, dependent on the maxval and color space.
388  ColorSpace _color_space;
389 
390  // The following enum determines which code path we should take in
391  // the set_xel and get_xel methods.
392  enum XelEncoding {
393  XE_generic,
394  XE_generic_alpha,
395  XE_generic_sRGB,
396  XE_generic_sRGB_alpha,
397  XE_uchar_sRGB,
398  XE_uchar_sRGB_alpha,
399  XE_uchar_sRGB_sse2,
400  XE_uchar_sRGB_alpha_sse2,
401  XE_scRGB,
402  XE_scRGB_alpha
403  } _xel_encoding;
404 };
405 
406 #include "pnmImage.I"
407 
408 #endif
This is the base class for all three-component vectors and points.
Definition: lvecBase3.h:105
ColorSpace get_color_space() const
Returns the color space that the image is encoded in, or CS_unspecified if unknown.
The name of this class derives from the fact that we originally implemented it as a layer on top of t...
Definition: pnmImage.h:68
This is the base class of a family of classes that represent particular image file types that PNMImag...
Definition: pnmFileType.h:35
Implements a multi-layer PerlinNoise, with one or more high-frequency noise functions added to a lowe...
The name of a file, such as a texture file or an Egg file.
Definition: filename.h:44
This is a 4-by-4 transform matrix.
Definition: lmatrix.h:451
This is an abstract base class that defines the interface for reading image files of various types...
Definition: pnmReader.h:31
This is an abstract base class that defines the interface for writing image files of various types...
Definition: pnmWriter.h:31
This is the base class for all three-component vectors and points.
Definition: lvecBase4.h:111
This is the base class of PNMImage, PNMReader, and PNMWriter.