source: trunk/libdjvu/DjVuImage.h @ 206

Last change on this file since 206 was 206, checked in by Eugene Romanenko, 14 years ago

DJVU plugin: djvulibre updated to version 3.5.19

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