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 IW44IMAGE_H_
57 #define IW44IMAGE_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 IW44Image.h
67
68 Files #"IW44Image.h"# and #"IW44Image.cpp"# implement the DjVu IW44 wavelet
69 scheme for the compression of gray-level images (see class \Ref{IWBitmap})
70 and color images (see class \Ref{IWPixmap}). Programs \Ref{c44} and
71 \Ref{d44} demonstrate how to encode and decode IW44 files.
72
73 {\bf IW44 File Structure} --- The IW44 files are structured according to
74 the EA IFF85 specifications (see \Ref{IFFByteStream.h}). Gray level IW44
75 Images consist of a single #"FORM:BM44"# chunk composed of an arbitrary
76 number of #"BM44"# data chunks. Color IW44 Images consist of a single
77 #"FORM:PM44"# chunk composed of an arbitrary number of #"PM44"# data
78 chunks. The successive #"PM44"# or #"BM44"# data chunks contain
79 successive refinements of the encoded image. Each chunk contains a
80 certain number of ``data slices''. The first chunk also contains a small
81 image header. You can use program \Ref{djvuinfo} to display all this
82 structural information:
83 \begin{verbatim}
84 % djvuinfo lag.iw4
85 lag.iw4:
86 FORM:PM44 [62598]
87 PM44 [10807] #1 - 74 slices - v1.2 (color) - 684x510
88 PM44 [23583] #2 - 13 slices
89 PM44 [28178] #3 - 10 slices
90 \end{verbatim}
91
92 {\bf Embedded IW44 Images} --- These IW44 data chunks can also appear within
93 other contexts. Files representing a DjVu page, for instance, consist of
94 a single #"FORM:DJVU"# composite chunk. This composite chunk may contain
95 #"BG44"# chunks encoding the background layer and #"FG44"# chunks encoding
96 the foreground color layer. These #"BG44"# and #"FG44"# chunks are
97 actually regular IW44 data chunks with a different chunk identifier. This
98 information too can be displayed using program \Ref{djvuinfo}.
99 \begin{verbatim}
100 % djvuinfo graham1.djvu
101 graham1.djvu:
102 FORM:DJVU [32553]
103 INFO [5] 3156x2325, version 17
104 Sjbz [17692]
105 BG44 [2570] #1 - 74 slices - v1.2 (color) - 1052x775
106 FG44 [1035] #1 - 100 slices - v1.2 (color) - 263x194
107 BG44 [3048] #2 - 10 slices
108 BG44 [894] #3 - 4 slices
109 BG44 [7247] #4 - 9 slices
110 \end{verbatim}
111
112 {\bf Performance} --- The main design objective for the DjVu wavelets
113 consisted of allowing progressive rendering and smooth scrolling of large
114 images with limited memory requirements. Decoding functions process the
115 compressed data and update a memory efficient representation of the
116 wavelet coefficients. Imaging function then can quickly render an
117 arbitrary segment of the image using the available data. Both process can
118 be carried out in two threads of execution. This design plays an
119 important role in the DjVu system. We have investigated various
120 state-of-the-art wavelet compression schemes: although these schemes may
121 achieve slightly smaller file sizes, the decoding functions did not even
122 approach our requirements.
123
124 The IW44 wavelets satisfy these requirements today. It performs very well
125 for quality settings resulting in high compression ratios. It should not
126 be used for quasi-lossless compression because certain design choices
127 deliberately sacrifice the IW44 quasi-lossless performance in order to
128 improve the image quality at high compression ratios.
129
130 Little care however has been taken to make the IW44 encoder memory
131 efficient. This code uses two copies of the wavelet coefficient data
132 structure (one for the raw coefficients, one for the quantized
133 coefficients). A more sophisticated implementation should considerably
134 reduce the memory requirements.
135
136 {\bf Masking} --- When we create a DjVu image, we often know that certain
137 pixels of the background image are going to be covered by foreground
138 objects like text or drawings. The DjVu IW44 wavelet decomposition
139 routine can use an optional bilevel image named the mask. Every non zero
140 pixel in the mask means the value of the corresponding pixel in the
141 background image is irrelevant. The wavelet decomposition code will
142 replace these masked pixels by a color value whose coding cost is minimal
143 (see \URL{http://www.research.att.com/~leonb/DJVU/mask}).
144
145 {\bf ToDo} --- There are many improvements to be made. Besides better
146 quantization algorithms (such as trellis quantization and bitrate
147 allocation), we should allow for more wavelet transforms. These
148 improvements may be implemented in future version, if (and only if) they
149 can meet our decoding constraints. Future versions will probably split
150 file #"IW44Image.cpp"# which currently contains everything.
151
152 @memo
153 Wavelet encoded images.
154 @author
155 L\'eon Bottou <leonb@research.att.com>
156
157 // From: Leon Bottou, 1/31/2002
158 // Lizardtech has split the corresponding cpp file into a decoder and an encoder.
159 // Only superficial changes. The meat is mine.
160
161 */
162 //@{
163
164
165 #include "GSmartPointer.h"
166 #include "ZPCodec.h"
167
168
169 #ifdef HAVE_NAMESPACES
170 namespace DJVU {
171 # ifdef NOT_DEFINED // Just to fool emacs c++ mode
172 }
173 #endif
174 #endif
175
176 class GRect;
177 class IFFByteStream;
178 class ByteStream;
179 class GBitmap;
180 class GPixmap;
181
182
183
184 /** IW44 encoding parameters.
185 This data structure gathers the quality specification parameters needed
186 for encoding each chunk of an IW44 file. Chunk data is generated until
187 meeting either the slice target, the size target or the decibel target. */
188
189 struct DJVUAPI IWEncoderParms
190 {
191 /** Slice target. Data generation for the current chunk stops if the total
192 number of slices (in this chunk and all the previous chunks) reaches
193 value #slice#. The default value #0# has a special meaning: data will
194 be generated regardless of the number of slices in the file. */
195 int slices;
196 /** Size target. Data generation for the current chunk stops if the total
197 data size (in this chunk and all the previous chunks), expressed in
198 bytes, reaches value #size#. The default value #0# has a special
199 meaning: data will be generated regardless of the file size. */
200 int bytes;
201 /** Decibel target. Data generation for the current chunk stops if the
202 estimated luminance error, expressed in decibels, reaches value
203 #decibel#. The default value #0# has a special meaning: data will be
204 generated regardless of the estimated luminance error. Specifying value
205 #0# in fact shortcuts the computation of the estimated luminance error
206 and sensibly speeds up the encoding process. */
207 float decibels;
208 /** Constructor. Initializes the structure with the default values. */
209 IWEncoderParms(void);
210 };
211
212
213
214 /** IW44 encoded gray-level and color images. This class acts as a base for
215 images represented as a collection of IW44 wavelet coefficients. The
216 coefficients are stored in a memory efficient data structure. Member
217 function \Ref{get_bitmap} renders an arbitrary segment of the image into
218 a \Ref{GBitmap}. Member functions \Ref{decode_iff} and \Ref{encode_iff}
219 read and write DjVu IW44 files (see \Ref{IW44Image.h}). Both the copy
220 constructor and the copy operator are declared as private members. It is
221 therefore not possible to make multiple copies of instances of this
222 class. */
223
224 class DJVUAPI IW44Image : public GPEnabled
225 {
226 public:
227 /** Chrominance processing selector. The following constants may be used as
228 argument to the following \Ref{IWPixmap} constructor to indicate how the
229 chrominance information should be processed. There are four possible values:
230 \begin{description}
231 \item[CRCBnone:] The wavelet transform will discard the chrominance
232 information and only keep the luminance. The image will show in shades of gray.
233 \item[CRCBhalf:] The wavelet transform will process the chrominance at only
234 half the image resolution. This option creates smaller files but may create
235 artifacts in highly colored images.
236 \item[CRCBnormal:] The wavelet transform will process the chrominance at full
237 resolution. This is the default.
238 \item[CRCBfull:] The wavelet transform will process the chrominance at full
239 resolution. This option also disables the chrominance encoding delay
240 (see \Ref{parm_crcbdelay}) which usually reduces the bitrate associated with the
241 chrominance information.
242 \end{description} */
243 enum CRCBMode {
244 CRCBnone,
245 CRCBhalf,
246 CRCBnormal,
247 CRCBfull };
248 class Transform;
249 class Map;
250 class Block;
251 class Codec;
252 struct Alloc;
253 struct PrimaryHeader;
254 struct SecondaryHeader;
255 struct TertiaryHeader;
256 enum ImageType {
257 GRAY=false,
258 COLOR=true };
259 protected:
260 IW44Image(void);
261 public:
262 /** Null constructor. Constructs an empty IW44Image object. This object does
263 not contain anything meaningful. You must call function \Ref{init},
264 \Ref{decode_iff} or \Ref{decode_chunk} to populate the wavelet
265 coefficient data structure. You may not use \Ref{encode_iff} or
266 \Ref{encode_chunk}. */
267 static GP<IW44Image> create_decode(const ImageType itype=COLOR);
268 /** Null constructor. Constructs an empty IW44Image object. This object does
269 not contain anything meaningful. You must call function \Ref{init},
270 \Ref{decode_iff} or \Ref{decode_chunk} to populate the wavelet
271 coefficient data structure. You may then use \Ref{encode_iff}
272 and \Ref{encode_chunk}. */
273 static GP<IW44Image> create_encode(const ImageType itype=COLOR);
274 // virtual destructor
275 virtual ~IW44Image();
276 /** Initializes an IWBitmap with image #bm#. This constructor
277 performs the wavelet decomposition of image #bm# and records the
278 corresponding wavelet coefficient. Argument #mask# is an optional
279 bilevel image specifying the masked pixels (see \Ref{IW44Image.h}). */
280 static GP<IW44Image> create_encode(const GBitmap &bm, const GP<GBitmap> mask=0);
281 /** Initializes an IWPixmap with color image #bm#. This constructor
282 performs the wavelet decomposition of image #bm# and records the
283 corresponding wavelet coefficient. Argument #mask# is an optional
284 bilevel image specifying the masked pixels (see \Ref{IW44Image.h}).
285 Argument #crcbmode# specifies how the chrominance information should be
286 encoded (see \Ref{CRCBMode}). */
287 static GP<IW44Image> create_encode(const GPixmap &bm, const GP<GBitmap> mask=0, CRCBMode crcbmode=CRCBnormal);
288 // ACCESS
289 /** Returns the width of the IWBitmap image. */
290 int get_width(void) const;
291 /** Returns the height of the IWBitmap image. */
292 int get_height(void) const;
293 /** Reconstructs the complete image. The reconstructed image
294 is then returned as a GBitmap object. */
get_bitmap(void)295 virtual GP<GBitmap> get_bitmap(void) {return 0;}
296 /** Reconstructs a segment of the image at a given scale. The subsampling
297 ratio #subsample# must be a power of two between #1# and #32#. Argument
298 #rect# specifies which segment of the subsampled image should be
299 reconstructed. The reconstructed image is returned as a GBitmap object
300 whose size is equal to the size of the rectangle #rect#. */
get_bitmap(int subsample,const GRect & rect)301 virtual GP<GBitmap> get_bitmap(int subsample, const GRect &rect) {return 0;}
302 /** Reconstructs the complete image. The reconstructed image
303 is then returned as a GPixmap object. */
get_pixmap(void)304 virtual GP<GPixmap> get_pixmap(void) {return 0;}
305 /** Reconstructs a segment of the image at a given scale. The subsampling
306 ratio #subsample# must be a power of two between #1# and #32#. Argument
307 #rect# specifies which segment of the subsampled image should be
308 reconstructed. The reconstructed image is returned as a GPixmap object
309 whose size is equal to the size of the rectangle #rect#. */
get_pixmap(int subsample,const GRect & rect)310 virtual GP<GPixmap> get_pixmap(int subsample, const GRect &rect) {return 0;}
311 /** Returns the amount of memory used by the wavelet coefficients. This
312 amount of memory is expressed in bytes. */
313 virtual unsigned int get_memory_usage(void) const = 0;
314 /** Returns the filling ratio of the internal data structure. Wavelet
315 coefficients are stored in a sparse array. This function tells what
316 percentage of bins have been effectively allocated. */
317 virtual int get_percent_memory(void) const = 0;
318 // CODER
319 /** Encodes one data chunk into ByteStream #bs#. Parameter #parms# controls
320 how much data is generated. The chunk data is written to ByteStream
321 #bs# with no IFF header. Successive calls to #encode_chunk# encode
322 successive chunks. You must call #close_codec# after encoding the last
323 chunk of a file. */
324 virtual int encode_chunk(GP<ByteStream> gbs, const IWEncoderParms &parms);
325 /** Writes a gray level image into DjVu IW44 file. This function creates a
326 composite chunk (identifier #FORM:BM44# or #FORM:PM44#) composed of
327 #nchunks# chunks (identifier #BM44# or #PM44#). Data for each chunk is
328 generated with #encode_chunk# using the corresponding parameters in
329 array #parms#. */
330 virtual void encode_iff(IFFByteStream &iff, int nchunks, const IWEncoderParms *parms);
331 // DECODER
332 /** Decodes one data chunk from ByteStream #bs#. Successive calls to
333 #decode_chunk# decode successive chunks. You must call #close_codec#
334 after decoding the last chunk of a file. Note that function
335 #get_bitmap# and #decode_chunk# may be called simultaneously from two
336 execution threads. */
337 virtual int decode_chunk(GP<ByteStream> gbs) = 0;
338 /** This function enters a composite chunk (identifier #FORM:BM44#, or
339 #FORM:PM44#), and decodes a maximum of #maxchunks# data chunks
340 (identifier #BM44#). Data for each chunk is processed using the
341 function #decode_chunk#. */
342 virtual void decode_iff(IFFByteStream &iff, int maxchunks=999) = 0;
343 // MISCELLANEOUS
344 /** Resets the encoder/decoder state. The first call to #decode_chunk# or
345 #encode_chunk# initializes the coder for encoding or decoding. Function
346 #close_codec# must be called after processing the last chunk in order to
347 reset the coder and release the associated memory. */
348 virtual void close_codec(void) = 0;
349 /** Returns the chunk serial number. This function returns the serial
350 number of the last chunk encoded with #encode_chunk# or decoded with
351 #decode_chunk#. The first chunk always has serial number #1#. Successive
352 chunks have increasing serial numbers. Value #0# is returned if this
353 function is called before calling #encode_chunk# or #decode_chunk# or
354 after calling #close_codec#. */
355 virtual int get_serial(void) = 0;
356 /** Sets the chrominance delay parameter. This function can be called
357 before encoding the first color IW44 data chunk. Parameter #parm# is an
358 encoding delay which reduces the bitrate associated with the
359 chrominance information. The default chrominance encoding delay is 10. */
parm_crcbdelay(const int parm)360 virtual int parm_crcbdelay(const int parm) {return parm;}
361 /** Sets the #dbfrac# parameter. This function can be called before
362 encoding the first IW44 data chunk. Parameter #frac# modifies the
363 decibel estimation algorithm in such a way that the decibel target only
364 pertains to the average error of the fraction #frac# of the most
365 misrepresented 32x32 pixel blocks. Setting arguments #frac# to #1.0#
366 restores the normal behavior. */
367 virtual void parm_dbfrac(float frac) = 0;
368 protected:
369 // Parameter
370 float db_frac;
371 // Data
372 Map *ymap, *cbmap, *crmap;
373 int cslice;
374 int cserial;
375 int cbytes;
376 private:
377 // Disable assignment semantic
378 IW44Image(const IW44Image &ref);
379 IW44Image& operator=(const IW44Image &ref);
380 };
381
382 #ifdef IW44IMAGE_IMPLIMENTATION
383
384 /*x IW44 encoded gray-level image. This class provided functions for managing
385 a gray level image represented as a collection of IW44 wavelet
386 coefficients. The coefficients are stored in a memory efficient data
387 structure. Member function \Ref{get_bitmap} renders an arbitrary segment
388 of the image into a \Ref{GBitmap}. Member functions \Ref{decode_iff} and
389 \Ref{encode_iff} read and write DjVu IW44 files (see \Ref{IW44Image.h}).
390 Both the copy constructor and the copy operator are declared as private
391 members. It is therefore not possible to make multiple copies of instances
392 of this class. */
393
394 class DJVUAPI IWBitmap : public IW44Image
395 {
396 public:
397 friend class IW44Image;
398 class Encode;
399 protected:
400 /*x Null constructor. Constructs an empty IWBitmap object. This object does
401 not contain anything meaningful. You must call function \Ref{init},
402 \Ref{decode_iff} or \Ref{decode_chunk} to populate the wavelet
403 coefficient data structure. */
404 IWBitmap(void);
405 public:
406 //x virtual destructor
407 virtual ~IWBitmap();
408 //x ACCESS
409 /*x Reconstructs the complete image. The reconstructed image
410 is then returned as a GBitmap object. */
411 virtual GP<GBitmap> get_bitmap(void);
412 /*x Reconstructs a segment of the image at a given scale. The subsampling
413 ratio #subsample# must be a power of two between #1# and #32#. Argument
414 #rect# specifies which segment of the subsampled image should be
415 reconstructed. The reconstructed image is returned as a GBitmap object
416 whose size is equal to the size of the rectangle #rect#. */
417 virtual GP<GBitmap> get_bitmap(int subsample, const GRect &rect);
418 /*x Returns the amount of memory used by the wavelet coefficients. This
419 amount of memory is expressed in bytes. */
420 virtual unsigned int get_memory_usage(void) const;
421 /*x Returns the filling ratio of the internal data structure. Wavelet
422 coefficients are stored in a sparse array. This function tells what
423 percentage of bins have been effectively allocated. */
424 virtual int get_percent_memory(void) const;
425 // DECODER
426 /*x Decodes one data chunk from ByteStream #bs#. Successive calls to
427 #decode_chunk# decode successive chunks. You must call #close_codec#
428 after decoding the last chunk of a file. Note that function
429 #get_bitmap# and #decode_chunk# may be called simultaneously from two
430 execution threads. */
431 virtual int decode_chunk(GP<ByteStream> gbs);
432 /*x Reads a DjVu IW44 file as a gray level image. This function enters a
433 composite chunk (identifier #FORM:BM44#), and decodes a maximum of
434 #maxchunks# data chunks (identifier #BM44#). Data for each chunk is
435 processed using the function #decode_chunk#. */
436 virtual void decode_iff(IFFByteStream &iff, int maxchunks=999);
437 // MISCELLANEOUS
438 /*x Resets the encoder/decoder state. The first call to #decode_chunk# or
439 #encode_chunk# initializes the coder for encoding or decoding. Function
440 #close_codec# must be called after processing the last chunk in order to
441 reset the coder and release the associated memory. */
442 virtual void close_codec(void);
443 /*x Returns the chunk serial number. This function returns the serial
444 number of the last chunk encoded with #encode_chunk# or decoded with
445 #decode_chunk#. The first chunk always has serial number #1#. Successive
446 chunks have increasing serial numbers. Value #0# is returned if this
447 function is called before calling #encode_chunk# or #decode_chunk# or
448 after calling #close_codec#. */
449 virtual int get_serial(void);
450 /*x Sets the #dbfrac# parameter. This function can be called before
451 encoding the first IW44 data chunk. Parameter #frac# modifies the
452 decibel estimation algorithm in such a way that the decibel target only
453 pertains to the average error of the fraction #frac# of the most
454 misrepresented 32x32 pixel blocks. Setting arguments #frac# to #1.0#
455 restores the normal behavior. */
456 virtual void parm_dbfrac(float frac);
457 private:
458 Codec *ycodec;
459 };
460
461
462 /*x IW44 encoded color image. This class provided functions for managing a
463 color image represented as a collection of IW44 wavelet coefficients. The
464 coefficients are stored in a memory efficient data structure. Member
465 function \Ref{get_pixmap} renders an arbitrary segment of the image into a
466 \Ref{GPixmap}. Member functions \Ref{decode_iff} and \Ref{encode_iff}
467 read and write DjVu IW44 files (see \Ref{IW44Image.h}). Both the copy
468 constructor and the copy operator are declared as private members. It is
469 therefore not possible to make multiple copies of instances of this
470 class. */
471
472 class DJVUAPI IWPixmap : public IW44Image
473 {
474 public:
475 friend class IW44Image;
476 protected:
477 class Encode;
478 /*x Null constructor. Constructs an empty IWPixmap object. This object does
479 not contain anything meaningful. You must call function \Ref{init},
480 \Ref{decode_iff} or \Ref{decode_chunk} to populate the wavelet
481 coefficient data structure. */
482 IWPixmap(void);
483 public:
484 // virtual destructor
485 virtual ~IWPixmap();
486 // ACCESS
487 /*x Reconstructs the complete image. The reconstructed image
488 is then returned as a GPixmap object. */
489 virtual GP<GPixmap> get_pixmap(void);
490 /*x Reconstructs a segment of the image at a given scale. The subsampling
491 ratio #subsample# must be a power of two between #1# and #32#. Argument
492 #rect# specifies which segment of the subsampled image should be
493 reconstructed. The reconstructed image is returned as a GPixmap object
494 whose size is equal to the size of the rectangle #rect#. */
495 virtual GP<GPixmap> get_pixmap(int subsample, const GRect &rect);
496 /*x Returns the amount of memory used by the wavelet coefficients. This
497 amount of memory is expressed in bytes. */
498 virtual unsigned int get_memory_usage(void) const;
499 /*x Returns the filling ratio of the internal data structure. Wavelet
500 coefficients are stored in a sparse array. This function tells what
501 percentage of bins have been effectively allocated. */
502 virtual int get_percent_memory(void) const;
503 // DECODER
504 /*x Decodes one data chunk from ByteStream #bs#. Successive calls to
505 #decode_chunk# decode successive chunks. You must call #close_codec#
506 after decoding the last chunk of a file. Note that function
507 #get_bitmap# and #decode_chunk# may be called simultaneously from two
508 execution threads. */
509 virtual int decode_chunk(GP<ByteStream> gbs);
510 /*x Reads a DjVu IW44 file as a color image. This function enters a
511 composite chunk (identifier #FORM:PM44# or #FORM:BM44#), and decodes a
512 maximum of #maxchunks# data chunks (identifier #PM44# or #BM44#). Data
513 for each chunk is processed using the function #decode_chunk#. */
514 virtual void decode_iff(IFFByteStream &iff, int maxchunks=999);
515 // MISCELLANEOUS
516 /*x Resets the encoder/decoder state. The first call to #decode_chunk# or
517 #encode_chunk# initializes the coder for encoding or decoding. Function
518 #close_codec# must be called after processing the last chunk in order to
519 reset the coder and release the associated memory. */
520 virtual void close_codec(void);
521 /*x Returns the chunk serial number. This function returns the serial
522 number of the last chunk encoded with #encode_chunk# or decoded with
523 #decode_chunk#. The first chunk always has serial number #1#. Successive
524 chunks have increasing serial numbers. Value #0# is returned if this
525 function is called before calling #encode_chunk# or #decode_chunk# or
526 after calling #close_codec#. */
527 virtual int get_serial(void);
528 /*x Sets the chrominance delay parameter. This function can be called
529 before encoding the first IW44 data chunk. Parameter #parm# is an
530 encoding delay which reduces the bitrate associated with the
531 chrominance information. The default chrominance encoding delay is 10. */
532 virtual int parm_crcbdelay(const int parm);
533 /*x Sets the #dbfrac# parameter. This function can be called before
534 encoding the first IW44 data chunk. Parameter #frac# modifies the
535 decibel estimation algorithm in such a way that the decibel target only
536 pertains to the average error of the fraction #frac# of the most
537 misrepresented 32x32 pixel blocks. Setting arguments #frac# to #1.0#
538 restores the normal behavior. */
539 virtual void parm_dbfrac(float frac);
540 protected:
541 // Parameter
542 int crcb_delay;
543 int crcb_half;
544 // Data
545 private:
546 Codec *ycodec, *cbcodec, *crcodec;
547 };
548
549 /*x IW44Transform.
550 */
551 class IW44Image::Transform
552 {
553 public:
554 class Decode;
555 class Encode;
556 protected:
557 static void filter_begin(int w, int h);
558 static void filter_end(void);
559 };
560
561 struct GPixel;
562 class IW44Image::Transform::Decode : public IW44Image::Transform
563 {
564 public:
565 // WAVELET TRANSFORM
566 /*x Forward transform. */
567 static void backward(short *p, int w, int h, int rowsize, int begin, int end);
568
569 // COLOR TRANSFORM
570 /*x Converts YCbCr to RGB. */
571 static void YCbCr_to_RGB(GPixel *p, int w, int h, int rowsize);
572 };
573
574 //---------------------------------------------------------------
575 // *** Class IW44Image::Block [declaration]
576 // Represents a block of 32x32 coefficients after zigzagging and scaling
577
578
579 class IW44Image::Block // DJVU_CLASS
580 {
581 public:
582 // creating
583 Block(void);
584 // accessing scaled coefficients
585 short get(int n) const;
586 void set(int n, int val, IW44Image::Map *map);
587 // converting from liftblock
588 void read_liftblock(const short *coeff, IW44Image::Map *map);
589 void write_liftblock(short *coeff, int bmin=0, int bmax=64) const;
590 // sparse array access
591 const short* data(int n) const;
592 short* data(int n, IW44Image::Map *map);
593 void zero(int n);
594 // sparse representation
595 private:
596 short **pdata[4];
597 };
598
599 //---------------------------------------------------------------
600 // *** Class IW44Image::Map [declaration]
601 // Represents all the blocks of an image
602
603 class IW44Image::Map // DJVU_CLASS
604 {
605 public:
606 class Encode;
607
608 // construction
609 Map(int w, int h);
610 ~Map();
611 // image access
612 void image(signed char *img8, int rowsize,
613 int pixsep=1, int fast=0);
614 void image(int subsample, const GRect &rect,
615 signed char *img8, int rowsize,
616 int pixsep=1, int fast=0);
617 // array of blocks
618 IW44Image::Block *blocks;
619 // geometry
620 int iw, ih;
621 int bw, bh;
622 int nb;
623 // coefficient allocation stuff
624 short *alloc(int n);
625 short **allocp(int n);
626 IW44Image::Alloc *chain;
627 int top;
628 // statistics
629 int get_bucket_count(void) const;
630 unsigned int get_memory_usage(void) const;
631 };
632
633 //////////////////////////////////////////////////////
634 // ENCODING/DECODING WAVELET COEFFICIENTS
635 // USING HIERARCHICAL SET DIFFERENCE
636 //////////////////////////////////////////////////////
637
638
639 //-----------------------------------------------
640 // Class IW44Image::Codec [declaration+implementation]
641 // Maintains information shared while encoding or decoding
642
643 class IW44Image::Codec
644 {
645 public:
646 class Decode;
647 class Encode;
648
649 protected:
650 // Construction
651 Codec(IW44Image::Map &map);
652 public:
653 virtual ~Codec();
654 // Coding
655 int finish_code_slice(ZPCodec &zp);
656 virtual int code_slice(ZPCodec &zp) = 0;
657 // Data
658 IW44Image::Map ↦ // working map
659 // status
660 int curband; // current band
661 int curbit; // current bitplane
662 // quantization tables
663 int quant_hi[10]; // quantization for bands 1 to 9
664 int quant_lo[16]; // quantization for band 0.
665 // bucket state
666 char coeffstate[256];
667 char bucketstate[16];
668 enum { ZERO = 1, // this coeff never hits this bit
669 ACTIVE = 2, // this coeff is already active
670 NEW = 4, // this coeff is becoming active
671 UNK = 8 }; // this coeff may become active
672 // coding context
673 BitContext ctxStart [32];
674 BitContext ctxBucket[10][8];
675 BitContext ctxMant;
676 BitContext ctxRoot;
677 // helper
678 int is_null_slice(int bit, int band);
679 int decode_prepare(int fbucket, int nbucket, IW44Image::Block &blk);
680 void decode_buckets(ZPCodec &zp, int bit, int band,
681 IW44Image::Block &blk, int fbucket, int nbucket);
682 };
683
684 //////////////////////////////////////////////////////
685 // DEFINITION OF CHUNK HEADERS
686 //////////////////////////////////////////////////////
687
688
689 struct IW44Image::PrimaryHeader {
690 unsigned char serial;
691 unsigned char slices;
692 void encode(GP<ByteStream> gbs);
693 void decode(GP<ByteStream> gbs);
694 };
695
696 struct IW44Image::SecondaryHeader {
697 unsigned char major;
698 unsigned char minor;
699 void encode(GP<ByteStream> gbs);
700 void decode(GP<ByteStream> gbs);
701 };
702
703 struct IW44Image::TertiaryHeader {
704 unsigned char xhi, xlo;
705 unsigned char yhi, ylo;
706 unsigned char crcbdelay;
707 void encode(GP<ByteStream> gbs);
708 void decode(GP<ByteStream> gbs, int major=1, int minor=2);
709 };
710
711 inline const short*
data(int n)712 IW44Image::Block::data(int n) const
713 {
714 if (! pdata[n>>4])
715 return 0;
716 return pdata[n>>4][n&15];
717 }
718
719 inline short*
data(int n,IW44Image::Map * map)720 IW44Image::Block::data(int n, IW44Image::Map *map)
721 {
722 if (! pdata[n>>4])
723 pdata[n>>4] = map->allocp(16);
724 if (! pdata[n>>4][n &15])
725 pdata[n>>4][n &15] = map->alloc(16);
726 return pdata[n>>4][n&15];
727 }
728
729 inline short
get(int n)730 IW44Image::Block::get(int n) const
731 {
732 int n1 = (n>>4);
733 const short *d = data(n1);
734 if (! d)
735 return 0;
736 return d[n&15];
737 }
738
739 inline void
set(int n,int val,IW44Image::Map * map)740 IW44Image::Block::set(int n, int val, IW44Image::Map *map)
741 {
742 int n1 = (n>>4);
743 short* d = data(n1, map);
744 d[n&15] = val;
745 }
746
747 #endif /* IW44IMAGE_IMPLIMENTATION */
748
749 //@}
750
751
752 #ifdef HAVE_NAMESPACES
753 }
754 # ifndef NOT_USING_DJVU_NAMESPACE
755 using namespace DJVU;
756 # endif
757 #endif
758 #endif
759
760