source: trunk/libdjvu/GBitmap.h @ 280

Last change on this file since 280 was 280, checked in by rbri, 11 years ago

DJVU plugin: djvulibre updated to version 3.5.22

File size: 28.3 KB
Line 
1//C-  -*- C++ -*-
2//C- -------------------------------------------------------------------
3//C- DjVuLibre-3.5
4//C- Copyright (c) 2002  Leon Bottou and Yann Le Cun.
5//C- Copyright (c) 2001  AT&T
6//C-
7//C- This software is subject to, and may be distributed under, the
8//C- GNU General Public License, either Version 2 of the license,
9//C- or (at your option) any later version. The license should have
10//C- accompanied the software or you may obtain a copy of the license
11//C- from the Free Software Foundation at http://www.fsf.org .
12//C-
13//C- This program is distributed in the hope that it will be useful,
14//C- but WITHOUT ANY WARRANTY; without even the implied warranty of
15//C- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16//C- GNU General Public License for more details.
17//C-
18//C- DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from
19//C- Lizardtech Software.  Lizardtech Software has authorized us to
20//C- replace the original DjVu(r) Reference Library notice by the following
21//C- text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu):
22//C-
23//C-  ------------------------------------------------------------------
24//C- | DjVu (r) Reference Library (v. 3.5)
25//C- | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved.
26//C- | The DjVu Reference Library is protected by U.S. Pat. No.
27//C- | 6,058,214 and patents pending.
28//C- |
29//C- | This software is subject to, and may be distributed under, the
30//C- | GNU General Public License, either Version 2 of the license,
31//C- | or (at your option) any later version. The license should have
32//C- | accompanied the software or you may obtain a copy of the license
33//C- | from the Free Software Foundation at http://www.fsf.org .
34//C- |
35//C- | The computer code originally released by LizardTech under this
36//C- | license and unmodified by other parties is deemed "the LIZARDTECH
37//C- | ORIGINAL CODE."  Subject to any third party intellectual property
38//C- | claims, LizardTech grants recipient a worldwide, royalty-free,
39//C- | non-exclusive license to make, use, sell, or otherwise dispose of
40//C- | the LIZARDTECH ORIGINAL CODE or of programs derived from the
41//C- | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU
42//C- | General Public License.   This grant only confers the right to
43//C- | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to
44//C- | the extent such infringement is reasonably necessary to enable
45//C- | recipient to make, have made, practice, sell, or otherwise dispose
46//C- | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to
47//C- | any greater extent that may be necessary to utilize further
48//C- | modifications or combinations.
49//C- |
50//C- | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY
51//C- | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
52//C- | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF
53//C- | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
54//C- +------------------------------------------------------------------
55//
56// $Id: GBitmap.h,v 1.14 2007/05/19 03:07:33 leonb Exp $
57// $Name: release_3_5_22 $
58
59#ifndef _GBITMAP_H_
60#define _GBITMAP_H_
61#ifdef HAVE_CONFIG_H
62#include "config.h"
63#endif
64#if NEED_GNUG_PRAGMAS
65# pragma interface
66#endif
67
68
69#include "GSmartPointer.h"
70#ifndef NDEBUG
71#include "GException.h"
72#endif
73
74#ifdef HAVE_NAMESPACES
75namespace DJVU {
76# ifdef NOT_DEFINED // Just to fool emacs c++ mode
77}
78#endif
79#endif
80
81
82class GRect;
83class GMonitor;
84class ByteStream;
85
86/** @name GBitmap.h
87
88    Files #"GBitmap.h"# and #"GBitmap.cpp"# implement class \Ref{GBitmap}.
89    Instances of this class represent bilevel or gray-level images. The
90    ``bottom left'' coordinate system is used consistently in the DjVu library.
91    Line zero of a bitmap is the bottom line in the bitmap.  Pixels are
92    organized from left to right within each line.  As suggested by its name,
93    class #GBitmap# was initially a class for bilevel images only.  It was
94    extended to handle gray-level images when arose the need to render
95    anti-aliased images.  This class has been a misnomer since then.
96
97    {\bf ToDo} --- Class #GBitmap# can internally represent bilevel images
98    using a run-length encoded representation.  Some algorithms may benefit
99    from a direct access to this run information.
100
101    @memo
102    Generic support for bilevel and gray-level images.
103    @author
104    L\'eon Bottou <leonb@research.att.com>
105    @version
106    #$Id: GBitmap.h,v 1.14 2007/05/19 03:07:33 leonb Exp $#
107
108 */
109//@{
110
111
112/** Bilevel and gray-level images.  Instances of class #GBitmap# represent
113    bilevel or gray-level images.  Images are usually represented using one
114    byte per pixel.  Value zero represents a white pixel.  A value equal to
115    the number of gray levels minus one represents a black pixel.  The number
116    of gray levels is returned by the function \Ref{get_grays} and can be
117    manipulated by the functions \Ref{set_grays} and \Ref{change_grays}.
118
119    The bracket operator returns a pointer to the bytes composing one line of
120    the image.  This pointer can be used to read or write the image pixels.
121    Line zero represents the bottom line of the image.
122
123    The memory organization is setup in such a way that you can safely read a
124    few pixels located in a small border surrounding all four sides of the
125    image.  The width of this border can be modified using the function
126    \Ref{minborder}.  The border pixels are initialized to zero and therefore
127    represent white pixels.  You should never write anything into border
128    pixels because they are shared between images and between lines.  */
129
130class DJVUAPI GBitmap : public GPEnabled
131{
132protected:
133  GBitmap(void);
134  GBitmap(int nrows, int ncolumns, int border=0);
135  GBitmap(const GBitmap &ref);
136  GBitmap(const GBitmap &ref, int border);
137  GBitmap(const GBitmap &ref, const GRect &rect, int border=0);
138  GBitmap(ByteStream &ref, int border=0);
139public:
140  virtual ~GBitmap();
141  void destroy(void);
142  /** @name Construction. */
143  //@{
144  /** Constructs an empty GBitmap object.  The returned GBitmap has zero rows
145      and zero columns.  Use function \Ref{init} to change the size of the
146      image. */
147  static GP<GBitmap> create(void) {return new GBitmap;}
148
149  /** Constructs a GBitmap with #nrows# rows and #ncolumns# columns.  All
150      pixels are initialized to white. The optional argument #border#
151      specifies the size of the optional border of white pixels surrounding
152      the image.  The number of gray levels is initially set to #2#.  */
153  static GP<GBitmap> create(const int nrows, const int ncolumns, const int border=0)
154  {return new GBitmap(nrows,ncolumns, border); }
155
156  /** Copy constructor. Constructs a GBitmap by replicating the size, the
157      border and the contents of GBitmap #ref#. */
158  static GP<GBitmap> create(const GBitmap &ref)
159  {return new GBitmap(ref);}
160
161  /** Constructs a GBitmap by copying the contents of GBitmap #ref#. 
162      Argument #border# specifies the width of the optional border. */
163  static GP<GBitmap> create(const GBitmap &ref, const int border)
164  { return new GBitmap(ref,border); }
165
166  /** Constructs a GBitmap by copying a rectangular segment #rect# of GBitmap
167      #ref#.  The optional argument #border# specifies the size of the
168      optional border of white pixels surrounding the image. */
169  static GP<GBitmap> create(const GBitmap &ref, const GRect &rect, const int border=0)
170  { return new GBitmap(ref,rect,border); }
171
172  /** Constructs a GBitmap by reading PBM, PGM or RLE data from ByteStream
173      #ref# into this GBitmap. The optional argument #border# specifies the
174      size of the optional border of white pixels surrounding the image.  See
175      \Ref{PNM and RLE file formats} for more information.  */
176  static GP<GBitmap> create(ByteStream &ref, const int border=0)
177  { return new GBitmap(ref,border); }
178
179  //@}
180
181  /** @name Initialization. */
182  //@{
183  /** Resets this GBitmap size to #nrows# rows and #ncolumns# columns and sets
184      all pixels to white.  The optional argument #border# specifies the size
185      of the optional border of white pixels surrounding the image.  The
186      number of gray levels is initialized to #2#. */
187  void init(int nrows, int ncolumns, int border=0);
188  /** Initializes this GBitmap with the contents of the GBitmap #ref#.  The
189      optional argument #border# specifies the size of the optional border of
190      white pixels surrounding the image. */
191  void init(const GBitmap &ref, int border=0);
192  /** Initializes this GBitmap with a rectangular segment #rect# of GBitmap
193      #ref#.  The optional argument #border# specifies the size of the
194      optional border of white pixels surrounding the image. */
195  void init(const GBitmap &ref, const GRect &rect, int border=0);
196  /** Reads PBM, PGM or RLE data from ByteStream #ref# into this GBitmap.  The
197      previous content of the GBitmap object is lost. The optional argument
198      #border# specifies the size of the optional border of white pixels
199      surrounding the image. See \Ref{PNM and RLE file formats} for more
200      information. */
201  void init(ByteStream &ref, int border=0);
202  /** Assignment operator. Initializes this GBitmap by copying the size, the
203      border and the contents of GBitmap #ref#. */
204  GBitmap& operator=(const GBitmap &ref);
205  /** Initializes all the GBitmap pixels to value #value#. */
206  void fill(unsigned char value);
207  //@}
208
209  /** @name Accessing the pixels. */
210  //@{
211  /** Returns the number of rows (the image height). */
212  unsigned int rows() const;
213  /** Returns the number of columns (the image width). */
214  unsigned int columns() const;
215  /** Returns a constant pointer to the first byte of row #row#.
216      This pointer can be used as an array to read the row elements. */
217  const unsigned char *operator[] (int row) const;
218  /** Returns a pointer to the first byte of row #row#.
219      This pointer can be used as an array to read or write the row elements. */
220  unsigned char *operator[] (int row);
221  /** Returns the size of a row in memory (in pixels).  This number is equal
222      to the difference between pointers to pixels located in the same column
223      in consecutive rows.  This difference can be larger than the number of
224      columns in the image. */
225  unsigned int rowsize() const;
226  /** Makes sure that the border is at least #minimum# pixels large.  This
227      function does nothing it the border width is already larger than
228      #minimum#.  Otherwise it reorganizes the data in order to provide a
229      border of #minimum# pixels. */
230  void minborder(int minimum);
231  //@}
232
233  /** @name Managing gray levels. */
234  //@{
235  /** Returns the number of gray levels.
236      Value #2# denotes a bilevel image. */
237  int  get_grays() const;
238  /** Sets the number of gray levels without changing the pixels.
239      Argument #grays# must be in range #2# to #256#. */
240  void set_grays(int grays);
241  /** Changes the number of gray levels.  The argument #grays# must be in the
242      range #2# to #256#.  All the pixel values are then rescaled and clipped
243      in range #0# to #grays-1#. */
244  void change_grays(int grays);
245  /** Binarizes a gray level image using a threshold.  The number of gray
246      levels is reduced to #2# as in a bilevel image.  All pixels whose value
247      was strictly greater than #threshold# are set to black. All other pixels
248      are set to white. */
249  void binarize_grays(int threshold=0);
250  //@}
251
252  /** @name Optimizing the memory usage. 
253      The amount of memory used by bilevel images can be reduced using
254      function \Ref{compress}, which encodes the image using a run-length
255      encoding scheme.  The bracket operator decompresses the image on demand.
256      A few highly optimized functions (e.g. \Ref{blit}) can use a run-length
257      encoded bitmap without decompressing it.  There are unfortunate locking
258      issues associated with this capability (c.f. \Ref{share} and
259      \Ref{monitor}). */
260  //@{
261  /** Reduces the memory required for a bilevel image by using a run-length
262      encoded representation.  Functions that need to access the pixel array
263      will decompress the image on demand. */
264  void compress();
265  /** Decodes run-length encoded bitmaps and recreate the pixel array.
266      This function is usually called by #operator[]# when needed. */
267  void uncompress();
268  /** Returns the number of bytes allocated for this image. */
269  unsigned int get_memory_usage() const;
270  /** Returns a possibly null pointer to a \Ref{GMonitor} for this bitmap.
271      You should use this monitor to ensure that the data representation of the
272      bitmap will not change while you are using it.  We suggest using
273      class \Ref{GMonitorLock} which properly handles null monitor pointers. */
274  GMonitor *monitor() const;
275  /** Associates a \Ref{GMonitor} with this bitmap. This function should be
276      called on all bitmaps susceptible of being simultaneously used by
277      several threads.  It will make sure that function \Ref{monitor} returns
278      a pointer to a suitable monitor for this bitmap. */
279  void share();
280  //@}
281
282  /** @name Accessing RLE data.
283      The next functions are useful for processing bilevel images
284      encoded using the run length encoding scheme.  These functions always return
285      zero if the bitmap is not RLE encoded.  Function \Ref{compress} must
286      be used to ensure that the bitmap is RLE encoded.  */
287  //@{
288  /** Gets the pixels for line #rowno#.  One line of pixel is stored as
289      #unsigned char# values into array #bits#.  Each pixel is either 1 or 0.
290      The array must be large enough to hold the whole line.  The number of
291      pixels is returned. */
292
293  int rle_get_bits(int rowno, unsigned char *bits) const;
294
295  /** Gets the bitmap line rle data passed.  One line of pixel is stored one
296      with 8 bits per #unsigned char# in an array.  The array must be large
297      enough to hold the whole line.  */
298
299  static void rle_get_bitmap(const int ncolumns,const unsigned char *&runs,
300    unsigned char *bitmap, const bool invert );
301
302  /** Gets the lengths of all runs in line #rowno#.  The array #rlens# must be
303      large enough to accomodate #w+2# integers where #w# is the number of
304      columns in the image.  These integers represent the lengths of
305      consecutive runs of alternatively white or black pixels.  Lengths can be
306      zero in order to allow for lines starting with black pixels.  This
307      function returns the total number of runs in the line. */
308  int rle_get_runs(int rowno, int *rlens) const;
309  /** Gets the smallest rectangle enclosing black pixels.
310      Rectangle rect gives the coordinates of the smallest rectangle
311      containing all black pixels. Returns the number of black pixels. */
312  int rle_get_rect(GRect &rect) const;
313  //@}
314
315  /** @name Additive Blit. 
316      The blit functions are designed to efficiently construct an anti-aliased
317      image by copying smaller images at predefined locations.  The image of a
318      page, for instance, is composed by copying the images of characters at
319      predefined locations.  These functions are fairly optimized.  They can
320      directly use compressed GBitmaps (see \Ref{compress}).  We consider in
321      this section that each GBitmap comes with a coordinate system defined as
322      follows.  Position (#0#,#0#) corresponds to the bottom left corner of
323      the bottom left pixel.  Position (#1#,#1#) corresponds to the top right
324      corner of the bottom left pixel, which is also the bottom left corner of
325      the second pixel of the second row.  Position (#w#,#h#), where #w# and
326      #h# denote the size of the GBitmap, corresponds to the top right corner
327      of the top right pixel. */
328
329  //@{
330  /** Performs an additive blit of the GBitmap #bm#.  The GBitmap #bm# is
331      first positioned above the current GBitmap in such a way that position
332      (#u#,#v#) in GBitmap #bm# corresponds to position (#u#+#x#,#v#+#y#) in
333      the current GBitmap.  The value of each pixel in GBitmap #bm# is then
334      added to the value of the corresponding pixel in the current GBitmap.
335     
336      {\bf Example}: Assume for instance that the current GBitmap is initially
337      white (all pixels have value zero).  This operation copies the pixel
338      values of GBitmap #bm# at position (#x#,#y#) into the current GBitmap.
339      Note that function #blit# does not change the number of gray levels in
340      the current GBitmap.  You may have to call \Ref{set_grays} to specify
341      how the pixel values should be interpreted. */
342  void blit(const GBitmap *bm, int x, int y);
343  /** Performs an additive blit of the GBitmap #bm# with anti-aliasing.  The
344      GBitmap #bm# is first positioned above the current GBitmap in such a
345      way that position (#u#,#v#) in GBitmap #bm# corresponds to position
346      (#u#+#x#/#subsample#,#v#+#y#/#subsample#) in the current GBitmap.  This
347      mapping results in a contraction of GBitmap #bm# by a factor
348      #subsample#.  Each pixel of the current GBitmap can be covered by a
349      maximum of #subsample^2# pixels of GBitmap #bm#.  The value of
350      each pixel in GBitmap #bm# is then added to the value of the
351      corresponding pixel in the current GBitmap.
352
353      {\bf Example}: Assume for instance that the current GBitmap is initially
354      white (all pixels have value zero).  Each pixel of the current GBitmap
355      then contains the sum of the gray levels of the corresponding pixels in
356      GBitmap #bm#.  There are up to #subsample*subsample# such pixels.  If
357      for instance GBitmap #bm# is a bilevel image (pixels can be #0# or #1#),
358      the pixels of the current GBitmap can take values in range #0# to
359      #subsample*subsample#.  Note that function #blit# does not change the
360      number of gray levels in the current GBitmap.  You must call
361      \Ref{set_grays} to indicate that there are #subsample^2+1# gray
362      levels.  Since there is at most 256 gray levels, this also means that
363      #subsample# should never be greater than #15#.
364
365      {\bf Remark}: Arguments #x# and #y# do not represent a position in the
366      coordinate system of the current GBitmap.  According to the above
367      discussion, the position is (#x/subsample#,#y/subsample#).  In other
368      words, you can position the blit with a sub-pixel resolution.  The
369      resulting anti-aliasing changes are paramount to the image quality. */
370  void blit(const GBitmap *shape, int x, int y, int subsample);
371  //@}
372 
373  /** @name Saving images. 
374      The following functions write PBM, PGM and RLE files.  PBM and PGM are
375      well known formats for bilevel and gray-level images.  The RLE is a
376      simple run-length encoding scheme for bilevel images. These files can be
377      read using the ByteStream based constructor or initialization function.
378      See \Ref{PNM and RLE file formats} for more information. */
379  //@{
380  /** Saves the image into ByteStream #bs# using the PBM format.  Argument
381      #raw# selects the ``Raw PBM'' (1) or the ``Ascii PBM'' (0) format.  The
382      image is saved as a bilevel image.  All non zero pixels are considered
383      black pixels. See section \Ref{PNM and RLE file formats}. */
384  void save_pbm(ByteStream &bs, int raw=1);
385  /** Saves the image into ByteStream #bs# using the PGM format.  Argument
386      #raw# selects the ``Raw PGM'' (1) or the ``Ascii PGM'' (0) format.  The
387      image is saved as a gray level image.  See section
388      \Ref{PNM and RLE file formats}. */
389  void save_pgm(ByteStream &bs, int raw=1);
390  /** Saves the image into ByteStream #bs# using the RLE file format.
391      The image is saved as a bilevel image. All non zero pixels are
392      considered black pixels. See section \Ref{PNM and RLE file formats}. */
393  void save_rle(ByteStream &bs);
394  //@}
395
396  /** @name Stealing or borrowing the memory buffer (advanced). */
397  //@{
398  /** Steals the memory buffer of a GBitmap.  This function returns the
399      address of the memory buffer allocated by this GBitmap object.  The
400      offset of the first pixel in the bottom line is written into variable
401      #offset#.  Other lines can be accessed using pointer arithmetic (see
402      \Ref{rowsize}).  The GBitmap object no longer ``owns'' the buffer: you
403      must explicitly de-allocate the buffer using #operator delete []#.  This
404      de-allocation should take place after the destruction or the
405      re-initialization of the GBitmap object.  This function will return a
406      null pointer if the GBitmap object does not ``own'' the buffer in the
407      first place.  */
408  unsigned char *take_data(size_t &offset);
409  /** Initializes this GBitmap by borrowing a memory segment.  The GBitmap
410      then directly addresses the memory buffer #data# provided by the user.
411      This buffer must be large enough to hold #w*h# bytes representing each
412      one pixel.  The GBitmap object does not ``own'' the buffer: you must
413      explicitly de-allocate the buffer using #operator delete []#.  This
414      de-allocation should take place after the destruction or the
415      re-initialization of the GBitmap object.  */
416  inline void borrow_data(unsigned char &data, int w, int h);
417  /** Same as borrow_data, except GBitmap will call #delete[]#. */
418  void donate_data(unsigned char *data, int w, int h);
419  /** Return a pointer to the rle data. */
420  const unsigned char *get_rle(unsigned int &rle_length);
421  /** Initializes this GBitmap by setting the size to #h# rows and #w#
422      columns, and directly addressing the memory buffer #rledata# provided by
423      the user.  This buffer contains #rledatalen# bytes representing the
424      bitmap in run length encoded form.  The GBitmap object then ``owns'' the
425      buffer (unlike #borrow_data#, but like #donate_data#) and will
426      deallocate this buffer when appropriate: you should not deallocate this
427      buffer yourself.  The encoding of buffer #rledata# is similar to the
428      data segment of the RLE file format (without the header) documented in
429      \Ref{PNM and RLE file formats}.  */
430  void donate_rle(unsigned char *rledata, unsigned int rledatalen, int w, int h);
431  /** Static function for parsing run data.
432      This function returns one run length encoded at position #data#
433      and increments the pointer #data# accordingly. */
434  static inline int read_run(const unsigned char *&data);
435  static inline int read_run(unsigned char *&data);
436  /** Static function for generating run data.
437      This function encoded run length #count# at position #data#
438      and increments the pointer accordingly.  The pointer must
439      initially point to a large enough data buffer. */
440  static inline void append_run(unsigned char *&data, int count);
441  /** Rotates bitmap by 90, 180 or 270 degrees anticlockwise
442      and returns a new pixmap, input bitmap is not changed.
443      count can be 1, 2, or 3 for 90, 180, 270 degree rotation.
444      It returns the same bitmap if not rotated.
445      The input bitmap will be uncompressed for rotation*/
446  GP<GBitmap> rotate(int count=0);
447  //@}
448
449// These are constants, but we use enum because that works on older compilers.
450  enum {MAXRUNSIZE=0x3fff};
451  enum {RUNOVERFLOWVALUE=0xc0};
452  enum {RUNMSBMASK=0x3f};
453  enum {RUNLSBMASK=0xff};
454
455
456protected:
457  // bitmap components
458  unsigned short nrows;
459  unsigned short ncolumns;
460  unsigned short border;
461  unsigned short bytes_per_row;
462  unsigned short grays;
463  unsigned char  *bytes;
464  unsigned char  *bytes_data;
465  GPBuffer<unsigned char> gbytes_data;
466  unsigned char  *rle;
467  GPBuffer<unsigned char> grle;
468  unsigned char  **rlerows;
469  GPBuffer<unsigned char *> grlerows;
470  unsigned int   rlelength;
471private:
472  GMonitor       *monitorptr;
473public:
474  class ZeroBuffer;
475  friend class ZeroBuffer;
476  GP<ZeroBuffer> gzerobuffer; 
477private:
478  static int zerosize;
479  static unsigned char *zerobuffer;
480  static GP<ZeroBuffer> zeroes(int ncolumns);
481  static unsigned int read_integer(char &lookahead, ByteStream &ref);
482  static void euclidian_ratio(int a, int b, int &q, int &r);
483  int encode(unsigned char *&pruns,GPBuffer<unsigned char> &gpruns) const;
484  void decode(unsigned char *runs);
485  void read_pbm_text(ByteStream &ref); 
486  void read_pgm_text(ByteStream &ref, int maxval); 
487  void read_pbm_raw(ByteStream &ref); 
488  void read_pgm_raw(ByteStream &ref, int maxval); 
489  void read_rle_raw(ByteStream &ref); 
490  static void append_long_run(unsigned char *&data, int count);
491  static void append_line(unsigned char *&data,const unsigned char *row,
492                          const int rowlen,bool invert=false);
493  static void makerows(int,const int, unsigned char *, unsigned char *[]);
494  friend class DjVu_Stream;
495  friend class DjVu_PixImage;
496public:
497#ifndef NDEBUG
498  void check_border() const;
499#endif
500};
501
502
503/** @name PNM and RLE file formats
504
505    {\bf PNM} --- There are actually three PNM file formats: PBM for bilevel
506    images, PGM for gray level images, and PPM for color images.  These
507    formats are widely used by popular image manipulation packages such as
508    NetPBM \URL{http://www.arc.umn.edu/GVL/Software/netpbm.html} or
509    ImageMagick \URL{http://www.wizards.dupont.com/cristy/}.
510   
511    {\bf RLE} --- The binary RLE file format is a simple run-length encoding
512    scheme for storing bilevel images.  Encoding or decoding a RLE encoded
513    file is extremely simple. Yet RLE encoded files are usually much smaller
514    than the corresponding PBM encoded files.  RLE files always begin with a
515    header line composed of:\\
516    - the two characters #"R4"#,\\
517    - one or more blank characters,\\
518    - the number of columns, encoded using characters #"0"# to #"9"#,\\
519    - one or more blank characters,\\
520    - the number of lines, encoded using characters #"0"# to #"9"#,\\
521    - exactly one blank character (usually a line-feed character).
522
523    The rest of the file encodes a sequence of numbers representing the
524    lengths of alternating runs of white and black pixels.  Lines are encoded
525    starting with the top line and progressing towards the bottom line.  Each
526    line starts with a white run. The decoder knows that a line is finished
527    when the sum of the run lengths for that line is equal to the number of
528    columns in the image.  Numbers in range #0# to #191# are represented by a
529    single byte in range #0x00# to #0xbf#.  Numbers in range #192# to #16383#
530    are represented by a two byte sequence: the first byte, in range #0xc0# to
531    #0xff#, encodes the six most significant bits of the number, the second
532    byte encodes the remaining eight bits of the number. This scheme allows
533    for runs of length zero, which are useful when a line starts with a black
534    pixel, and when a very long run (whose length exceeds #16383#) must be
535    split into smaller runs.
536
537    @memo
538    Simple image file formats.  */
539
540//@}
541
542
543// ---------------- IMPLEMENTATION
544
545inline unsigned int
546GBitmap::rows() const
547{
548  return nrows;
549}
550
551inline unsigned int
552GBitmap::columns() const
553{
554  return ncolumns;
555}
556
557inline unsigned int 
558GBitmap::rowsize() const
559{
560  return bytes_per_row;
561}
562
563inline int
564GBitmap::get_grays() const
565{
566  return grays;
567}
568
569inline unsigned char *
570GBitmap::operator[](int row) 
571{
572  if (!bytes) 
573    uncompress();
574  if (row<0 || row>=nrows) {
575#ifndef NDEBUG
576    if (zerosize < bytes_per_row + border)
577      G_THROW( ERR_MSG("GBitmap.zero_small") );
578#endif
579    return zerobuffer + border;
580  }
581  return &bytes[row * bytes_per_row + border];
582}
583
584inline const unsigned char *
585GBitmap::operator[](int row) const
586{
587  if (!bytes) 
588    ((GBitmap*)this)->uncompress();
589  if (row<0 || row>=nrows) {
590#ifndef NDEBUG
591    if (zerosize < bytes_per_row + border)
592      G_THROW( ERR_MSG("GBitmap.zero_small") );
593#endif
594    return zerobuffer + border;
595  }
596  return &bytes[row * bytes_per_row + border];
597}
598
599inline GBitmap& 
600GBitmap::operator=(const GBitmap &ref)
601{
602  init(ref, ref.border);
603  return *this;
604}
605
606inline GMonitor *
607GBitmap::monitor() const
608{
609  return monitorptr;
610}
611
612inline void 
613GBitmap::euclidian_ratio(int a, int b, int &q, int &r)
614{
615  q = a / b;
616  r = a - b*q;
617  if (r < 0)
618  {
619    q -= 1;
620    r += b;
621  }
622}
623
624
625inline int
626GBitmap::read_run(unsigned char *&data)
627{
628  register int z=*data++;
629  return (z>=RUNOVERFLOWVALUE)?
630    ((z&~RUNOVERFLOWVALUE)<<8)|(*data++):z;
631}
632
633inline int
634GBitmap::read_run(const unsigned char *&data)
635{
636  register int z=*data++;
637  return (z>=RUNOVERFLOWVALUE)?
638    ((z&~RUNOVERFLOWVALUE)<<8)|(*data++):z;
639}
640
641inline void
642GBitmap::append_run(unsigned char *&data, int count)
643{
644  if (count < RUNOVERFLOWVALUE)
645    {
646      data[0] = count;
647      data += 1;
648    }
649  else if (count <= MAXRUNSIZE)
650    {
651      data[0] = (count>>8) + GBitmap::RUNOVERFLOWVALUE;
652      data[1] = (count & 0xff);
653      data += 2;
654    }
655  else
656    {
657      append_long_run(data, count);
658    }
659}
660
661
662inline void
663GBitmap::borrow_data(unsigned char &data,int w,int h)
664{
665  donate_data(&data,w,h);
666  bytes_data=0;
667}
668
669// ---------------- THE END
670
671#ifdef HAVE_NAMESPACES
672}
673# ifndef NOT_USING_DJVU_NAMESPACE
674using namespace DJVU;
675# endif
676#endif
677#endif
Note: See TracBrowser for help on using the repository browser.