com.lizardtech.djvu
Class DjVuPage

java.lang.Object
  com.lizardtech.djvu.DjVuObject
      com.lizardtech.djvu.DjVuPage

All Implemented Interfaces:

DjVuInterface, java.lang.Runnable

public class DjVuPage
extends DjVuObject
implements java.lang.Runnable

DjVuPage decodes single page DjVu files. This class is appropriate for decoding a single page. If an INCL chunk is contained in the page, then either decoding must be done from a URL or createDataPool must be overloaded as in the case of the Document class. The general usage of this class is to create an instance, set any desired values, and then call decode with the relevant data. Decoding may be done either asynchronously or synchronously. By default decoding is synchronous, but this may be changed by calling setAsync(true) before calling decode. If you will be accessing this class from another thread while decoding is in progress then you should use asynchronous mode.

In synchronous mode, the decode method will not return until decoding is complete. In asynchronous mode decode returns right away as decoding continues in a separate thread. One method to track asynchronous decode progress is to register a PropertyChangeListener. Each codec will generate a signal when created. If you need to wait for a particular codec, rather than polling, use the waitForCodec method.

The updateMap method should be used for progressive rendering. The following example shows how to progressively update an image map in a separate thread.

 class Progressive extends Thread
 {
   GMap map = null;
   GRect segment;
   int subsample;
   final DjVuPage page;
 
   ... define constructors and other methods here ...
 
   public void run()
   { 
     boolean repeat;
     do
     {
       repeat=page.isDecoding();
       map=page.updateMap(map,segment,subsample); // get the map
       // We limit our wait to 200 ms, to query updates for new
       // segment or subsample values.  This also limits our wait
       // wait time when the page is updated before waitForCodec 
       // obtains a lock.
       page.waitForCodec(progressLock,200L);
     } while(repeat);
   }
 }
 

Field Summary

java.lang.Object	annoLock Lock used for accessing the annotation codec.
java.lang.Object	bgIWPixmapLock Lock used for accessing the background IWPixmap codec.
static int	DJVUVERSION This is the version of DjVu this code was written for.
static int	DJVUVERSION_TOO_NEW This is the newest version of DjVu we should attempt to decode.
static int	DJVUVERSION_TOO_OLD This is the oldest version of DjVu we can hope to decode.
java.lang.Object	doneLock Lock to signal decoding is done.
java.lang.Object	fgIWPixmapLock Lock used for accessing the foreground IWPixmap codec.
java.lang.Object	fgJb2DictLock Lock used for accessing the foreground JB2Dict codec.
java.lang.Object	fgJb2Lock Lock used for accessing the foreground JB2 codec.
java.lang.Object	fgPaletteLock Lock used for accessing the foreground Palette codec.
java.lang.Object	infoLock Lock used for accessing the info codec.
static int	MAX_PRIORITY
java.lang.String	mimetype The mimetype of this document.
static int	MIN_PRIORITY
protected java.lang.Number	progressiveCount Number incremented each time the image pixels are updated.
java.lang.Object	progressiveLock Lock to signal any image update, for progressive rendering.
protected static int	queueCount
protected static java.lang.Thread	queueThread The thread used for asynchronious decoding.
protected static java.util.Vector[]	queueVector An array of vectors listing pages which need decoding.
protected DataPool	sjbzChunk The shared dictionary data.
java.lang.Object	textLock Lock used for accessing the text codec.
protected java.net.URL	url The URL for this page.

Fields inherited from class com.lizardtech.djvu.DjVuObject

hasReferences

Constructor Summary

DjVuPage()
Creates a new DjVuPage object.

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Add a listener for property change events.
protected void	clean(java.lang.String chkid) Called after processing each chunk to log progress and optionally run the garbage collector.
static int	compute_red(int w, int h, int rw, int rh) Compute the subsample rate used.
static DjVuPage	createDjVuPage(DjVuInterface ref) Creates an instance of DjVuPage with the options interherited from the specified reference.
com.lizardtech.djvu.GPixmapScaler	createGPixmapScaler(int inw, int inh, int outw, int outh) Called to create an instance of GPixmapScaler
void	decode(DataPool pool) Decode the specified DataPool.
void	decode(java.net.URL url) Decode the specified URL.
protected void	decodeChunk(IFFInputStream iff, java.lang.String chkid, boolean isInclude) Called to decode a chunk.
protected void	decodeChunks(IFFInputStream iff, boolean isInclude) Called to decode chunks.
protected void	decodeInclude(DataPool pool) Called to decode an include chunk.
GBitmap	get_bitmap(GRect rect, int subsample, int align, java.util.Vector components) Get a bitmap for the specifed region
Codec	getAnno() Query the Anno Codec for this page.
IWPixmap	getBgIWPixmap() Query the background IWPixmap codec for this page.
GPixmap	getBgPixmap(GRect rect, int subsample, double gamma, GPixmap retval) Get the background pixmap.
GBitmap	getBitmap(GRect rect, int subsample, int align, GBitmap retval) Get the foreground bitmap.
Codec	getCodec(java.lang.Object nameLock) Query the named Codec for this page.
IWPixmap	getFgIWPixmap() Query the foreground IWPixmap for this page.
JB2Image	getFgJb2() Query the foreground Jb2 codec for this page.
JB2Dict	getFgJb2Dict() Query the foreground Jb2 Dict codec for this page.
Palette	getFgPalette() Query the foreground palette codec for this page.
GPixmap	getFgPixmap() Query the foreground pixmap for this page.
DjVuInfo	getInfo() Query the DjVuInfo for this page.
DjVuInfo	getInfoWait() Query the DjVuInfo for this page.
GMap	getMap(GRect segment, int subsample, GMap retval) Create a new map.
GPixmap	getPixmap(GRect rect, int subsample, double gamma, GPixmap retval) Get the pixmap for the desired region.
int	getPriority() Query if the asynchronous flag is set.
int	getProgressiveCount() Query the progressive count.
java.lang.String	getStatus() Query the status string.
Codec	getText() Query the hidden text Codec for this page.
boolean	hasCodec(java.lang.Object nameLock) Query if the specified codec is available.
boolean	is_legal_bilevel() Query if this is a bitonal image.
boolean	is_legal_compound() Query if this is a compound image.
boolean	is_legal_photo() Test if this is a photo image.
boolean	isAsync() Query if the asynchronous flag is set.
boolean	isColor() Query if this is a compound or photo DjVu page.
boolean	isDecoding() Query if the thread is alive and processing.
protected void	parseSjbz(java.io.InputStream input) Called to parse jb2 data.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Remove a listener for PropertyChangeEvent.
void	run() This thread processes the asynchronous queue.
void	setAsync(boolean value) Set the flag to allow or disallow asynchronous operations.
void	setPriority(int value) Set the decode priority.
void	setStatus(java.lang.String status) Set the status string and fire a property change event "status".
boolean	stencil(GPixmap pm, GRect rect, int subsample, double gamma) Create an image by stenciling the foreground onto the background.
GMap	updateMap(GMap map, GRect segment, int subsample) Update an image map based on an existing one.
Codec	waitForCodec(java.lang.Object nameLock, long maxTime) Query the named Codec for this page.

Methods inherited from class com.lizardtech.djvu.DjVuObject

checkLockTime, create, create, createSoftReference, createWeakReference, getDjVuOptions, getFromReference, invoke, setDjVuOptions

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DJVUVERSION

public static final int DJVUVERSION

This is the version of DjVu this code was written for.

See Also:

Constant Field Values

DJVUVERSION_TOO_OLD

public static final int DJVUVERSION_TOO_OLD

This is the oldest version of DjVu we can hope to decode.

See Also:

Constant Field Values

DJVUVERSION_TOO_NEW

public static final int DJVUVERSION_TOO_NEW

This is the newest version of DjVu we should attempt to decode.

See Also:

Constant Field Values

queueThread

protected static java.lang.Thread queueThread

The thread used for asynchronious decoding.

queueVector

protected static java.util.Vector[] queueVector

An array of vectors listing pages which need decoding.

queueCount

protected static int queueCount

MAX_PRIORITY

public static int MAX_PRIORITY

MIN_PRIORITY

public static int MIN_PRIORITY

annoLock

public final java.lang.Object annoLock

Lock used for accessing the annotation codec.

bgIWPixmapLock

public final java.lang.Object bgIWPixmapLock

Lock used for accessing the background IWPixmap codec.

doneLock

public final java.lang.Object doneLock

Lock to signal decoding is done.

fgIWPixmapLock

public final java.lang.Object fgIWPixmapLock

Lock used for accessing the foreground IWPixmap codec.

fgJb2DictLock

public final java.lang.Object fgJb2DictLock

Lock used for accessing the foreground JB2Dict codec.

fgJb2Lock

public final java.lang.Object fgJb2Lock

Lock used for accessing the foreground JB2 codec.

fgPaletteLock

public final java.lang.Object fgPaletteLock

Lock used for accessing the foreground Palette codec.

infoLock

public final java.lang.Object infoLock

Lock used for accessing the info codec.

progressiveLock

public final java.lang.Object progressiveLock

Lock to signal any image update, for progressive rendering.

textLock

public final java.lang.Object textLock

Lock used for accessing the text codec.

mimetype

public java.lang.String mimetype

The mimetype of this document.

sjbzChunk

protected DataPool sjbzChunk

The shared dictionary data.

progressiveCount

protected java.lang.Number progressiveCount

Number incremented each time the image pixels are updated.

url

protected java.net.URL url

The URL for this page.

Constructor Detail

DjVuPage

public DjVuPage()

Creates a new DjVuPage object.

Method Detail

setAsync

public final void setAsync(boolean value)

Set the flag to allow or disallow asynchronous operations.

Parameters:

value - true if asynchronous operations should be used.

isAsync

public final boolean isAsync()

Query if the asynchronous flag is set.

Returns:

true if the asynchronous operations are set.

setPriority

public final void setPriority(int value)

Set the decode priority. Must be called prior to decoding.

Parameters:

value - the decode priority

getPriority

public final int getPriority()

Query if the asynchronous flag is set. Must be called prior to decoding.

Returns:

true if the asynchronous operations are set.

getBgPixmap

public GPixmap getBgPixmap(GRect rect,
                           int subsample,
                           double gamma,
                           GPixmap retval)

Get the background pixmap.

Parameters:

rect - area to render

subsample - rate to subsample

gamma - color correction factor

retval - an old pixmap to reuse rather than allocating more memory

Returns:

the pixmap of interest

getBitmap

public final GBitmap getBitmap(GRect rect,
                               int subsample,
                               int align,
                               GBitmap retval)

Get the foreground bitmap.

Parameters:

rect - area of interest

subsample - rate to subsample

align - number of alignment pixels

retval - an old image to fill rather than creating a new image

Returns:

the bitmap of interest

isColor

public boolean isColor()

Query if this is a compound or photo DjVu page.

Returns:

true if color.

isDecoding

public final boolean isDecoding()

Query if the thread is alive and processing.

Returns:

true if the thread is running and still processing.

getAnno

public Codec getAnno()

Query the Anno Codec for this page.

Returns:

Annotation for this page.

getBgIWPixmap

public IWPixmap getBgIWPixmap()

Query the background IWPixmap codec for this page.

Returns:

the background IWPixmap codec for this page.

getCodec

public Codec getCodec(java.lang.Object nameLock)

Query the named Codec for this page.

Parameters:

nameLock - DOCUMENT ME!

Returns:

the named Codec for this page.

getMap

public final GMap getMap(GRect segment,
                         int subsample,
                         GMap retval)

Create a new map. The rectangle of interest and subsample rate are looked up from the old map, and stored in the new map. A null may be returned if the subsample rate is not legal or there is no valid image.

Parameters:

segment - The bounding rectangle of the subsampled segment.

subsample - The subsample rate.

retval - an old image to fill rather than creating a new image

Returns:

The newly created image map.

getFgIWPixmap

public IWPixmap getFgIWPixmap()

Query the foreground IWPixmap for this page.

Returns:

The foreground IWPixmap for this page.

getFgJb2

public JB2Image getFgJb2()

Query the foreground Jb2 codec for this page.

Returns:

the foreground Jb2 codec for this page.

getFgJb2Dict

public JB2Dict getFgJb2Dict()

Query the foreground Jb2 Dict codec for this page.

Returns:

the foreground Jb2 Dict codec for this page.

getFgPalette

public Palette getFgPalette()

Query the foreground palette codec for this page.

Returns:

foreground palette codec for this page.

getFgPixmap

public GPixmap getFgPixmap()

Query the foreground pixmap for this page.

Returns:

The foreground pixmap for this page.

getInfo

public DjVuInfo getInfo()

Query the DjVuInfo for this page.

Returns:

DjVuInfo for this page.

getInfoWait

public DjVuInfo getInfoWait()

Query the DjVuInfo for this page.

Returns:

DjVuInfo for this page.

getProgressiveCount

public int getProgressiveCount()

Query the progressive count.

Returns:

the named Codec for this page.

getText

public Codec getText()

Query the hidden text Codec for this page.

Returns:

Hidden text for this page.

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Add a listener for property change events.

Parameters:

listener - to add

compute_red

public static int compute_red(int w,
                              int h,
                              int rw,
                              int rh)

Compute the subsample rate used.

Parameters:

w - full size width

h - fill size height

rw - reduced width

rh - reduced height

Returns:

subsample rate, or 16

createDjVuPage

public static DjVuPage createDjVuPage(DjVuInterface ref)

Creates an instance of DjVuPage with the options interherited from the specified reference.

Parameters:

ref - Object to interherit DjVuOptions from.

Returns:

a new instance of DjVuPage.

createGPixmapScaler

public com.lizardtech.djvu.GPixmapScaler createGPixmapScaler(int inw,
                                                             int inh,
                                                             int outw,
                                                             int outh)

Called to create an instance of GPixmapScaler

Parameters:

inw - Source image width.

inh - Source image height.

outw - Destination image width.

outh - Destination image height.

Returns:

DOCUMENT ME!

decode

public void decode(java.net.URL url)
            throws java.io.IOException

Decode the specified URL.

Parameters:

url - URL to decode.

Throws:

java.io.IOException - if an error occures.

decode

public void decode(DataPool pool)
            throws java.io.IOException

Decode the specified DataPool.

Parameters:

pool - DataPool to decode.

Throws:

java.io.IOException - if an error occures.

java.lang.IllegalStateException - DOCUMENT ME!

hasCodec

public boolean hasCodec(java.lang.Object nameLock)

Query if the specified codec is available.

Parameters:

nameLock - DOCUMENT ME!

Returns:

true if the specified codec is available.

is_legal_photo

public boolean is_legal_photo()

Test if this is a photo image.

Returns:

true if a photo image

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Remove a listener for PropertyChangeEvent.

Parameters:

listener - to remove

updateMap

public final GMap updateMap(GMap map,
                            GRect segment,
                            int subsample)

Update an image map based on an existing one. If the existing map is null or anything has been updated, a new image map will be fetched. Otherwise, the existing image will be returned. A null may be returned if the subsample rate is not legal, or no pixels are available.

Parameters:

map - The existing map.

segment - The bounding rectangle of the subsampled segment.

subsample - The subsample rate.

Returns:

The newly created image map.

getPixmap

public GPixmap getPixmap(GRect rect,
                         int subsample,
                         double gamma,
                         GPixmap retval)

Get the pixmap for the desired region.

Parameters:

rect - area of interest

subsample - rate to subsample

gamma - color correction factor

retval - an old image to use instead of creating a new one

Returns:

the pixmap of interest

get_bitmap

public GBitmap get_bitmap(GRect rect,
                          int subsample,
                          int align,
                          java.util.Vector components)

Get a bitmap for the specifed region

Parameters:

rect - area of interest

subsample - subsample rate

align - border alignment

components - a list of components

Returns:

the newly created image

is_legal_bilevel

public boolean is_legal_bilevel()

Query if this is a bitonal image.

Returns:

true if bitonal

is_legal_compound

public boolean is_legal_compound()

Query if this is a compound image.

Returns:

true if a compound image

run

public void run()

This thread processes the asynchronous queue. Only one page is decoded at a time, with the most recient requested page processed first.

Specified by:

run in interface java.lang.Runnable

setStatus

public void setStatus(java.lang.String status)

Set the status string and fire a property change event "status".

Parameters:

status - new status string

getStatus

public java.lang.String getStatus()

Query the status string.

Returns:

the status string

stencil

public boolean stencil(GPixmap pm,
                       GRect rect,
                       int subsample,
                       double gamma)

Create an image by stenciling the foreground onto the background.

Parameters:

pm - the background image to stencil

rect - the area of the page being stenciled

subsample - the subsample rate of the area being stenciled

gamma - the color correction factor

Returns:

true if successfull

waitForCodec

public Codec waitForCodec(java.lang.Object nameLock,
                          long maxTime)

Query the named Codec for this page. If the Codec is not available, and decoding is in progress then wait for it.

Parameters:

nameLock - the name lock of the codec to wait for

maxTime - the maximum amount of time to wait for the specified codec

Returns:

the named Codec for this page.

clean

protected void clean(java.lang.String chkid)

Called after processing each chunk to log progress and optionally run the garbage collector.

Parameters:

chkid - name of chunk processed

decodeChunk

protected void decodeChunk(IFFInputStream iff,
                           java.lang.String chkid,
                           boolean isInclude)
                    throws java.io.IOException

Called to decode a chunk.

Parameters:

iff - stream being processed

chkid - name of the current chunk

isInclude - true if this is an include file stream

Throws:

java.io.IOException - if an error occurs

java.lang.IllegalStateException - if an error occurs

decodeChunks

protected void decodeChunks(IFFInputStream iff,
                            boolean isInclude)
                     throws java.io.IOException

Called to decode chunks.

Parameters:

iff - stream being processed

isInclude - true if this is an include file stream

Throws:

java.io.IOException - if an error occurs

decodeInclude

protected void decodeInclude(DataPool pool)
                      throws java.io.IOException

Called to decode an include chunk.

Parameters:

pool - chunk to be read

Throws:

java.io.IOException - if an error occurs

java.lang.IllegalStateException - if an error occurs

parseSjbz

protected void parseSjbz(java.io.InputStream input)
                  throws java.io.IOException

Called to parse jb2 data.

Parameters:

input - stream to parse

Throws:

java.io.IOException - if an error occurs

java.lang.IllegalStateException - if an error occurs