Classes DjVuImage and DjVuDocument provide the preferred way to decode the contents of a DjVu file. The complete documentation is found in section DjVuDocument.h, DjVuImage.h and DjVuFile. You may also consult the source code of programs ddjvu and djvm.The DjVu Reference Library uses a two stage decoding model.
- The first stage, called decoding, consists of analyzing a DjVu or IW44 file and constructing a partially decoded representation of the image in memory. This partially decoded representation requires much less memory (typically 1-2 MBytes) than the raw image (typically 20-30 MBytes).
- The second stage, called rendering, consists of using this representation to recreate the pixels for any part of the image at any resolution. You should render on-the-fly the part of the image that you actually wish to display. This strategy minimizes both the memory and the computational requirements.
An example of decoding a multipage DjVu document is shown below. First you create DjVuDocument and call init with a proper file URL. This function starts a thread which decodes the document structure (i.e. the number of pages, the page names, etc.). You can use function wait_for_complete_init to wait for the termination of this thread and check its result. Then you can use function get_page to obtain a DjVuImage for a given page number. This function starts a thread which decodes the image data. Again you can call function wait_for_complete_decode to wait for the termination of this thread and check its result.
GP<DjVuDocument> doc = new DjVuDocument; // Decode the document structure doc->init(GOS::filename_to_url("file.djvu")); if (! doc->wait_for_complete_init()) THROW("A decoding error has occured"); // Decode a page GP<DjVuImage> dimg = doc->get_page(2); if (! dimg->wait_for_complete_decode() ) THROW("A decoding error has occured");Note: When the reference library is compiled without threads, both functions init and get_page perform their task before returning. The functions wait_for_complete_init and wait_for_complete_decode do not wait, but are still useful for testing that the operation was successful.
The sample rendering code below may be called whenever you need to redisplay part of a window showing DjVu image. Class GRect is used to represent two rectangles of interest. Rectangle full represents the range of pixels that would be occupied by the full DjVu image. This rectangle may be much larger than your computer screen. The ratio between the size of this rectangle and the size of the image implicitly defines the resolution of the displayed image. Rectangle part represents the range of pixel that you actually want to compute. This rectangle always corresponds to a visible portion of your screen. The functions get_pixmap and get_bitmap return a "smart" GP pointer to either a GPixmap or GBitmap containing the requested pixels.
GRect part = my_rectangle_to_redisplay(); GRect full = my_rectangle_for_the_full_image(); // Try rendering in color GP<GPixmap> pm = img->get_pixmap(part, full); if (pm) { my_display_in_color(pm); return; } // Try rendering in gray GP<GBitmap> bm = img->get_bitmap(part, full); if (bm) { my_display_in_grays(bm); return ; }This is the easiest way to decode and render a DjVu document stored in the filesystem. DjVuDocument accesses all the required and prints all potential error messages directly to stderr.
In a more complex environment you may want to have more control on where the data is coming from and where status and error messages are directed. By definining a subclass of DjVuPort, you can receive notifications from the decoding threads. These notifications allow you to provide data from various sources, to know about various error conditions, and to know when enough data has been decoded to display a preliminary version of the image.
Progressive display, for instance, can be implemented by letting the decoding threads run in the background. These threads wait for data and process it as soon as possible. The main thread handles the user interface and can call the rendering functions at any time while the decoding is in progress. These function will render the best possible image given the amount of data currently received (or simply return 0 if no rendering is possible yet). The DjVuPort notification mechanism allows you to determine when enough data has been received to justify redisplaying an updated version of the image.
Section GThreads.h discusses the multi-threading capabilities of the DjVu Reference Library. These features must be enabled at compile-time using the adequate option of the configuration script.
Note: In previous versions of the library, decoding was achieved by calling function decode in class DjVuImage. This method has been made obsolete by the introduction of multipage DjVu documents and INCL chunks. The decoder has to handle more than one stream of incoming data and should be able to keep track of relationships between different files in the same document. All this activity is now orchestrated by class DjVuDocument.
Alphabetic index Hierarchy of classes