source: trunk/libdjvu/DjVuImage.h @ 199

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

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

File size: 21.1 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: DjVuImage.h,v 1.9 2005/04/27 16:34:13 leonb Exp $
55// $Name:  $
56
57#ifndef _DJVUIMAGE_H
58#define _DJVUIMAGE_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/** @name DjVuImage.h
68
69    Files #"DjVuImage.h"# and #"DjVuImage.cpp"# implement \Ref{DjVuImage}
70    class produced as a result of decoding of DjVu files. In the previous
71    version of the library both the rendering {\bf and} decoding have been
72    handled by \Ref{DjVuImage}. This is no longer true. Now the
73    \Ref{DjVuDocument} and \Ref{DjVuFile} classes handle decoding of both
74    single page and multi page documents.
75
76    For compatibility reasons though, we still support old-style decoding
77    interface through the \Ref{DjVuImage} class for single page documents
78    {\em only}. As before, the display programs can call the decoding
79    function from a separate thread.  The user interface thread may call
80    the rendering functions at any time. Rendering will be performed using
81    the most recent data generated by the decoding thread. This multithreaded
82    capability enables progressive display of remote images.
83
84    {\bf Creating DjVu images} --- Class \Ref{DjVuImage} does not provide a
85    direct way to create a DjVu image.  The recommended procedure consists of
86    directly writing the required chunks into an \Ref{IFFByteStream} as
87    demonstrated in program \Ref{djvumake}.  Dealing with too many encoding
88    issues (such as chunk ordering and encoding quality) would indeed make the
89    decoder unnecessarily complex.
90
91    {\bf ToDo: Layered structure} --- Class #DjVuImage# currently contains an
92    unstructured collection of smart pointers to various data structures.
93    Although it simplifies the rendering routines, this choice does not
94    reflect the layered structure of DjVu images and does not leave much room
95    for evolution.  We should be able to do better.
96
97    @memo
98    Decoding DjVu and IW44 images.
99    @author
100    L\'eon Bottou <leonb@research.att.com> - initial implementation
101    Andrei Erofeev <eaf@geocities.com> - multipage support
102    @version
103    #$Id: DjVuImage.h,v 1.9 2005/04/27 16:34:13 leonb Exp $# */
104//@{
105
106
107
108#include "DjVuFile.h"
109#include "DjVuAnno.h"
110#include "GRect.h"
111
112#ifdef HAVE_NAMESPACES
113namespace DJVU {
114# ifdef NOT_DEFINED // Just to fool emacs c++ mode
115}
116#endif
117#endif
118
119/* Obsolete class included for backward compatibility. */
120
121class DjVuInterface
122{
123public:
124  virtual ~DjVuInterface();
125  virtual void notify_chunk(const char *chkid, const char *msg) = 0;
126  virtual void notify_relayout(void) = 0;
127  virtual void notify_redisplay(void) = 0;
128};
129
130
131/** Main DjVu Image data structure.  This class defines the internal
132    representation of a DjVu image.  This representation consists of a few
133    pointers referencing the various components of the DjVu image.  These
134    components are created and populated by the decoding function.  The
135    rendering functions then can use the available components to compute a
136    pixel representation of the desired segment of the DjVu image. */
137
138class DjVuImage : public DjVuPort
139{
140protected:
141  DjVuImage(void);
142public:
143  enum { NOINFO, NOTEXT=1, NOMAP=4, NOMETA=8 };
144  // CONSTRUCTION
145  /** @name Construction. */
146  //@{
147  /** Creates an empty DjVu image. After the image has been constructed,
148      it may be connected to an existing \Ref{DjVuFile} or left as is.
149
150      In the former case #DjVuImage# will look for its decoded components
151      (like #Sjbz# or #BG44#) by decending the hierarchy of \Ref{DjVuFile}s
152      starting from the one passed to \Ref{connect}().
153
154      In the latter case you can use \Ref{decode}() function to decode
155      {\bf single-page} DjVu documents in the old-style way. */
156  static GP<DjVuImage> create(void) {return new DjVuImage();}
157
158  /** Connects this #DjVuImage# to the passed \Ref{DjVuFile}. The #DjVuImage#
159      will use this \Ref{DjVuFile} to retrieve components necessary for
160      decoding. It will also connect itself to \Ref{DjVuFile} using the
161      communication mechanism provided by \Ref{DjVuPort} and \Ref{DjVuPortcaster}.
162      This will allow it to receive and relay messages and requests generated
163      by the passed \Ref{DjVuFile} and any file included into it. */
164  void          connect(const GP<DjVuFile> & file);
165
166  /** This combines the above two steps for simplier code operations. */
167  static GP<DjVuImage> create(const GP<DjVuFile> &file)
168  { const GP<DjVuImage> retval=create(); retval->connect(file); return retval; }
169     
170  //@}
171
172  // COMPONENTS
173  /** @name Components. */
174  //@{
175  /** Returns a pointer to a DjVu information component.
176      This function returns a null pointer until the decoder
177      actually processes an #"INFO"# chunk. */
178  GP<DjVuInfo>    get_info() const;
179  /** Returns a pointer to the IW44 encoded background component of a DjVu
180      image.  This function returns a null pointer until the decoder actually
181      processes an #"BG44"# chunk. */
182  GP<IW44Image>    get_bg44() const;
183  /** Returns a pointer to the raw background component of a DjVu image. The
184      background component is used for JPEG encoded backgrounds.  This
185      function returns a null pointer until the decoder actually processes an
186      #"BGjp"# chunk. */
187  GP<GPixmap>     get_bgpm() const;
188  /** Returns a pointer to the mask of the foreground component of a DjVu
189      image. The mask of the foreground component is always a JB2 image in
190      this implementation. This function returns a null pointer until the
191      decoder actually processes an #"Sjbz"# chunk. */
192  GP<JB2Image>    get_fgjb() const;
193  /** Returns a pointer to the colors of the foreground component of a DjVu
194      image. The mask of the foreground component is always a small pixmap in
195      this implementation. This function returns a null pointer until the
196      decoder actually processes an #"FG44"# chunk. */
197  GP<GPixmap>     get_fgpm() const;
198  /** Returns a pointer to a palette object containing colors for the
199      foreground components of a DjVu image.  These colors are only
200      pertinent with respect to the JB2Image. */
201  GP<DjVuPalette> get_fgbc() const;
202  /** Returns a pointer to a ByteStream containing all the annotation
203      chunks collected so far for this image.  Individual chunks can be
204      retrieved using \Ref{IFFByteStream}. Returns NULL if no chunks have been
205      collected yet. */
206  GP<ByteStream> get_anno() const;
207  /** Returns a pointer to a ByteStream containing all the hidden text.
208      Returns NULL if no chunks have been collected yet. */
209  GP<ByteStream> get_text() const;
210  /** Returns a pointer to a ByteStream containing all the metadata.
211      Returns NULL if no chunks have been collected yet. */
212  GP<ByteStream> get_meta() const;
213  //@}
214
215  // NEW STYLE DECODING
216  /** @name New style decoding. */
217  //@{
218  /** The decoder is now started when the image is created
219      by function \Ref{DjVuDocument::get_page} in \Ref{DjVuDocument}.
220      This function waits until the decoding thread terminates
221      and returns TRUE if the image has been successfully decoded. */
222  bool wait_for_complete_decode(void);
223  //@}
224 
225  // OLD STYLE DECODING
226  /** @name Old style decoding (backward compatibility). */
227  //@{
228  /** This function is here for backward compatibility. Now, with the
229      introduction of multipage DjVu documents, the decoding is handled
230      by \Ref{DjVuFile} and \Ref{DjVuDocument} classes. For single page
231      documents though, we still have this wrapper. */
232  void decode(ByteStream & str, DjVuInterface *notifier=0);
233  //@}
234 
235  // UTILITIES
236  /** @name Utilities */
237  //@{
238  /** Returns the width of the DjVu image. This function just extracts this
239      information from the DjVu information component. It returns zero if such
240      a component is not yet available. This gives rotated width if there is any
241      rotation of image. If you need real width, use #get_real_width()#.*/
242  int get_width() const;
243  /** Returns the height of the DjVu image. This function just extracts this
244      information from the DjVu information component. It returns zero if such
245      a component is not yet available. This gives rotated height if there is any
246      rotation of image. If you need real width, use #get_real_height()#.*/
247  int get_height() const;
248  /** Returns the width of the DjVu image. This function just extracts this
249      information from the DjVu information component. It returns zero if such
250      a component is not yet available.*/
251  int get_real_width() const;
252  /** Returns the height of the DjVu image. This function just extracts this
253      information from the DjVu information component. It returns zero if such
254      a component is not yet available.*/
255  int get_real_height() const;
256  /** Returns the format version the DjVu data. This function just extracts
257      this information from the DjVu information component. It returns zero if
258      such a component is not yet available.  This version number should
259      be compared with the \Ref{DjVu version constants}. */
260  int get_version() const;
261  /** Returns the resolution of the DjVu image. This information is given in
262      pixels per 2.54 cm.  Display programs can use this information to
263      determine the natural magnification to use for rendering a DjVu
264      image. */
265  int get_dpi() const;
266  /** Same as \Ref{get_dpi}() but instead of precise value returns the closest
267      "standard" one: 25, 50, 75, 100, 150, 300, 600. If dpi is greater than
268      700, it's returned as is. */
269  int get_rounded_dpi() const;
270  /** Returns the gamma coefficient of the display for which the image was
271      designed.  The rendering functions can use this information in order to
272      perform color correction for the intended display device. */
273  double get_gamma() const;
274  /** Returns a MIME type string describing the DjVu data.  This information
275      is auto-sensed by the decoder.  The MIME type can be #"image/djvu"# or
276      #"image/iw44"# depending on the data stream. */
277  GUTF8String get_mimetype() const;
278  /** Returns a short string describing the DjVu image.
279      Example: #"2500x3223 in 23.1 Kb"#. */
280  GUTF8String get_short_description() const;
281  /** Returns a verbose description of the DjVu image.  This description lists
282      all the chunks with their size and a brief comment, as shown in the
283      following example.
284      \begin{verbatim}
285      DJVU Image (2325x3156) version 17:
286       0.0 Kb   'INFO'  Page information.
287       17.3 Kb  'Sjbz'  JB2 foreground mask (2325x3156)
288       2.5 Kb   'BG44'  IW44 background (775x1052)
289       1.0 Kb   'FG44'  IW44 foreground colors (194x263)
290       3.0 Kb   'BG44'  IW44 background (part 2).
291       0.9 Kb   'BG44'  IW44 background (part 3).
292       7.1 Kb   'BG44'  IW44 background (part 4).
293      Compression ratio: 676 (31.8 Kb)
294      \end{verbatim} */
295  GUTF8String get_long_description() const;
296  /** Returns pointer to \Ref{DjVuFile} which contains this image in
297      compressed form. */
298  GP<DjVuFile> get_djvu_file(void) const;
299  /// Write out a DjVuXML object tag and map tag.
300  void writeXML(ByteStream &str_out,const GURL &doc_url, const int flags=0) const;
301  /// Write out a DjVuXML object tag and map tag.
302  void writeXML(ByteStream &str_out) const;
303  /// Get a DjVuXML object tag and map tag.
304  GUTF8String get_XML(const GURL &doc_url, const int flags=0) const;
305  /// Get a DjVuXML object tag and map tag.
306  GUTF8String get_XML(void) const;
307  //@}
308
309  // CHECKING
310  /** @name Checking for legal DjVu files. */
311  //@{
312  /** This function returns true if this object contains a well formed {\em
313      Photo DjVu Image}. Calling function #get_pixmap# on a well formed photo
314      image should always return a non zero value.  Note that function
315      #get_pixmap# works as soon as sufficient information is present,
316      regardless of the fact that the image follows the rules or not. */
317  int is_legal_photo() const;
318  /** This function returns true if this object contains a well formed {\em
319      Bilevel DjVu Image}.  Calling function #get_bitmap# on a well formed
320      bilevel image should always return a non zero value.  Note that function
321      #get_bitmap# works as soon as a foreground mask component is present,
322      regardless of the fact that the image follows the rules or not. */
323  int is_legal_bilevel() const;
324  /** This function returns true if this object contains a well formed {\em
325      Compound DjVu Image}.  Calling function #get_bitmap# or #get_pixmap# on
326      a well formed compound DjVu image should always return a non zero value.
327      Note that functions #get_bitmap# or #get_pixmap# works as soon as
328      sufficient information is present, regardless of the fact that the image
329      follows the rules or not.  */
330  int is_legal_compound() const;
331  //@}
332
333  // RENDERING
334  /** @name Rendering. 
335      All these functions take two rectangles as argument.  Conceptually,
336      these function first render the whole image into a rectangular area
337      defined by rectangle #all#.  The relation between this rectangle and the
338      image size define the appropriate scaling.  The rendering function then
339      extract the subrectangle #rect# and return the corresponding pixels as a
340      #GPixmap# or #GBitmap# object.  The #all# and #rect# should take the any
341      rotation in to effect, The actual implementation performs these
342      two operation simultaneously for obvious efficiency reasons.  The best
343      rendering speed is achieved by making sure that the size of rectangle
344      #all# and the size of the DjVu image are related by an integer ratio. */
345  //@{
346  /** Renders the image and returns a color pixel image.  Rectangles #rect#
347      and #all# are used as explained above. Color correction is performed
348      according to argument #gamma#, which represents the gamma coefficient of
349      the display device on which the pixmap will be rendered.  The default
350      value, zero, means that no color correction should be performed.
351      This function returns a null pointer if there is not enough information
352      in the DjVu image to properly render the desired image. */
353  GP<GPixmap>  get_pixmap(const GRect &rect, const GRect &all, double gamma=0) const;
354  /** Renders the mask of the foreground layer of the DjVu image.  This
355      functions is a wrapper for \Ref{JB2Image::get_bitmap}.  Argument #align#
356      specified the alignment of the rows of the returned images.  Setting
357      #align# to #4#, for instance, will adjust the bitmap border in order to
358      make sure that each row of the returned image starts on a word (four
359      byte) boundary.  This function returns a null pointer if there is not
360      enough information in the DjVu image to properly render the desired
361      image. */
362  GP<GBitmap>  get_bitmap(const GRect &rect, const GRect &all, int align = 1) const;
363  /** Renders the background layer of the DjVu image.  Rectangles #rect# and
364      #all# are used as explained above. Color correction is performed
365      according to argument #gamma#, which represents the gamma coefficient of
366      the display device on which the pixmap will be rendered.  The default
367      value, zero, means that no color correction should be performed.  This
368      function returns a null pointer if there is not enough information in
369      the DjVu image to properly render the desired image. */
370  GP<GPixmap>  get_bg_pixmap(const GRect &rect, const GRect &all, double gamma=0) const;
371  /** Renders the foreground layer of the DjVu image.  Rectangles #rect# and
372      #all# are used as explained above. Color correction is performed
373      according to argument #gamma#, which represents the gamma coefficient of
374      the display device on which the pixmap will be rendered.  The default
375      value, zero, means that no color correction should be performed.  This
376      function returns a null pointer if there is not enough information in
377      the DjVu image to properly render the desired image. */
378  GP<GPixmap>  get_fg_pixmap(const GRect &rect, const GRect &all, double gamma=0) const;
379
380
381  /** set the rotation count(angle) in counter clock wise for the image
382    values (0,1,2,3) correspond to (0,90,180,270) degree rotation*/
383  void set_rotate(int count=0);
384  /** returns the rotation count*/
385  int get_rotate() const;
386  /** returns decoded annotations in DjVuAnno object in which all hyperlinks
387      and hilighted areas are rotated as per rotation setting*/
388  GP<DjVuAnno> get_decoded_anno();
389  /** maps the given #rect# from rotated co-ordinates to unrotated document
390      co-ordinates*/
391  void map(GRect &rect) const;
392  /** unmaps the given #rect# from unrotated document co-ordinates to rotated 
393      co-ordinates*/
394  void unmap(GRect &rect) const;
395  /** maps the given #x#, #y# from rotated co-ordinates to unrotated document
396      co-ordinates*/
397  void map(int &x, int &y) const;
398  /** unmaps the given #x#, #y# from unrotated document co-ordinates to rotated 
399      co-ordinates*/
400  void unmap(int &x, int &y) const;
401
402
403
404  //@}
405
406  // Inherited from DjVuPort.
407  virtual void notify_chunk_done(const DjVuPort *, const GUTF8String &name);
408
409  // SUPERSEDED
410  GP<GPixmap>  get_pixmap(const GRect &rect, int subs=1, double gamma=0) const;
411  GP<GBitmap>  get_bitmap(const GRect &rect, int subs=1, int align = 1) const;
412  GP<GPixmap>  get_bg_pixmap(const GRect &rect, int subs=1, double gamma=0) const;
413  GP<GPixmap>  get_fg_pixmap(const GRect &rect, int subs=1, double gamma=0) const;
414private:
415  GP<DjVuFile>          file;
416  int                   rotate_count;
417  bool                  relayout_sent;
418 
419  // HELPERS
420  int stencil(GPixmap *pm, const GRect &rect, int subs, double gcorr) const;
421  GP<DjVuInfo>          get_info(const GP<DjVuFile> & file) const;
422  GP<IW44Image>         get_bg44(const GP<DjVuFile> & file) const;
423  GP<GPixmap>           get_bgpm(const GP<DjVuFile> & file) const;
424  GP<JB2Image>          get_fgjb(const GP<DjVuFile> & file) const;
425  GP<GPixmap>           get_fgpm(const GP<DjVuFile> & file) const;
426  GP<DjVuPalette>      get_fgbc(const GP<DjVuFile> & file) const;
427  void init_rotate(const DjVuInfo &info);
428};
429
430
431inline GP<DjVuFile>
432DjVuImage::get_djvu_file(void) const
433{
434   return file;
435}
436
437//@}
438
439
440
441// ----- THE END
442
443#ifdef HAVE_NAMESPACES
444}
445# ifndef NOT_USING_DJVU_NAMESPACE
446using namespace DJVU;
447# endif
448#endif
449#endif
Note: See TracBrowser for help on using the repository browser.