More Doxygen doc
authorjmvalin <jmvalin@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Thu, 12 Sep 2002 03:31:08 +0000 (03:31 +0000)
committerjmvalin <jmvalin@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Thu, 12 Sep 2002 03:31:08 +0000 (03:31 +0000)
git-svn-id: http://svn.xiph.org/trunk/speex@3901 0101bb08-14d6-0310-b084-bc0e0c8e3800

libspeex/misc.h
libspeex/modes.h
libspeex/nb_celp.h
libspeex/sb_celp.h
libspeex/speex.h
libspeex/speex_bits.h
libspeex/speex_header.h

index 81cbb6f..9bce89d 100644 (file)
@@ -1,7 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin 
-   File: mics.h
-   Various utility routines for Speex
-
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
+   @file misc.h
+   @brief Various compatibility routines for Speex
+*/
+/*
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
@@ -31,8 +33,13 @@ unsigned int le_int(unsigned int i);
 unsigned short be_short(unsigned short s);
 unsigned short le_short(unsigned short s);
 
+/**< Speex wrapper for calloc. To do your own dynamic allocation, all you need to do is replace this function and speex_free */
 void *speex_alloc (int size);
+
+/**< Speex wrapper for calloc. To do your own dynamic allocation, all you need to do is replace this function and speex_alloc */
 void speex_free (void *ptr);
+
+/** Speex wrapper for mem_move */
 void *speex_move (void *dest, void *src, int n);
 
 #endif
index 12c1103..ea608f3 100644 (file)
@@ -1,7 +1,9 @@
-/** Copyright (C) 2002 Jean-Marc Valin
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
    @file modes.h
    @brief Describes the different modes of the codec
-
+*/
+/*
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
@@ -67,19 +69,21 @@ typedef struct SpeexSubmode {
    lsp_unquant_func  lsp_unquant; /**< LSP unquantization function */
 
    /*Lont-term predictor functions*/
-   ltp_quant_func    ltp_quant;
-   ltp_unquant_func  ltp_unquant;
-   void             *ltp_params;
+   ltp_quant_func    ltp_quant; /**< Long-term predictor (pitch) quantizer */
+   ltp_unquant_func  ltp_unquant; /**< Long-term predictor (pitch) un-quantizer */
+   void             *ltp_params; /**< Pitch parameters (options) */
 
    /*Quantization of innovation*/
-   innovation_quant_func innovation_quant;
-   innovation_unquant_func innovation_unquant;
-   void             *innovation_params;
+   innovation_quant_func innovation_quant; /**< Innovation quantization */
+   innovation_unquant_func innovation_unquant; /**< Innovation un-quantization */
+   void             *innovation_params; /**< Innovation quantization parameters*/
 
    /*Synthesis filter enhancement*/
-   float lpc_enh_k1, lpc_enh_k2, comb_gain;
+   float             lpc_enh_k1; /**< Enhancer constant */
+   float             lpc_enh_k2; /**< Enhancer constant */
+   float             comb_gain;  /**< Gain of enhancer comb filter */
 
-   int               bits_per_frame;
+   int               bits_per_frame; /**< Number of bits per frame after encoding*/
 } SpeexSubmode;
 
 /** Struct defining the encoding/decoding mode*/
index 473c38a..0883119 100644 (file)
@@ -1,7 +1,9 @@
-/** Copyright (C) 2002 Jean-Marc Valin
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
     @file nb_celp.h
     @brief Narrowband CELP encoder/decoder
-
+*/
+/*
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
index f44c9ca..b2f85a6 100644 (file)
@@ -1,6 +1,9 @@
-/** Copyright (C) 2002 Jean-Marc Valin 
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
    @file sb_celp.h
-
+   @brief Sub-band CELP mode used for wideband encoding
+*/
+/*
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
index 8b50f15..0940b52 100644 (file)
@@ -1,7 +1,9 @@
-/** Copyright (C) 2002 Jean-Marc Valin
+/* Copyright (C) 2002 Jean-Marc Valin*/
+/**
   @file speex.h
   @brief Describes the different modes of the codec
-
+*/
+/*
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
@@ -28,16 +30,16 @@ extern "C" {
 #endif
 
 /* Values allowed for *ctl() requests */
-#define SPEEX_SET_ENH 0
-#define SPEEX_GET_ENH 1
+#define SPEEX_SET_ENH 0 /**< Set enhancement on/off (decoder only) */
+#define SPEEX_GET_ENH 1 /**< Get enhancement state (decoder only) */
 /*Would be SPEEX_SET_FRAME_SIZE, but it's (currently) invalid*/
-#define SPEEX_GET_FRAME_SIZE 3
-#define SPEEX_SET_QUALITY 4
-#define SPEEX_GET_QUALITY 5
-#define SPEEX_SET_MODE 6
-#define SPEEX_GET_MODE 7
-#define SPEEX_SET_LOW_MODE 8
-#define SPEEX_GET_LOW_MODE 9
+#define SPEEX_GET_FRAME_SIZE 3 /**< Obtain frame size used by encoder/decoder */
+#define SPEEX_SET_QUALITY 4 /**< Set quality value */
+#define SPEEX_GET_QUALITY 5 /**< Get current quality setting */
+#define SPEEX_SET_MODE 6 /**< Set sub-mode to use */
+#define SPEEX_GET_MODE 7 /**< Get current sub-mode in use */
+#define SPEEX_SET_LOW_MODE 8 /**< Set low-band sub-mode to use (wideband only)*/
+#define SPEEX_GET_LOW_MODE 9 /**< Get current low-band mode in use (wideband only)*/
 #define SPEEX_SET_HIGH_MODE 10
 #define SPEEX_GET_HIGH_MODE 11
 #define SPEEX_SET_VBR 12
@@ -178,11 +180,21 @@ void speex_decoder_destroy(void *state);
  */
 int speex_decode(void *state, SpeexBits *bits, float *out);
 
-/** Used like the ioctl function to control the encoder parameters */
+/** Used like the ioctl function to control the encoder parameters
+ *
+ * @param state Decoder state
+ * @param request ioctl-type request (one of the SPEEX_* macros)
+ * @param ptr Data exchanged to-from function
+ */
 void speex_decoder_ctl(void *state, int request, void *ptr);
 
 
-/** Query function for mode information */
+/** Query function for mode information
+ *
+ * @param mode Speex mode
+ * @param request ioctl-type request (one of the SPEEX_* macros)
+ * @param ptr Data exchanged to-from function
+ */
 void speex_mode_query(SpeexMode *mode, int request, void *ptr);
 
 
index 1dffb15..9bae24e 100644 (file)
@@ -1,7 +1,9 @@
-/** Copyright (C) 2002 Jean-Marc Valin
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
    @file speex_bits.h
    @brief Handles bit packing/unpacking
-
+*/
+/*
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
index f6174ae..fe09d11 100644 (file)
@@ -1,7 +1,9 @@
-/** Copyright (C) 2002 Jean-Marc Valin 
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
    @file speex_header.h
    @brief Describes the Speex header
-
+*/
+/*
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
@@ -33,27 +35,30 @@ struct SpeexMode;
 
 /** Speex header info for file-based formats */
 typedef struct SpeexHeader {
-   char speex_string[8];
-   char speex_version[SPEEX_HEADER_VERSION_LENGTH];
-   int speex_header_version;
-   int header_size;
-   int rate;
-   int mode;
-   int mode_bitstream_version;
-   int nb_channels;
-   int bitrate;
-   int frame_size;
-   int vbr;
-   int frames_per_packet;
-   int reserved1;
-   int reserved2;
-   int reserved3;
+   char speex_string[8]; /**< Identifies a Speex bit-stream, always set to "Speex   " */
+   char speex_version[SPEEX_HEADER_VERSION_LENGTH]; /**< Speex version */
+   int speex_header_version; /**< Version number for the header */
+   int header_size; /**< Total size of the header ( sizeof(SpeexHeader) ) */
+   int rate; /**< Sampling rate used */
+   int mode; /**< Mode used (0 for narrowband, 1 for wideband) */
+   int mode_bitstream_version; /**< Version ID of the bit-stream */
+   int nb_channels; /**< Number of channels encoded */
+   int bitrate; /**< Bit-rate used */
+   int frame_size; /**< Size of frames */
+   int vbr; /**< 1 for a VBR encoding, 0 otherwise */
+   int frames_per_packet; /**< Number of frames stored per Ogg packet */
+   int reserved1; /**< Reserved for future use */
+   int reserved2; /**< Reserved for future use */
+   int reserved3; /**< Reserved for future use */
 } SpeexHeader;
 
+/** Initializes a SpeexHeader using basic information */
 void speex_init_header(SpeexHeader *header, int rate, int nb_channels, struct SpeexMode *m);
 
+/** Creates the header packet from the header itself (mostly involves endianness conversion) */
 char *speex_header_to_packet(SpeexHeader *header, int *size);
 
+/** Creates a SpeexHeader from a packet */
 SpeexHeader *speex_packet_to_header(char *packet, int size);
 
 #ifdef __cplusplus