lava.riff
Class RiffStreamWriter

java.lang.Object
  |
  +--lava.riff.RiffStreamWriter

public class RiffStreamWriter

extends java.lang.Object

Generates RIFF stream.

Details: RiffStreamWriter generates RIFF streams (duh!). Data is stored in a tagged, nested chunk structure, as specified by the RIFF standard. Most of the details for creating and nesting chunks are handled automatically, and the programmer needs only to call beginChunk, endChunk, and the data writing methods in order to produce a beautifully structured RIFF stream.

Constructor Summary

RiffStreamWriter(IRiffOutput raos, long length)
Writes RIFF header.

Method Summary

void	beginChunk(int tag, long length) Creates inner chunk.
void	close() Closes RIFF stream.
void	endChunk() Terminates current chunk.
protected void	finalize() Finalizes RIFF stream.
void	writeByte(byte b) Writes BYTE.
void	writeBytes(byte[] src, int offset, int amount) Writes BYTEs.
void	writeDword(int dword) Writes DWORD.
void	writeDwords(int[] src, int offset, int amount) Writes DWORDs.
void	writeTag(int tag) Writes tag.
void	writeWord(short word) Writes WORD.
void	writeWords(short[] src, int offset, int amount) Writes WORDs.

Methods inherited from class java.lang.Object

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

Constructor Detail

RiffStreamWriter

public RiffStreamWriter(IRiffOutput raos,
                        long length)
                 throws java.io.IOException

Writes RIFF header.

Details: This constructor initializes a new RiffStreamWriter so that all subsequent RIFF data is written to the given IRiffOutput (raos).

The length parameter can be used to declare the intended data length of the RIFF file's outer chunk, if that value is known. In most cases, however, because RiffStreamWriter is meant to insulate the API user from RIFF details, the length of the RIFF stream will not be known until the entire stream has been generated. Setting this parameter to 0 indicates that the data length of the outer chunk is unknown.

Because the second DWORD in a RIFF file specifies the RIFF file's data length, not knowing the data length ahead of time prevents a RiffStreamWriter from committing any data to the output stream until the entire RIFF structure has been generated. This can require significant memory resources for large streams, such as Microsoft Wave or AVI files.

Parameters:

raos - the output stream

length - the data length

Method Detail

beginChunk

public void beginChunk(int tag,
                       long length)
                throws java.io.IOException

Creates inner chunk.

Details: beginChunk creates a new inner chunk that is nested within the currently open outer chunk. The new inner chunk is tagged with tag. length indicates the length of the inner chunk's data field. If the inner chunk's data field length is unknown at the time beginChunk is called, the client should set length to 0. Setting length to 0 causes this RiffStreamWriter to wait until after the inner chunk is closed before writing the inner chunk's header.

Parameters:

tag - the inner chunk's tag

length - the predicted data length

endChunk

public void endChunk()
              throws java.io.IOException

Terminates current chunk.

Details: endChunk terminates the currently open chunk and prepares to continue writing data in the parent chunk immediately after the last byte of the closed inner chunk. If the current chunk is the RIFF file's outer chunk, then this method wraps things up and closes the RIFF output stream entirely. If the chunk being closed did not have a predeclared length, the length field in the inner chunk's header is updated before closing the chunk.

close

public void close()
           throws java.io.IOException

Closes RIFF stream.

Details: close closes all currently open, nested chunks and completes the RIFF stream, updating the headers to all chunks structures as needed. The underlying data sink is closed as well.

writeTag

public void writeTag(int tag)
              throws java.io.IOException

Writes tag.

Details: writeTag outputs the 4 bytes of tag in big endian order. This method is typically used to output the four character tags which appear in the headers to each chunk, but it may be used for other purposes as well.

Parameters:

tag - the tag

writeByte

public void writeByte(byte b)
               throws java.io.IOException

Writes BYTE.

Details: This method writes a single BYTE to the current chunk.

Parameters:

b - the BYTE

Throws:

java.io.IOException - if an I/O error occurs

writeWord

public void writeWord(short word)
               throws java.io.IOException

Writes WORD.

Details: This method writes a single WORD to the current chunk.

Parameters:

word - the WORD

Throws:

java.io.IOException - if an I/O error occurs

writeDword

public void writeDword(int dword)
                throws java.io.IOException

Writes DWORD.

Details: This method writes a single DWORD to the current chunk.

Parameters:

dword - the DWORD

Throws:

java.io.IOException - if an I/O error occurs

writeBytes

public void writeBytes(byte[] src,
                       int offset,
                       int amount)
                throws java.io.IOException

Writes BYTEs.

Details: writeBytes writes a sequence of BYTEs to the current chunk, taking them from the given byte array (src), starting with src [offset]. amount BYTEs are written.

Parameters:

src - BYTEs to write

offset - offset into array

amount - number of BYTEs to write

Throws:

java.io.IOException - if an I/O error occurs

EOFException - if reading the BYTEs extends the chunk reader beyond the chunk's end

writeWords

public void writeWords(short[] src,
                       int offset,
                       int amount)
                throws java.io.IOException

Writes WORDs.

Details: writeWords writes a sequence of WORDs to the current chunk, taking them from the given short array (src), starting with src [offset]. amount WORDs are written.

Parameters:

src - WORDs to write

offset - offset into array

amount - number of WORDs to write

Throws:

java.io.IOException - if an I/O error occurs

EOFException - if reading the WORDs extends the chunk reader beyond the chunk's end

writeDwords

public void writeDwords(int[] src,
                        int offset,
                        int amount)
                 throws java.io.IOException

Writes DWORDs.

Details: writeDwords writes a sequence of DWORDs to the current chunk, taking them from the given int array (src), starting with src [offset]. amount DWORDs are written.

Parameters:

src - DWORDs to write

offset - offset into array

amount - number of DWORDs to write

Throws:

java.io.IOException - if an I/O error occurs

EOFException - if reading the DWORDs extends the chunk reader beyond the chunk's end

finalize

protected void finalize()
                 throws java.lang.Throwable

Finalizes RIFF stream.

Details: finalize calls close.

Overrides:

finalize in class java.lang.Object