source: trunk/libdjvu/GBitmap.h @ 17

Last change on this file since 17 was 17, checked in by Eugene Romanenko, 15 years ago

update makefiles, remove absolute paths, update djvulibre to version 3.5.17

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