001: /*
002: * $RCSfile: CodestreamWriter.java,v $
003: * $Revision: 1.1 $
004: * $Date: 2005/02/11 05:02:02 $
005: * $State: Exp $
006: *
007: * Class: CodestreamWriter
008: *
009: * Description: Interface for writing bit streams
010: *
011: *
012: *
013: * COPYRIGHT:
014: *
015: * This software module was originally developed by Raphaël Grosbois and
016: * Diego Santa Cruz (Swiss Federal Institute of Technology-EPFL); Joel
017: * Askelöf (Ericsson Radio Systems AB); and Bertrand Berthelot, David
018: * Bouchard, Félix Henry, Gerard Mozelle and Patrice Onno (Canon Research
019: * Centre France S.A) in the course of development of the JPEG2000
020: * standard as specified by ISO/IEC 15444 (JPEG 2000 Standard). This
021: * software module is an implementation of a part of the JPEG 2000
022: * Standard. Swiss Federal Institute of Technology-EPFL, Ericsson Radio
023: * Systems AB and Canon Research Centre France S.A (collectively JJ2000
024: * Partners) agree not to assert against ISO/IEC and users of the JPEG
025: * 2000 Standard (Users) any of their rights under the copyright, not
026: * including other intellectual property rights, for this software module
027: * with respect to the usage by ISO/IEC and Users of this software module
028: * or modifications thereof for use in hardware or software products
029: * claiming conformance to the JPEG 2000 Standard. Those intending to use
030: * this software module in hardware or software products are advised that
031: * their use may infringe existing patents. The original developers of
032: * this software module, JJ2000 Partners and ISO/IEC assume no liability
033: * for use of this software module or modifications thereof. No license
034: * or right to this software module is granted for non JPEG 2000 Standard
035: * conforming products. JJ2000 Partners have full right to use this
036: * software module for his/her own purpose, assign or donate this
037: * software module to any third party and to inhibit third parties from
038: * using this software module for non JPEG 2000 Standard conforming
039: * products. This copyright notice must be included in all copies or
040: * derivative works of this software module.
041: *
042: * Copyright (c) 1999/2000 JJ2000 Partners.
043: * */
044: package jj2000.j2k.codestream.writer;
045:
046: import java.io.*;
047:
048: /**
049: * This is the abstract class for writing to a bit stream. Data is
050: * written in packets, each packet having a head and a body. The
051: * bit stream always has a maximum number of bytes that can be written
052: * to it. After that many number of bytes no more data is written to
053: * the bit stream but the number of bytes is counted so that the value
054: * returned by getMaxAvailableBytes() is negative. If the number of
055: * bytes is unlimited a ridicoulosly large value, such as
056: * Integer.MAX_VALUE, is equivalent.
057: *
058: * <P>Data may be written to the bit stream in sumulation mode. When in
059: * simulation mode no data is written to the bit stream but the
060: * resulting number of bytes is calculated and returned (although it
061: * is not accounted in the bit stream). This can be used in rate
062: * control loops.
063: *
064: * <P>Implementing classes should write the header of the bit stream
065: * before writing any packets. The bit stream header should be written
066: * with the aid of the HeaderEncoder class.
067: *
068: * @see HeaderEncoder
069: * */
070: public abstract class CodestreamWriter {
071:
072: /** The number of bytes already written to the bit stream */
073: protected int ndata = 0;
074:
075: /** The maximum number of bytes that can be written to the
076: * bit stream */
077: protected int maxBytes;
078:
079: /**
080: * Allocates this object and initializes the maximum numner of
081: * bytes.
082: *
083: * @param mb The maximum number of bytes that can be written to
084: * the bit stream.
085: * */
086: protected CodestreamWriter(int mb) {
087: maxBytes = mb;
088: }
089:
090: /**
091: * Returns the number of bytes remaining available in the bit stream. This
092: * is the maximum allowed number of bytes minus the number of bytes that
093: * have already been written to the bit stream. If more bytes have been
094: * written to the bit stream than the maximum number of allowed bytes,
095: * then a negative value is returned.
096: *
097: * @return The number of bytes remaining available in the bit stream.
098: * */
099: public abstract int getMaxAvailableBytes();
100:
101: /**
102: * Returns the current length of the entire bit stream.
103: *
104: * @return the current length of the bit stream
105: * */
106: public abstract int getLength();
107:
108: /**
109: * Writes a packet head to the bit stream and returns the number of bytes
110: * used by this header. It returns the total number of bytes that the
111: * packet head takes in the bit stream. If in simulation mode then no data
112: * is written to the bit stream but the number of bytes is
113: * calculated. This can be used for iterative rate allocation.
114: *
115: * <P>If the length of the data that is to be written to the bit stream is
116: * more than the space left (as returned by getMaxAvailableBytes()) only
117: * the data that does not exceed the allowed length is written, the rest
118: * is discarded. However the value returned by the method is the total
119: * length of the packet, as if all of it was written to the bit stream.
120: *
121: * <P>If the bit stream header has not been commited yet and 'sim' is
122: * false, then the bit stream header is automatically commited (see
123: * commitBitstreamHeader() method) before writting the packet.
124: *
125: * @param head The packet head data.
126: *
127: * @param hlen The number of bytes in the packet head.
128: *
129: * @param sim Simulation mode flag. If true nothing is written to the bit
130: * stream, but the number of bytes that would be written is returned.
131: *
132: * @param sop Start of packet header marker flag. This flag indicates
133: * whether or not SOP markers should be written. If true, SOP markers
134: * should be written, if false, they should not.
135: *
136: * @param eph End of Packet Header marker flag. This flag indicates
137: * whether or not EPH markers should be written. If true, EPH markers
138: * should be written, if false, they should not.
139: *
140: * @return The number of bytes spent by the packet head.
141: *
142: * @exception IOException If an I/O error occurs while writing to the
143: * output stream.
144: *
145: * @see #commitBitstreamHeader
146: * */
147: public abstract int writePacketHead(byte head[], int hlen,
148: boolean sim, boolean sop, boolean eph) throws IOException;
149:
150: /**
151: * Writes a packet body to the bit stream and returns the number of bytes
152: * used by this body .If in simulation mode then no data is written to the
153: * bit stream but the number of bytes is calculated. This can be used for
154: * iterative rate allocation.
155: *
156: * <P>If the length of the data that is to be written to the bit stream is
157: * more than the space left (as returned by getMaxAvailableBytes()) only
158: * the data that does not exceed the allowed length is written, the rest
159: * is discarded. However the value returned by the method is the total
160: * length of the packet body , as if all of it was written to the bit
161: * stream.
162: *
163: * @param body The packet body data.
164: *
165: * @param blen The number of bytes in the packet body.
166: *
167: * @param sim Simulation mode flag. If true nothing is written to the bit
168: * stream, but the number of bytes that would be written is returned.
169: *
170: * @param roiInPkt Whether or not there is ROI information in this packet
171: *
172: * @param roiLen Number of byte to read in packet body to get all the ROI
173: * information
174: *
175: * @return The number of bytes spent by the packet body.
176: *
177: * @exception IOException If an I/O error occurs while writing to
178: * the output stream.
179: *
180: * @see #commitBitstreamHeader
181: * */
182: public abstract int writePacketBody(byte body[], int blen,
183: boolean sim, boolean roiInPkt, int roiLen)
184: throws IOException;
185:
186: /**
187: * Closes the underlying resource (file, stream, network connection,
188: * etc.). After a CodestreamWriter is closed no more data can be written
189: * to it.
190: *
191: * @exception IOException If an I/O error occurs while closing the
192: * resource.
193: * */
194: public abstract void close() throws IOException;
195:
196: /**
197: * Writes the header data to the bit stream, if it has not been already
198: * done. In some implementations this method can be called only once, and
199: * an IllegalArgumentException is thrown if called more than once.
200: *
201: * @exception IOException If an I/O error occurs while writing the data.
202: *
203: * @exception IllegalArgumentException If this method has already been
204: * called.
205: * */
206: public abstract void commitBitstreamHeader(HeaderEncoder he)
207: throws IOException;
208:
209: /**
210: * Gives the offset of the end of last packet containing ROI information
211: *
212: * @return End of last ROI packet
213: * */
214: public abstract int getOffLastROIPkt();
215: }
|