Commit 776fd4b9 authored by Ralph Giles's avatar Ralph Giles
Browse files

Cleanup pass on the vorbisenc documentation.

svn path=/trunk/vorbis/; revision=16757
parent 1028f159
......@@ -22,7 +22,7 @@ function is called on each block. It looks up the encoding mode and
dispatches the block to the forward transform provided by that mode.
</p>
<p>When using a basic encoding mode, with no bitrate management,
an ogg_packet pointer can be given, and an the coded block is returned
an ogg_packet pointer can be given, and the coded block is returned
directly through that structure and can be placed in the output stream.
</p>
<p>Otherwise, NULL should be passed for the ogg_packet pointer. In
......@@ -46,9 +46,9 @@ extern int vorbis_analysis(vorbis_block *vb,ogg_packet *op);
<dt><i>vb</i></dt>
<dd>Pointer to the vorbis_block to be encoded.</dd>
<dt><i>op</i></dt>
<dd>Optional pointer to an ogg_packet. This should normally NULL,
and the final output obtained by passing <i>vb</i> though the
vorbis_bitrate_*() interface to perform any further refinement.
<dd>Optional pointer to an ogg_packet. This is normally NULL,
and the final output is obtained by passing <i>vb</i> though the
vorbis_bitrate_*() interface to perform further refinement.
However, when not using a bitrate managed encoding mode, it
is possible to skip that step by providing an ogg_packet pointer
here, obtaining the compressed data directly.</dd>
......
......@@ -17,9 +17,9 @@
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This fuction examines the available encoder and tries to break it
into appropriate sized blocks. It should be called in a loop after
adding new data with vorbis_analysis_buffer()/vorbis_analysis_wrote()
<p>This fuction examines the available uncompressed data and tries to
break it into appropriate sized blocks. It should be called in a loop
after adding new data with vorbis_analysis_buffer()/vorbis_analysis_wrote()
until it returns zero (need more data) or an negative value (error).
</p>
<p>
......@@ -42,7 +42,7 @@ extern int vorbis_analysis_blockout(vorbis_dsp_state *v,vorbis_block *vb);
<dt><i>v</i></dt>
<dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
<dt><i>vb</i></dt>
<dd>Pointer to a previously initialize vorbis_block object to store the
<dd>Pointer to a previously initialized vorbis_block object to hold the
returned data.
</dl>
......
......@@ -47,7 +47,7 @@ extern float **vorbis_analysis_buffer(vorbis_dsp_state *v,int vals);
<dt><i>v</i></dt>
<dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
<dt><i>vals</i></dt>
<dd>Number of samples to provide in the request buffer.</dd>
<dd>Number of samples to provide space for in the returned buffer. 1024 is a reasonable choice.</dd>
</dl>
......
......@@ -18,7 +18,7 @@
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This function creates and returns the three header packets needed
to configure a decoder to accept subsequent data. I should be called
to configure a decoder to accept compressed data. I should be called
after all encoder initialization and configuration is complete. The
output packets should be placed in order at the start of the compressed
vorbis stream, prior to the first data packet.
......
......@@ -37,7 +37,7 @@ extern int vorbis_analysis_init(vorbis_dsp_state *v,vorbis_info *vi);
<dt><i>v</i</dt>
<dd>Pointer to the vorbis_dsp_state structure to be initialized for encoding.</dd>
<dt><i>vi</i></dt>
<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct describing the encoder configuration.</dd>
</dl>
......
......@@ -22,6 +22,11 @@ Call this after writing new audio into the buffer array returned by
vorbis_analysis_buffer().
</p>
<p>
Call with the <i>vals</i> parameter set to zero to signal the end
of the input data.
</p>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
......@@ -38,7 +43,9 @@ extern int vorbis_analysis_wrote(vorbis_dsp_state *v,int vals);
<dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
<dt><i>vals</i></dt>
<dd>Number of samples successfully written. This must be less than
or equal to the value passed to vorbis_analysis_buffer().</dd>
or equal to the value passed to vorbis_analysis_buffer(). A value
of zero means all input data has been provided and the compressed
stream should be finalized.</dd>
</dl>
......
......@@ -18,9 +18,9 @@
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This fuction submits a transformed block to the bitrate management
engine for final encoding. Packets are submitted and, depending on the
encoding mode, buffered and the packet boundaries adjusted and padded
to meet the target bitrate.</p>
engine for final encoding. Packets are buffered and the packet boundaries
adjusted and padded to meet the target bitrate, if any.</p>
<p>After calling vorbis_bitrate_addblock(), the passed vorbis_block
structure can be reused in another call to vorbis_analysis_blockout().
Call vorbis_bitrate_flushpacket() to obtain the final compressed data.
......@@ -38,7 +38,7 @@ extern int vorbis_bitrate_addblock(vorbis_block *vb);
<h3>Parameters</h3>
<dl>
<dt><i>v</i></dt>
<dt><i>vb</i></dt>
<dd>Pointer to the vorbis_block to be submitted.</dd>
</dl>
......
......@@ -17,9 +17,9 @@
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This function returns the next available packet from the bitrate
management engine. It should be called in a loop after any calls to
vorbis_bitrate_addblock() until it returns either 0 (more data needed)
<p>This function returns the next available completed packet from the
bitrate management engine. It should be called in a loop after any call
to vorbis_bitrate_addblock() until it returns either 0 (more data needed)
or a negative value (error).
</p>
......
......@@ -17,9 +17,9 @@
<p><i>declared in "vorbis/codec.h";</i></p>
<p>This function allocates and initializes internal state associated
with dividing the input into blocks for further analysis, stored inside
a vorbis_block structure.
<p>This function initializes a vorbis_block structure and allocates its
internal storage. A vorbis_block is used to represent a particular block
of input audio which can be analyzed and coded as a unit.
</p>
<table border=0 color=black cellspacing=0 cellpadding=7>
......@@ -36,7 +36,7 @@ extern int vorbis_block_init(vorbis_dsp_state *v, vorbis_block *vb);
<dl>
<dt><i>v</i</dt>
<dd>Pointer to an initialized vorbis_dsp_state with which to associate the new block.</dd>
<dt><i>vi</i></dt>
<dt><i>vb</i></dt>
<dd>Pointer to a vorbis_block struct to be initialized.</dd>
</dl>
......
......@@ -46,7 +46,7 @@ extern int vorbis_encode_ctl(vorbis_info *vi,int request,void *arg);
<h3>Parameters</h3>
<dl>
<dt><i>vi</i></dt>
<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd><p>
<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd><p>
<dt><i>request</i></dt>
<dd>Specifies the desired action; possible request fields are detailed below.</dd><p>
<dt><i>arg</i></dt>
......
......@@ -42,7 +42,7 @@ extern int vorbis_encode_init(<a href="vorbis_info.html">vorbis_info</a> *vi,
<h3>Parameters</h3>
<dl>
<dt><i>vi</i></dt>
<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dt><i>channels</i></dt>
<dd>The number of channels to be encoded.</dd>
<dt><i>rate</i></dt>
......
......@@ -39,7 +39,7 @@ extern int vorbis_encode_init_vbr(<a href="vorbis_info.html">vorbis_info</a> *vi
<h3>Parameters</h3>
<dl>
<dt><i>vi</i></dt>
<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dt><i>channels</i></dt>
<dd>The number of channels to be encoded.</dd>
<dt><i>rate</i></dt>
......
......@@ -48,7 +48,7 @@ extern int vorbis_encode_setup_init(<a href="vorbis_info.html">vorbis_info</a> *
<h3>Parameters</h3>
<dl>
<dt><i>vi</i></dt>
<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
</dl>
......
......@@ -56,7 +56,7 @@ extern int vorbis_encode_init(<a href="vorbis_info.html">vorbis_info</a> *vi,
<h3>Parameters</h3>
<dl>
<dt><i>vi</i></dt>
<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dt><i>channels</i></dt>
<dd>The number of channels to be encoded.</dd>
<dt><i>rate</i></dt>
......
......@@ -48,7 +48,7 @@ extern int vorbis_encode_init_vbr(<a href="vorbis_info.html">vorbis_info</a> *vi
<h3>Parameters</h3>
<dl>
<dt><i>vi</i></dt>
<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dt><i>channels</i></dt>
<dd>The number of channels to be encoded.</dd>
<dt><i>rate</i></dt>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment