From 8e17e82d9e38da697056f36df809ffdf35b432ca Mon Sep 17 00:00:00 2001
From: James Zern <jzern@google.com>
Date: Thu, 24 Feb 2011 14:12:57 -0800
Subject: [PATCH] documentation: minor updates to vp8 (en|de)coder

Group algorithm interfaces to avoid undocumented warning from doxygen
and provide basic documentation for CQ level & cpuused.

Change-Id: I11095061be962cbc998741de9c8c3019d415e137
---
 vpx/vp8cx.h | 30 ++++++++++++++++++++++++++----
 vpx/vp8dx.h |  9 +++++++--
 2 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/vpx/vp8cx.h b/vpx/vp8cx.h
index 8e0754702..5ff6bdcfb 100644
--- a/vpx/vp8cx.h
+++ b/vpx/vp8cx.h
@@ -24,13 +24,15 @@
 #define VP8CX_H
 #include "vpx/vpx_codec_impl_top.h"
 
-/*!\brief Algorithm interface for VP8
+/*!\name Algorithm interface for VP8
  *
  * This interface provides the capability to encode raw VP8 streams, as would
  * be found in AVI files.
+ * @{
  */
 extern vpx_codec_iface_t  vpx_codec_vp8_cx_algo;
 extern vpx_codec_iface_t* vpx_codec_vp8_cx(void);
+/*!@} - end algorithm interface member group*/
 
 
 /*
@@ -114,7 +116,10 @@ extern vpx_codec_iface_t* vpx_codec_vp8_cx(void);
 
 /*!\brief VP8 encoder control functions
  *
- * The set of macros define the control functions of VP8 encoder interface
+ * This set of macros define the control functions available for the VP8
+ * encoder interface.
+ *
+ * \sa #vpx_codec_control
  */
 enum vp8e_enc_control_id
 {
@@ -124,7 +129,18 @@ enum vp8e_enc_control_id
     VP8E_SET_ROI_MAP,                /**< control function to pass an ROI map to encoder */
     VP8E_SET_ACTIVEMAP,              /**< control function to pass an Active map to encoder */
     VP8E_SET_SCALEMODE         = 11, /**< control function to set encoder scaling mode */
-    VP8E_SET_CPUUSED           = 13, /**< control function to set vp8 encoder cpuused  */
+    /*!\brief control function to set vp8 encoder cpuused
+     *
+     * Changes in this value influences, among others, the encoder's selection
+     * of motion estimation methods. Values greater than 0 will increase encoder
+     * speed at the expense of quality.
+     * The full set of adjustments can be found in
+     * onyx_if.c:vp8_set_speed_features().
+     * \todo List highlights of the changes at various levels.
+     *
+     * \note Valid range: -16..16 or {-16..-4, 4..16} w/CONFIG_REALTIME_ONLY
+     */
+    VP8E_SET_CPUUSED           = 13,
     VP8E_SET_ENABLEAUTOALTREF,       /**< control function to enable vp8 to automatic set and use altref frame */
     VP8E_SET_NOISE_SENSITIVITY,      /**< control function to set noise sensitivity */
     VP8E_SET_SHARPNESS,              /**< control function to set sharpness */
@@ -141,7 +157,13 @@ enum vp8e_enc_control_id
     VP8E_SET_ARNR_STRENGTH ,         /**< control function to set the filter strength for the arf */
     VP8E_SET_ARNR_TYPE     ,         /**< control function to set the type of filter to use for the arf*/
     VP8E_SET_TUNING,                 /**< control function to set visual tuning */
-    VP8E_SET_CQ_LEVEL,               /**< control function to set constrained quality level */
+    /*!\brief control function to set constrained quality level
+     *
+     * \attention For this value to be used vpx_codec_enc_cfg_t::g_usage must be
+     *            set to #VPX_CQ.
+     * \note Valid range: 0..63
+     */
+    VP8E_SET_CQ_LEVEL,
 };
 
 /*!\brief vpx 1-D scaling mode
diff --git a/vpx/vp8dx.h b/vpx/vp8dx.h
index a2a0dd178..1a81a81f4 100644
--- a/vpx/vp8dx.h
+++ b/vpx/vp8dx.h
@@ -24,13 +24,15 @@
 #define VP8DX_H
 #include "vpx/vpx_codec_impl_top.h"
 
-/*!\brief Algorithm interface for VP8
+/*!\name Algorithm interface for VP8
  *
  * This interface provides the capability to decode raw VP8 streams, as would
  * be found in AVI files and other non-Flash uses.
+ * @{
  */
 extern vpx_codec_iface_t  vpx_codec_vp8_dx_algo;
 extern vpx_codec_iface_t* vpx_codec_vp8_dx(void);
+/*!@} - end algorithm interface member group*/
 
 /* Include controls common to both the encoder and decoder */
 #include "vp8.h"
@@ -38,7 +40,10 @@ extern vpx_codec_iface_t* vpx_codec_vp8_dx(void);
 
 /*!\brief VP8 decoder control functions
  *
- * The set of macros define the control functions of VP8 decoder interface
+ * This set of macros define the control functions available for the VP8
+ * decoder interface.
+ *
+ * \sa #vpx_codec_control
  */
 enum vp8d_dec_control_id
 {
-- 
2.40.0