From 776fd4b9f604be440170b6d60887f624a08a49c4 Mon Sep 17 00:00:00 2001 From: Ralph Giles Date: Sat, 19 Dec 2009 08:26:06 +0000 Subject: [PATCH] Cleanup pass on the vorbisenc documentation. svn path=/trunk/vorbis/; revision=16757 --- doc/vorbisenc/vorbis_analysis.html | 8 ++++---- doc/vorbisenc/vorbis_analysis_blockout.html | 8 ++++---- doc/vorbisenc/vorbis_analysis_buffer.html | 2 +- doc/vorbisenc/vorbis_analysis_headerout.html | 2 +- doc/vorbisenc/vorbis_analysis_init.html | 2 +- doc/vorbisenc/vorbis_analysis_wrote.html | 9 ++++++++- doc/vorbisenc/vorbis_bitrate_addblock.html | 8 ++++---- doc/vorbisenc/vorbis_bitrate_flushpacket.html | 6 +++--- doc/vorbisenc/vorbis_block_init.html | 8 ++++---- doc/vorbisenc/vorbis_encode_ctl.html | 2 +- doc/vorbisenc/vorbis_encode_init.html | 2 +- doc/vorbisenc/vorbis_encode_init_vbr.html | 2 +- doc/vorbisenc/vorbis_encode_setup_init.html | 2 +- doc/vorbisenc/vorbis_encode_setup_managed.html | 2 +- doc/vorbisenc/vorbis_encode_setup_vbr.html | 2 +- 15 files changed, 36 insertions(+), 29 deletions(-) diff --git a/doc/vorbisenc/vorbis_analysis.html b/doc/vorbisenc/vorbis_analysis.html index 6b91922..e5974cb 100644 --- a/doc/vorbisenc/vorbis_analysis.html +++ b/doc/vorbisenc/vorbis_analysis.html @@ -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.

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.

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);

vb
Pointer to the vorbis_block to be encoded.
op
-
Optional pointer to an ogg_packet. This should normally NULL, -and the final output obtained by passing vb though the -vorbis_bitrate_*() interface to perform any further refinement. +
Optional pointer to an ogg_packet. This is normally NULL, +and the final output is obtained by passing vb 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.
diff --git a/doc/vorbisenc/vorbis_analysis_blockout.html b/doc/vorbisenc/vorbis_analysis_blockout.html index 9f10243..169df08 100644 --- a/doc/vorbisenc/vorbis_analysis_blockout.html +++ b/doc/vorbisenc/vorbis_analysis_blockout.html @@ -17,9 +17,9 @@

declared in "vorbis/codec.h";

-

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() +

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).

@@ -42,7 +42,7 @@ extern int vorbis_analysis_blockout(vorbis_dsp_state *v,vorbis_block *vb);

v
Pointer to the vorbis_dsp_state representing the encoder.
vb
-
Pointer to a previously initialize vorbis_block object to store the +
Pointer to a previously initialized vorbis_block object to hold the returned data. diff --git a/doc/vorbisenc/vorbis_analysis_buffer.html b/doc/vorbisenc/vorbis_analysis_buffer.html index 5ea9b23..5e79068 100644 --- a/doc/vorbisenc/vorbis_analysis_buffer.html +++ b/doc/vorbisenc/vorbis_analysis_buffer.html @@ -47,7 +47,7 @@ extern float **vorbis_analysis_buffer(vorbis_dsp_state *v,int vals);
v
Pointer to the vorbis_dsp_state representing the encoder.
vals
-
Number of samples to provide in the request buffer.
+
Number of samples to provide space for in the returned buffer. 1024 is a reasonable choice.
diff --git a/doc/vorbisenc/vorbis_analysis_headerout.html b/doc/vorbisenc/vorbis_analysis_headerout.html index 0c10fc5..5c08656 100644 --- a/doc/vorbisenc/vorbis_analysis_headerout.html +++ b/doc/vorbisenc/vorbis_analysis_headerout.html @@ -18,7 +18,7 @@

declared in "vorbis/codec.h";

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. diff --git a/doc/vorbisenc/vorbis_analysis_init.html b/doc/vorbisenc/vorbis_analysis_init.html index d652cf4..967d13f 100644 --- a/doc/vorbisenc/vorbis_analysis_init.html +++ b/doc/vorbisenc/vorbis_analysis_init.html @@ -37,7 +37,7 @@ extern int vorbis_analysis_init(vorbis_dsp_state *v,vorbis_info *vi);

v
Pointer to the vorbis_dsp_state structure to be initialized for encoding.
vi
-
File pointer to an initialized vorbis_info struct.
+
Pointer to an initialized vorbis_info struct describing the encoder configuration.
diff --git a/doc/vorbisenc/vorbis_analysis_wrote.html b/doc/vorbisenc/vorbis_analysis_wrote.html index f6e5483..f907eb4 100644 --- a/doc/vorbisenc/vorbis_analysis_wrote.html +++ b/doc/vorbisenc/vorbis_analysis_wrote.html @@ -22,6 +22,11 @@ Call this after writing new audio into the buffer array returned by vorbis_analysis_buffer().

+

+Call with the vals parameter set to zero to signal the end +of the input data. +

+
@@ -38,7 +43,9 @@ extern int vorbis_analysis_wrote(vorbis_dsp_state *v,int vals);
Pointer to the vorbis_dsp_state representing the encoder.
vals
Number of samples successfully written. This must be less than -or equal to the value passed to vorbis_analysis_buffer().
+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. diff --git a/doc/vorbisenc/vorbis_bitrate_addblock.html b/doc/vorbisenc/vorbis_bitrate_addblock.html index 651751f..bd360d8 100644 --- a/doc/vorbisenc/vorbis_bitrate_addblock.html +++ b/doc/vorbisenc/vorbis_bitrate_addblock.html @@ -18,9 +18,9 @@

declared in "vorbis/codec.h";

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.

+engine for final encoding. Packets are buffered and the packet boundaries +adjusted and padded to meet the target bitrate, if any.

+

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);

Parameters

-
v
+
vb
Pointer to the vorbis_block to be submitted.
diff --git a/doc/vorbisenc/vorbis_bitrate_flushpacket.html b/doc/vorbisenc/vorbis_bitrate_flushpacket.html index d4cccb7..d5467eb 100644 --- a/doc/vorbisenc/vorbis_bitrate_flushpacket.html +++ b/doc/vorbisenc/vorbis_bitrate_flushpacket.html @@ -17,9 +17,9 @@

declared in "vorbis/codec.h";

-

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) +

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).

diff --git a/doc/vorbisenc/vorbis_block_init.html b/doc/vorbisenc/vorbis_block_init.html index 167d325..4053e01 100644 --- a/doc/vorbisenc/vorbis_block_init.html +++ b/doc/vorbisenc/vorbis_block_init.html @@ -17,9 +17,9 @@

declared in "vorbis/codec.h";

-

This function allocates and initializes internal state associated -with dividing the input into blocks for further analysis, stored inside -a vorbis_block structure. +

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.

@@ -36,7 +36,7 @@ extern int vorbis_block_init(vorbis_dsp_state *v, vorbis_block *vb);
v
Pointer to an initialized vorbis_dsp_state with which to associate the new block.
-
vi
+
vb
Pointer to a vorbis_block struct to be initialized.
diff --git a/doc/vorbisenc/vorbis_encode_ctl.html b/doc/vorbisenc/vorbis_encode_ctl.html index ce4c8eb..48f63a7 100644 --- a/doc/vorbisenc/vorbis_encode_ctl.html +++ b/doc/vorbisenc/vorbis_encode_ctl.html @@ -46,7 +46,7 @@ extern int vorbis_encode_ctl(vorbis_info *vi,int request,void *arg);

Parameters

vi
-
File pointer to an initialized vorbis_info struct.

+

Pointer to an initialized vorbis_info struct.

request
Specifies the desired action; possible request fields are detailed below.

arg
diff --git a/doc/vorbisenc/vorbis_encode_init.html b/doc/vorbisenc/vorbis_encode_init.html index 525b546..f279775 100644 --- a/doc/vorbisenc/vorbis_encode_init.html +++ b/doc/vorbisenc/vorbis_encode_init.html @@ -42,7 +42,7 @@ extern int vorbis_encode_init(vorbis_info *vi,

Parameters

vi
-
File pointer to an initialized vorbis_info struct.
+
Pointer to an initialized vorbis_info struct.
channels
The number of channels to be encoded.
rate
diff --git a/doc/vorbisenc/vorbis_encode_init_vbr.html b/doc/vorbisenc/vorbis_encode_init_vbr.html index 2afe8cd..92f9a23 100644 --- a/doc/vorbisenc/vorbis_encode_init_vbr.html +++ b/doc/vorbisenc/vorbis_encode_init_vbr.html @@ -39,7 +39,7 @@ extern int vorbis_encode_init_vbr(vorbis_info *vi

Parameters

vi
-
File pointer to an initialized vorbis_info struct.
+
Pointer to an initialized vorbis_info struct.
channels
The number of channels to be encoded.
rate
diff --git a/doc/vorbisenc/vorbis_encode_setup_init.html b/doc/vorbisenc/vorbis_encode_setup_init.html index 48abca1..7d18655 100644 --- a/doc/vorbisenc/vorbis_encode_setup_init.html +++ b/doc/vorbisenc/vorbis_encode_setup_init.html @@ -48,7 +48,7 @@ extern int vorbis_encode_setup_init(vorbis_info *

Parameters

vi
-
File pointer to an initialized vorbis_info struct.
+
Pointer to an initialized vorbis_info struct.
diff --git a/doc/vorbisenc/vorbis_encode_setup_managed.html b/doc/vorbisenc/vorbis_encode_setup_managed.html index c36599d..6e8d8c7 100644 --- a/doc/vorbisenc/vorbis_encode_setup_managed.html +++ b/doc/vorbisenc/vorbis_encode_setup_managed.html @@ -56,7 +56,7 @@ extern int vorbis_encode_init(vorbis_info *vi,

Parameters

vi
-
File pointer to an initialized vorbis_info struct.
+
Pointer to an initialized vorbis_info struct.
channels
The number of channels to be encoded.
rate
diff --git a/doc/vorbisenc/vorbis_encode_setup_vbr.html b/doc/vorbisenc/vorbis_encode_setup_vbr.html index 0e0b16e..6c9a698 100644 --- a/doc/vorbisenc/vorbis_encode_setup_vbr.html +++ b/doc/vorbisenc/vorbis_encode_setup_vbr.html @@ -48,7 +48,7 @@ extern int vorbis_encode_init_vbr(vorbis_info *vi

Parameters

vi
-
File pointer to an initialized vorbis_info struct.
+
Pointer to an initialized vorbis_info struct.
channels
The number of channels to be encoded.
rate
-- 2.7.4