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 * */
044package jj2000.j2k.codestream.writer;
045
046import 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 * */
070public 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,boolean sim,
148                                        boolean sop, boolean eph)
149        throws IOException;
150
151    /**
152     * Writes a packet body to the bit stream and returns the number of bytes
153     * used by this body .If in simulation mode then no data is written to the
154     * bit stream but the number of bytes is calculated. This can be used for
155     * iterative rate allocation.
156     *
157     * <P>If the length of the data that is to be written to the bit stream is
158     * more than the space left (as returned by getMaxAvailableBytes()) only
159     * the data that does not exceed the allowed length is written, the rest
160     * is discarded. However the value returned by the method is the total
161     * length of the packet body , as if all of it was written to the bit
162     * stream.
163     *
164     * @param body The packet body data.
165     *
166     * @param blen The number of bytes in the packet body.
167     *
168     * @param sim Simulation mode flag. If true nothing is written to the bit
169     * stream, but the number of bytes that would be written is returned.
170     *
171     * @param roiInPkt Whether or not there is ROI information in this packet
172     *
173     * @param roiLen Number of byte to read in packet body to get all the ROI
174     * information
175     *
176     * @return The number of bytes spent by the packet body.
177     *
178     * @exception IOException If an I/O error occurs while writing to
179     * the output stream.
180     *
181     * @see #commitBitstreamHeader
182     * */
183    public abstract int writePacketBody(byte body[],int blen,boolean sim,
184                                        boolean roiInPkt, int roiLen)
185        throws IOException;
186
187
188    /**
189     * Closes the underlying resource (file, stream, network connection,
190     * etc.). After a CodestreamWriter is closed no more data can be written
191     * to it.
192     *
193     * @exception IOException If an I/O error occurs while closing the
194     * resource.
195     * */
196    public abstract void close() throws IOException;
197
198    /**
199     * Writes the header data to the bit stream, if it has not been already
200     * done. In some implementations this method can be called only once, and
201     * an IllegalArgumentException is thrown if called more than once.
202     *
203     * @exception IOException If an I/O error occurs while writing the data.
204     *
205     * @exception IllegalArgumentException If this method has already been
206     * called.
207     * */
208    public abstract void commitBitstreamHeader(HeaderEncoder he)
209        throws IOException;
210
211    /**
212     * Gives the offset of the end of last packet containing ROI information
213     *
214     * @return End of last ROI packet
215     * */
216    public abstract int getOffLastROIPkt();
217}