From: Ralph Giles Date: Sat, 19 Dec 2009 07:59:52 +0000 (+0000) Subject: Add rough reference documentation for the main encoding calls. X-Git-Tag: v1.3.3~114 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1028f159c2910a878687481d966224e8b3a2a974;p=platform%2Fupstream%2Flibvorbis.git Add rough reference documentation for the main encoding calls. These are a bit rough in that the main calls are declared in codec.h, and not vorbisenc.h as one might expect for the encoder. Nevertheless I felt this was helpful to those trying to use the encoder since there is no 'Programming with libvorbis' documenation at all. The error return values listed don't entirely match what the code will actually provide, but they're all good ones to check for anyway. Note of the new pages have hyperlinked function or structure names. svn path=/trunk/vorbis/; revision=16756 --- diff --git a/doc/vorbisenc/reference.html b/doc/vorbisenc/reference.html index b695f7c..9bda280 100644 --- a/doc/vorbisenc/reference.html +++ b/doc/vorbisenc/reference.html @@ -15,20 +15,46 @@

Vorbisenc API Reference

Data Structures

-Data Structures
vorbis_info
ov_ectl_ratemanage_arg
ov_ectl_ratemanage2_arg
+

-
-Encoder Setup
+

Encoder Setup

+ +

vorbis_encode_ctl()
vorbis_encode_init()
vorbis_encode_init_vbr()
vorbis_encode_setup_init()
vorbis_encode_setup_managed()
vorbis_encode_setup_vbr()
+

+ +

Encoding

+ +

+vorbis_analysis_init()
+vorbis_block_init()
+

+ +

+vorbis_analysis_headerout()
+

+ +

+vorbis_analysis_buffer()
+vorbis_analysis_wrote()
+vorbis_analysis_blockout()
+

+vorbis_analysis()
+vorbis_bitrate_addblock()
+vorbis_bitrate_flushpacket()
+

diff --git a/doc/vorbisenc/vorbis_analysis.html b/doc/vorbisenc/vorbis_analysis.html new file mode 100644 index 0000000..6b91922 --- /dev/null +++ b/doc/vorbisenc/vorbis_analysis.html @@ -0,0 +1,86 @@ + + + +libvorbisenc - function - vorbis_analysis + + + + + + + + + +

libvorbisenc documentation

libvorbisenc release 1.1 - 20091219

+ +

vorbis_analysis

+ +

declared in "vorbis/codec.h";

+ +

Once the uncompressed audio data has been divided into blocks, this +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 +directly through that structure and can be placed in the output stream. +

Otherwise, NULL should be passed for the ogg_packet pointer. In +that case, after the transform has been applied, the block must passed +to vorbis_bitrate_addblock() for further coding. This method works with +both basic and managed encoding modes, so it's recommended for new code. +

+ + + + + +


+extern int      vorbis_analysis(vorbis_block *vb,ogg_packet *op);
+

+ +

Parameters

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

+ + +

Return Values

0 for success
negative values for failure: +
- OV_EINVAL - Invalid request; a non-NULL value was passed for op when the encoder is using a bitrate managed mode.
- OV_EFAULT - Internal fault; indicates a bug or memory corruption.
- OV_EIMPL - Unimplemented; not supported by this version of the library.
+

+ +

+

+ + + + + + + + +

copyright © 2009 Xiph.Org	Ogg Vorbis team@vorbis.org
libvorbisenc documentation	libvorbisenc release 1.1 - 20091219

+ + + + + diff --git a/doc/vorbisenc/vorbis_analysis_blockout.html b/doc/vorbisenc/vorbis_analysis_blockout.html new file mode 100644 index 0000000..9f10243 --- /dev/null +++ b/doc/vorbisenc/vorbis_analysis_blockout.html @@ -0,0 +1,79 @@ + + + +libvorbisenc - function - vorbis_analysis_blockout + + + + + + + + + +

libvorbisenc documentation

libvorbisenc release 1.1 - 20091219

+ +

vorbis_analysis_blockout

+ +

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() +until it returns zero (need more data) or an negative value (error). +

+Each block returned should be passed to vorbis_analysis() for transform +and coding. +

+ + + + + +


+extern int      vorbis_analysis_blockout(vorbis_dsp_state *v,vorbis_block *vb);
+

+ +

Parameters

v: Pointer to the vorbis_dsp_state representing the encoder.
vb: Pointer to a previously initialize vorbis_block object to store the +returned data. +

+ + +

Return Values

1 for success when more blocks are available.
0 for success when this is the last block available from the current input.
negative values for failure: +
- OV_EINVAL - Invalid parameters.
- OV_EFAULT - Internal fault; indicates a bug or memory corruption.
- OV_EIMPL - Unimplemented; not supported by this version of the library.
+

+ +

+

+ + + + + + + + +

copyright © 2009 Xiph.Org	Ogg Vorbis team@vorbis.org
libvorbisenc documentation	libvorbisenc release 1.1 - 20091219

+ + + + + diff --git a/doc/vorbisenc/vorbis_analysis_buffer.html b/doc/vorbisenc/vorbis_analysis_buffer.html new file mode 100644 index 0000000..5ea9b23 --- /dev/null +++ b/doc/vorbisenc/vorbis_analysis_buffer.html @@ -0,0 +1,74 @@ + + + +libvorbisenc - function - vorbis_analysis_buffer + + + + + + + + + +

libvorbisenc documentation

libvorbisenc release 1.1 - 20091219

+ +

vorbis_analysis_buffer

+ +

declared in "vorbis/codec.h";

+ +

This fuction requests a buffer array for delivering audio to the +encoder for compression.

+ +

The Vorbis encoder expects the caller to write audio data as +non-interleaved floating point samples into its internal buffers. +

+The general procedure is to call this function with the number of samples +you have available. The encoder will arrange for that much internal storage +and return an array of buffer pointers, one for each channel of audio. +The caller must then write the audio samples into those buffers, as +float values, and finally call vorbis_analysis_wrote() to tell the +encoder the data is available for analysis. +

+ + + + + +


+extern float  **vorbis_analysis_buffer(vorbis_dsp_state *v,int vals);
+

+ +

Parameters

v: Pointer to the vorbis_dsp_state representing the encoder.
vals: Number of samples to provide in the request buffer.

+ + +

Return Values

Returns an array of floating point buffers which can accept data. +A (**float) where the first index is the channel, and the second is +the sample index.

+ +

+

+ + + + + + + + +

copyright © 2009 Xiph.Org	Ogg Vorbis team@vorbis.org
libvorbisenc documentation	libvorbisenc release 1.1 - 20091219

+ + + + + diff --git a/doc/vorbisenc/vorbis_analysis_headerout.html b/doc/vorbisenc/vorbis_analysis_headerout.html new file mode 100644 index 0000000..0c10fc5 --- /dev/null +++ b/doc/vorbisenc/vorbis_analysis_headerout.html @@ -0,0 +1,83 @@ + + + +libvorbisenc - function - vorbis_analysis_headerout + + + + + + + + + +

libvorbisenc documentation

libvorbisenc release 1.1 - 20091219

+ +

vorbis_analysis_headerout

+ +

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

+ + + + + +


+extern int      vorbis_analysis_headerout(vorbis_dsp_state *v,
+                                          vorbis_comment *vc,
+                                          ogg_packet *op,
+                                          ogg_packet *op_comm,
+                                          ogg_packet *op_code);
+

+ +

Parameters

v: Pointer to an initialized vorbis_dsp_state which holds the encoder configuration.
vc: Pointer to an initialized vorbis_comment structure which holds the metadata associated with the stream being encoded.
op: Pointer to an ogg_packet structure to be filled out with the stream identification header.
op_comm: Pointer to an ogg_packet structure to be filled out with the serialied vorbis_comment data.
op_code: Pointer to an ogg_packet structure to be filled out with the codebooks, mode descriptions, etc. which will be used encoding the stream.

+ + +

Return Values

0 for success
negative values for failure: +
- OV_EFAULT - Internal fault; indicates a bug or memory corruption.
- OV_EIMPL - Unimplemented; not supported by this version of the library.
+

+ +

+

+ + + + + + + + +

copyright © 2009 Xiph.Org	Ogg Vorbis team@vorbis.org
libvorbisenc documentation	libvorbisenc release 1.1 - 20091219

+ + + + + diff --git a/doc/vorbisenc/vorbis_analysis_init.html b/doc/vorbisenc/vorbis_analysis_init.html new file mode 100644 index 0000000..d652cf4 --- /dev/null +++ b/doc/vorbisenc/vorbis_analysis_init.html @@ -0,0 +1,66 @@ + + + +libvorbisenc - function - vorbis_analysis_init + + + + + + + + + +

libvorbisenc documentation

libvorbisenc release 1.1 - 20091219

+ +

vorbis_analysis_init

+ +

declared in "vorbis/codec.h";

+ +

This function allocates and initializes the encoder's analysis state +inside a is vorbis_dsp_state, based on the configuration in a vorbis_info +struct. +

+ + + + + +


+extern int      vorbis_analysis_init(vorbis_dsp_state *v,vorbis_info *vi);
+

+ +

Parameters

v +: Pointer to the vorbis_dsp_state structure to be initialized for encoding.
vi: File pointer to an initialized vorbis_info struct.

+ + +
Return Values
+
+
+0 for success
+
+
+ +

+
+ + + + + + + + +
copyright © 2009 Xiph.Org
Ogg Vorbis
team@vorbis.org
libvorbisenc documentation
libvorbisenc release 1.1 - 20091219
+ + + + + diff --git a/doc/vorbisenc/vorbis_analysis_wrote.html b/doc/vorbisenc/vorbis_analysis_wrote.html new file mode 100644 index 0000000..f6e5483 --- /dev/null +++ b/doc/vorbisenc/vorbis_analysis_wrote.html @@ -0,0 +1,73 @@ + + + +libvorbisenc - function - vorbis_analysis_wrote + + + + + + + + + +
libvorbisenc documentation
libvorbisenc release 1.1 - 20091219
+ +
vorbis_analysis_wrote
+ +
declared in "vorbis/codec.h";
+ +
This function tells the encoder new data is available for compression. +Call this after writing new audio into the buffer array returned by +vorbis_analysis_buffer(). +
+ + + + + +
+
+extern int vorbis_analysis_wrote(vorbis_dsp_state *v,int vals); +
+
+ +
Parameters
+
+
v
+
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().
+
+ + +
Return Values
+
+
0 for success
+
negative values for failure: +
+
OV_EINVAL - Invalid request; e.g. vals overflows the allocated space.
+
OV_EFAULT - Internal fault; indicates a bug or memory corruption.
+
OV_EIMPL - Unimplemented; not supported by this version of the library.
+
+
+
+
+ +

+
+ + + + + + + + +
copyright © 2009 Xiph.Org
Ogg Vorbis
team@vorbis.org
libvorbisenc documentation
libvorbisenc release 1.1 - 20091219
+ + + + + diff --git a/doc/vorbisenc/vorbis_bitrate_addblock.html b/doc/vorbisenc/vorbis_bitrate_addblock.html new file mode 100644 index 0000000..651751f --- /dev/null +++ b/doc/vorbisenc/vorbis_bitrate_addblock.html @@ -0,0 +1,74 @@ + + + +libvorbisenc - function - vorbis_bitrate_addblock + + + + + + + + + +
libvorbisenc documentation
libvorbisenc release 1.1 - 20091219
+ +
vorbis_bitrate_addblock
+ +
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.
+
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. +
+ + + + + +
+
+extern int vorbis_bitrate_addblock(vorbis_block *vb); +
+
+ +
Parameters
+
+
v
+
Pointer to the vorbis_block to be submitted.
+
+ + +
Return Values
+
+
0 for success.
+
negative values for failure: +
+
OV_EINVAL - Invalid parameters.
+
OV_EFAULT - Internal fault; indicates a bug or memory corruption.
+
OV_EIMPL - Unimplemented; not supported by this version of the library.
+
+
+ +
+ +

+
+ + + + + + + + +
copyright © 2009 Xiph.Org
Ogg Vorbis
team@vorbis.org
libvorbisenc documentation
libvorbisenc release 1.1 - 20091219
+ + + + + diff --git a/doc/vorbisenc/vorbis_bitrate_flushpacket.html b/doc/vorbisenc/vorbis_bitrate_flushpacket.html new file mode 100644 index 0000000..d4cccb7 --- /dev/null +++ b/doc/vorbisenc/vorbis_bitrate_flushpacket.html @@ -0,0 +1,80 @@ + + + +libvorbisenc - function - vorbis_bitrate_flushpacket + + + + + + + + + +
libvorbisenc documentation
libvorbisenc release 1.1 - 20091219
+ +
vorbis_bitrate_flushpacket
+ +
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) +or a negative value (error). +
+ +
+The data returned in the ogg_packet structure can be copied to the +final compressed output stream. +
+ + + + + +
+
+extern int vorbis_bitrate_flushpacket(vorbis_dsp_state *vd, + ogg_packet *op); +
+
+ +
Parameters
+
+
vd
+
Pointer to the vorbis_dsp_state represending the encoder.
+
op
+
Pointer to an ogg_packet to be filled out with the compressed data.
+
+ + +
Return Values
+
+
1 for success when more packets are available. +
0 for success when this is the last packet available from the current input.
+
negative values for failure: +
+
OV_EINVAL - Invalid parameters.
+
OV_EFAULT - Internal fault; indicates a bug or memory corruption.
+
OV_EIMPL - Unimplemented; not supported by this version of the library.
+
+
+ +
+ +

+
+ + + + + + + + +
copyright © 2009 Xiph.Org
Ogg Vorbis
team@vorbis.org
libvorbisenc documentation
libvorbisenc release 1.1 - 20091219
+ + + + + diff --git a/doc/vorbisenc/vorbis_block_init.html b/doc/vorbisenc/vorbis_block_init.html new file mode 100644 index 0000000..167d325 --- /dev/null +++ b/doc/vorbisenc/vorbis_block_init.html @@ -0,0 +1,66 @@ + + + +libvorbisenc - function - vorbis_block_init + + + + + + + + + +
libvorbisenc documentation
libvorbisenc release 1.1 - 20091219
+ +
vorbis_block_init
+ +
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. +
+ + + + + +
+
+extern int vorbis_block_init(vorbis_dsp_state *v, vorbis_block *vb); +
+
+ +
Parameters
+
+
v +
Pointer to an initialized vorbis_dsp_state with which to associate the new block.
+
vi
+
Pointer to a vorbis_block struct to be initialized.
+
+ + +
Return Values
+
+
+0 for success
+
+
+ +

+
+ + + + + + + + +
copyright © 2009 Xiph.Org
Ogg Vorbis
team@vorbis.org
libvorbisenc documentation
libvorbisenc release 1.1 - 20091219
+ + + + +