[xiph-commits] r16437 - trunk/theora/include/theora
giles at svn.xiph.org
giles at svn.xiph.org
Wed Aug 5 15:05:36 PDT 2009
Author: giles
Date: 2009-08-05 15:05:36 -0700 (Wed, 05 Aug 2009)
New Revision: 16437
Modified:
trunk/theora/include/theora/theora.h
trunk/theora/include/theora/theoradec.h
trunk/theora/include/theora/theoraenc.h
Log:
Remove encoder/decoder control codes which weren't in the 1.0 release
from the legacy theora.h header. While the theora_control()
implementation will pass on all the same control codes recognized by
th_encode_ctl() and th_decode_ctl(), we want to encourage migration
to the newer api, so we only declare them there.
Remove an obsolete limitation on user-supplied quant matrices.
Switch to an _old suffix on the theora.h version of the control code
anchors to avoid confusion with the new api. I also tried to clean up
the formatting but wasn't entirely successful; the documentation for
theoraenc.h and theoradec.h looks better.
Modified: trunk/theora/include/theora/theora.h
===================================================================
--- trunk/theora/include/theora/theora.h 2009-08-05 20:56:58 UTC (rev 16436)
+++ trunk/theora/include/theora/theora.h 2009-08-05 22:05:36 UTC (rev 16437)
@@ -292,14 +292,21 @@
/**\name theora_control() codes */
-
-/**\anchor decctlcodes
+/* \anchor decctlcodes_old
* These are the available request codes for theora_control()
* when called with a decoder instance.
- * By convention, these are odd, to distinguish them from the
- * \ref encctlcodes "encoder control codes".
+ * By convention decoder control codes are odd, to distinguish
+ * them from \ref encctlcodes_old "encoder control codes" which
+ * are even.
+ *
+ * Note that since the 1.0 release, both the legacy and the final
+ * implementation accept all the same control codes, but only the
+ * final API declares the newer codes.
+ *
* Keep any experimental or vendor-specific values above \c 0x8000.*/
+/*@{*/
+
/**Get the maximum post-processing level.
* The decoder supports a post-processing filter that can improve
* the appearance of the decoded images. This returns the highest
@@ -338,37 +345,23 @@
*/
#define TH_DECCTL_SET_GRANPOS (5)
-#define TH_DECCTL_SET_TELEMETRY_MBMODE (9)
-#define TH_DECCTL_SET_TELEMETRY_MV (11)
-#define TH_DECCTL_SET_TELEMETRY_QI (13)
-#define TH_DECCTL_SET_TELEMETRY_BITS (15)
+/**\anchor encctlcodes_old */
-/**\anchor encctlcodes
- * These are the available request codes for theora_control()
- * when called with an encoder instance.
- * By convention, these are even, to distinguish them from the
- * \ref decctlcodes "decoder control codes".
- * Keep any experimental or vendor-specific values above \c 0x8000.*/
-/*@{*/
/**Sets the quantization parameters to use.
* The parameters are copied, not stored by reference, so they can be freed
* after this call.
* <tt>NULL</tt> may be specified to revert to the default parameters.
- * For the current encoder, <tt>scale[ci!=0][qi]</tt> must be no greater than
- * <tt>scale[ci!=0][qi-1]</tt> and <tt>base[qti][pli][qi][ci]</tt> must be no
- * greater than <tt>base[qti][pli][qi-1][ci]</tt>.
- * These two conditions ensure that the actual quantizer for a given \a qti,
- * \a pli, and \a ci does not increase as \a qi increases.
*
* \param[in] buf #th_quant_info
* \retval TH_FAULT \a theora_state is <tt>NULL</tt>.
* \retval TH_EINVAL Encoding has already begun, the quantization parameters
- * do not meet one of the above stated conditions, \a buf
- * is <tt>NULL</tt> and \a buf_sz is not zero, or \a buf
- * is non-<tt>NULL</tt> and \a buf_sz is not
- * <tt>sizeof(#th_quant_info)</tt>.
+ * are not acceptable to this version of the encoder,
+ * \a buf is <tt>NULL</tt> and \a buf_sz is not zero,
+ * or \a buf is non-<tt>NULL</tt> and \a buf_sz is
+ * not <tt>sizeof(#th_quant_info)</tt>.
* \retval TH_IMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_QUANT_PARAMS (2)
+
/**Disables any encoder features that would prevent lossless transcoding back
* to VP3.
* This primarily means disabling block-level QI values and not using 4MV mode
@@ -397,6 +390,7 @@
* \retval TH_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>.
* \retval TH_IMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_VP3_COMPATIBLE (10)
+
/**Gets the maximum speed level.
* Higher speed levels favor quicker encoding over better quality per bit.
* Depending on the encoding mode, and the internal algorithms used, quality
@@ -411,6 +405,7 @@
* \retval TH_IMPL Not supported by this implementation in the current
* encoding mode.*/
#define TH_ENCCTL_GET_SPLEVEL_MAX (12)
+
/**Sets the speed level.
* By default a speed value of 1 is used.
*
@@ -425,32 +420,7 @@
* \retval TH_IMPL Not supported by this implementation in the current
* encoding mode.*/
#define TH_ENCCTL_SET_SPLEVEL (14)
-/**Sets the number of duplicates of the next frame to produce.
- * Although libtheora can encode duplicate frames very cheaply, it costs some
- * amount of CPU to detect them, and a run of duplicates cannot span a
- * keyframe boundary.
- * This control code tells the encoder to produce the specified number of extra
- * duplicates of the next frame.
- * This allows the encoder to make smarter keyframe placement decisions and
- * rate control decisions, as well as reduces CPU usage, when compared to just
- * submitting the same frame for encoding multiple times.
- * This setting only applies to the next frame submitted for encoding.
- * You MUST call th_encode_packetout() repeatedly until it returns 0, or the
- * extra duplicate frames will be lost.
- *
- * \param[in] _buf int: The number of duplicates to produce.
- * Unless this is positive, no duplicates will be produced.
- * \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
- * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the
- * number of duplicates is greater than or equal to the
- * maximum keyframe interval.
- * In the latter case, NO duplicate frames will be produced.
- * You must ensure that the maximum keyframe interval is set
- * larger than the maximum number of duplicates you will
- * ever wish to insert prior to encoding.
- * \retval TH_IMPL Not supported by this implementation in the current
- * encoding mode.*/
-#define TH_ENCCTL_SET_DUP_COUNT (18)
+
/*@}*/
#define OC_FAULT -1 /**< General failure */
@@ -809,8 +779,8 @@
* This is used to provide advanced control the encoding process.
* \param th A #theora_state handle.
* \param req The control code to process.
- * See \ref encctlcodes "the list of available control codes"
- * for details.
+ * See \ref encctlcodes_old "the list of available
+ * control codes" for details.
* \param buf The parameters for this control code.
* \param buf_sz The size of the parameter buffer.*/
extern int theora_control(theora_state *th,int req,void *buf,size_t buf_sz);
Modified: trunk/theora/include/theora/theoradec.h
===================================================================
--- trunk/theora/include/theora/theoradec.h 2009-08-05 20:56:58 UTC (rev 16436)
+++ trunk/theora/include/theora/theoradec.h 2009-08-05 22:05:36 UTC (rev 16437)
@@ -38,6 +38,10 @@
* Keep any experimental or vendor-specific values above \c 0x8000.*/
/*@{*/
/**Gets the maximum post-processing level.
+ * The decoder supports a post-processing filter that can improve
+ * the appearance of the decoded images. This returns the highest
+ * level setting for this post-processor, corresponding to maximum
+ * improvement and computational expense.
*
* \param[out] _buf int: The maximum post-processing level.
* \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
@@ -47,6 +51,10 @@
/**Sets the post-processing level.
* By default, post-processing is disabled.
*
+ * Sets the level of post-processing to use when decoding the
+ * compressed stream. This must be a value between zero (off)
+ * and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX.
+ *
* \param[in] _buf int: The new post-processing level.
* 0 to disable; larger values use more CPU.
* \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
@@ -83,12 +91,16 @@
* \retval TH_EINVAL \a _buf_sz is not
* <tt>sizeof(th_stripe_callback)</tt>.*/
#define TH_DECCTL_SET_STRIPE_CB (7)
-/*@}*/
+/**Enables telemetry and sets the macroblock display mode */
#define TH_DECCTL_SET_TELEMETRY_MBMODE (9)
+/**Enables telemetry and sets the motion vector display mode */
#define TH_DECCTL_SET_TELEMETRY_MV (11)
+/**Enables telemetry and sets the adaptive quantization display mode */
#define TH_DECCTL_SET_TELEMETRY_QI (13)
+/**Enables telemetry and sets the bitstream breakdown visualization mode */
#define TH_DECCTL_SET_TELEMETRY_BITS (15)
+/*@}*/
Modified: trunk/theora/include/theora/theoraenc.h
===================================================================
--- trunk/theora/include/theora/theoraenc.h 2009-08-05 20:56:58 UTC (rev 16436)
+++ trunk/theora/include/theora/theoraenc.h 2009-08-05 22:05:36 UTC (rev 16437)
@@ -55,19 +55,13 @@
* The parameters are copied, not stored by reference, so they can be freed
* after this call.
* <tt>NULL</tt> may be specified to revert to the default parameters.
- * For the current encoder, <tt>scale[ci!=0][qi]</tt> must be no greater than
- * <tt>scale[ci!=0][qi-1]</tt> and <tt>base[qti][pli][qi][ci]</tt> must be no
- * greater than <tt>base[qti][pli][qi-1][ci]</tt>.
- * These two conditions ensure that the actual quantizer for a given \a qti,
- * \a pli, and \a ci does not increase as \a qi increases.
*
* \param[in] _buf #th_quant_info
* \retval TH_EFAULT \a _enc_ctx is <tt>NULL</tt>.
- * \retval TH_EINVAL Encoding has already begun, the quantization parameters
- * do not meet one of the above stated conditions, \a _buf
- * is <tt>NULL</tt> and \a _buf_sz is not zero, or \a _buf
- * is non-<tt>NULL</tt> and \a _buf_sz is not
- * <tt>sizeof(#th_quant_info)</tt>.
+ * \retval TH_EINVAL Encoding has already begun, \a _buf is
+ * <tt>NULL</tt> and \a _buf_sz is not zero,
+ * or \a _buf is non-<tt>NULL</tt> and
+ * \a _buf_sz is not <tt>sizeof(#th_quant_info)</tt>.
* \retval TH_IMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_QUANT_PARAMS (2)
/**Sets the maximum distance between key frames.
More information about the commits
mailing list