Main Page Modules Namespace List Class Hierarchy Alphabetical List Compound List File List Namespace Members Compound Members File Members Related Pages

# codec.h

Go to the documentation of this file.

    00001 /********************************************************************
    00002  *                                                                  *
    00003  * THIS FILE IS PART OF THE OggVorbis SOFTWARE CODEC SOURCE CODE.   *
    00004  * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS     *
    00005  * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
    00006  * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING.       *
    00007  *                                                                  *
    00008  * THE OggVorbis SOURCE CODE IS (C) COPYRIGHT 1994-2001             *
    00009  * by the XIPHOPHORUS Company http://www.xiph.org/                  *
    00010
    00011  ********************************************************************
    00012
    00013  function: libvorbis codec headers
    00014  last mod: $Id: codec.h,v 1.2 2004/10/01 03:52:02 Assassin Exp $
    00015
    00016  ********************************************************************/
    00017
    00018 #ifndef _vorbis_codec_h_
    00019 #define _vorbis_codec_h_
    00020
    00021 #ifdef __cplusplus
    00022 extern "C"
    00023 {
    00024 #endif /* __cplusplus */
    00025
    00026 #include <ogg/ogg.h>
    00027
    00028 typedef struct vorbis_info{
    00029   int version;
    00030   int channels;
    00031   long rate;
    00032
    00033   /* The below bitrate declarations are *hints*.
    00034      Combinations of the three values carry the following implications:
    00035
    00036      all three set to the same value:
    00037        implies a fixed rate bitstream
    00038      only nominal set:
    00039        implies a VBR stream that averages the nominal bitrate.  No hard
    00040        upper/lower limit
    00041      upper and or lower set:
    00042        implies a VBR bitstream that obeys the bitrate limits. nominal
    00043        may also be set to give a nominal rate.
    00044      none set:
    00045        the coder does not care to speculate.
    00046   */
    00047
    00048   long bitrate_upper;
    00049   long bitrate_nominal;
    00050   long bitrate_lower;
    00051   long bitrate_window;
    00052
    00053   void *codec_setup;
    00054 } vorbis_info;
    00055
    00056 /* vorbis_dsp_state buffers the current vorbis audio
    00057    analysis/synthesis state.  The DSP state belongs to a specific
    00058    logical bitstream ****************************************************/
    00059 typedef struct vorbis_dsp_state{
    00060   int analysisp;
    00061   vorbis_info *vi;
    00062
    00063   float **pcm;
    00064   float **pcmret;
    00065   int      pcm_storage;
    00066   int      pcm_current;
    00067   int      pcm_returned;
    00068
    00069   int  preextrapolate;
    00070   int  eofflag;
    00071
    00072   long lW;
    00073   long W;
    00074   long nW;
    00075   long centerW;
    00076
    00077   ogg_int64_t granulepos;
    00078   ogg_int64_t sequence;
    00079
    00080   ogg_int64_t glue_bits;
    00081   ogg_int64_t time_bits;
    00082   ogg_int64_t floor_bits;
    00083   ogg_int64_t res_bits;
    00084
    00085   void       *backend_state;
    00086 } vorbis_dsp_state;
    00087
    00088 typedef struct vorbis_block{
    00089   /* necessary stream state for linking to the framing abstraction */
    00090   float  **pcm;       /* this is a pointer into local storage */
    00091   oggpack_buffer opb;
    00092
    00093   long  lW;
    00094   long  W;
    00095   long  nW;
    00096   int   pcmend;
    00097   int   mode;
    00098
    00099   int         eofflag;
    00100   ogg_int64_t granulepos;
    00101   ogg_int64_t sequence;
    00102   vorbis_dsp_state *vd; /* For read-only access of configuration */
    00103
    00104   /* local storage to avoid remallocing; it's up to the mapping to
    00105      structure it */
    00106   void               *localstore;
    00107   long                localtop;
    00108   long                localalloc;
    00109   long                totaluse;
    00110   struct alloc_chain *reap;
    00111
    00112   /* bitmetrics for the frame */
    00113   long glue_bits;
    00114   long time_bits;
    00115   long floor_bits;
    00116   long res_bits;
    00117
    00118   void *internal;
    00119
    00120 } vorbis_block;
    00121
    00122 /* vorbis_block is a single block of data to be processed as part of
    00123 the analysis/synthesis stream; it belongs to a specific logical
    00124 bitstream, but is independant from other vorbis_blocks belonging to
    00125 that logical bitstream. *************************************************/
    00126
    00127 struct alloc_chain{
    00128   void *ptr;
    00129   struct alloc_chain *next;
    00130 };
    00131
    00132 /* vorbis_info contains all the setup information specific to the
    00133    specific compression/decompression mode in progress (eg,
    00134    psychoacoustic settings, channel setup, options, codebook
    00135    etc). vorbis_info and substructures are in backends.h.
    00136 *********************************************************************/
    00137
    00138 /* the comments are not part of vorbis_info so that vorbis_info can be
    00139    static storage */
    00140 typedef struct vorbis_comment{
    00141   /* unlimited user comment fields.  libvorbis writes 'libvorbis'
    00142      whatever vendor is set to in encode */
    00143   char **user_comments;
    00144   int   *comment_lengths;
    00145   int    comments;
    00146   char  *vendor;
    00147
    00148 } vorbis_comment;
    00149
    00150
    00151 /* libvorbis encodes in two abstraction layers; first we perform DSP
    00152    and produce a packet (see docs/analysis.txt).  The packet is then
    00153    coded into a framed OggSquish bitstream by the second layer (see
    00154    docs/framing.txt).  Decode is the reverse process; we sync/frame
    00155    the bitstream and extract individual packets, then decode the
    00156    packet back into PCM audio.
    00157
    00158    The extra framing/packetizing is used in streaming formats, such as
    00159    files.  Over the net (such as with UDP), the framing and
    00160    packetization aren't necessary as they're provided by the transport
    00161    and the streaming layer is not used */
    00162
    00163 /* Vorbis PRIMITIVES: general ***************************************/
    00164
    00165 extern void     vorbis_info_init(vorbis_info *vi);
    00166 extern void     vorbis_info_clear(vorbis_info *vi);
    00167 extern void     vorbis_comment_init(vorbis_comment *vc);
    00168 extern void     vorbis_comment_add(vorbis_comment *vc, char *comment);
    00169 extern void     vorbis_comment_add_tag(vorbis_comment *vc,
    00170                        char *tag, char *contents);
    00171 extern char    *vorbis_comment_query(vorbis_comment *vc, char *tag, int count);
    00172 extern int      vorbis_comment_query_count(vorbis_comment *vc, char *tag);
    00173 extern void     vorbis_comment_clear(vorbis_comment *vc);
    00174
    00175 extern int      vorbis_block_init(vorbis_dsp_state *v, vorbis_block *vb);
    00176 extern int      vorbis_block_clear(vorbis_block *vb);
    00177 extern void     vorbis_dsp_clear(vorbis_dsp_state *v);
    00178
    00179 /* Vorbis PRIMITIVES: analysis/DSP layer ****************************/
    00180
    00181 extern int      vorbis_analysis_init(vorbis_dsp_state *v,vorbis_info *vi);
    00182 extern int      vorbis_commentheader_out(vorbis_comment *vc, ogg_packet *op);
    00183 extern int      vorbis_analysis_headerout(vorbis_dsp_state *v,
    00184                       vorbis_comment *vc,
    00185                       ogg_packet *op,
    00186                       ogg_packet *op_comm,
    00187                       ogg_packet *op_code);
    00188 extern float  **vorbis_analysis_buffer(vorbis_dsp_state *v,int vals);
    00189 extern int      vorbis_analysis_wrote(vorbis_dsp_state *v,int vals);
    00190 extern int      vorbis_analysis_blockout(vorbis_dsp_state *v,vorbis_block *vb);
    00191 extern int      vorbis_analysis(vorbis_block *vb,ogg_packet *op);
    00192
    00193 /* Vorbis PRIMITIVES: synthesis layer *******************************/
    00194 extern int      vorbis_synthesis_headerin(vorbis_info *vi,vorbis_comment *vc,
    00195                       ogg_packet *op);
    00196
    00197 extern int      vorbis_synthesis_init(vorbis_dsp_state *v,vorbis_info *vi);
    00198 extern int      vorbis_synthesis(vorbis_block *vb,ogg_packet *op);
    00199 extern int      vorbis_synthesis_blockin(vorbis_dsp_state *v,vorbis_block *vb);
    00200 extern int      vorbis_synthesis_pcmout(vorbis_dsp_state *v,float ***pcm);
    00201 extern int      vorbis_synthesis_read(vorbis_dsp_state *v,int samples);
    00202 extern long     vorbis_packet_blocksize(vorbis_info *vi,ogg_packet *op);
    00203
    00204 /* Vorbis ERRORS and return codes ***********************************/
    00205
    00206 #define OV_FALSE      -1
    00207 #define OV_EOF        -2
    00208 #define OV_HOLE       -3
    00209
    00210 #define OV_EREAD      -128
    00211 #define OV_EFAULT     -129
    00212 #define OV_EIMPL      -130
    00213 #define OV_EINVAL     -131
    00214 #define OV_ENOTVORBIS -132
    00215 #define OV_EBADHEADER -133
    00216 #define OV_EVERSION   -134
    00217 #define OV_ENOTAUDIO  -135
    00218 #define OV_EBADPACKET -136
    00219 #define OV_EBADLINK   -137
    00220 #define OV_ENOSEEK    -138
    00221
    00222 #ifdef __cplusplus
    00223 }
    00224 #endif /* __cplusplus */
    00225
    00226 #endif
    00227