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