--- trunk/xvidcore/src/xvid.h 2002/10/21 23:13:53 608
+++ trunk/xvidcore/src/xvid.h 2002/11/26 23:44:11 677
@@ -3,30 +3,52 @@
* XVID MPEG-4 VIDEO CODEC
* - XviD Main header file -
*
- * This program is an implementation of a part of one or more MPEG-4
- * Video tools as specified in ISO/IEC 14496-2 standard. Those intending
- * to use this software module in hardware or software products are
- * advised that its use may infringe existing patents or copyrights, and
- * any such use would be at such party's own risk. The original
- * developer of this software module and his/her company, and subsequent
- * editors and their companies, will have no liability for use of this
- * software or modifications or derivatives thereof.
- *
- * This program is free software ; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation ; either version 2 of the License, or
+ * This file is part of XviD, a free MPEG-4 video encoder/decoder
+ *
+ * XviD is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY ; without even the implied warranty of
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
- * along with this program ; if not, write to the Free Software
+ * along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
- * $Id: xvid.h,v 1.20 2002-10-21 23:13:53 edgomez Exp $
+ * Under section 8 of the GNU General Public License, the copyright
+ * holders of XVID explicitly forbid distribution in the following
+ * countries:
+ *
+ * - Japan
+ * - United States of America
+ *
+ * Linking XviD statically or dynamically with other modules is making a
+ * combined work based on XviD. Thus, the terms and conditions of the
+ * GNU General Public License cover the whole combination.
+ *
+ * As a special exception, the copyright holders of XviD give you
+ * permission to link XviD with independent modules that communicate with
+ * XviD solely through the VFW1.1 and DShow interfaces, regardless of the
+ * license terms of these independent modules, and to copy and distribute
+ * the resulting combined work under terms of your choice, provided that
+ * every copy of the combined work is accompanied by a complete copy of
+ * the source code of XviD (the version of XviD used to produce the
+ * combined work), being distributed under the terms of the GNU General
+ * Public License plus this exception. An independent module is a module
+ * which is not derived from or based on XviD.
+ *
+ * Note that people who make modified versions of XviD are not obligated
+ * to grant this special exception for their modified versions; it is
+ * their choice whether to do so. The GNU General Public License gives
+ * permission to release a modified version without this exception; this
+ * exception also makes it possible to release a modified version which
+ * carries forward this exception.
+ *
+ * $Id: xvid.h,v 1.24 2002-11-26 23:44:10 edgomez Exp $
*
*****************************************************************************/
@@ -60,7 +82,7 @@
* You can use it to check if the host XviD library API is the same as the one
* you used to build you client program. If versions mismatch, then it is
* highly possible that your application will segfault because the host XviD
- * library and your application use structure fields in different ways.
+ * library and your application use different structures.
*
*/
@@ -73,7 +95,7 @@
/**
- * \defgroup error_grp Error codes used by XviD API entry points.
+ * \defgroup error_grp Error codes returned by XviD API entry points.
* @{
*/
@@ -85,10 +107,9 @@
* this point of the code. Clean all instances you
* already created and exit the program cleanly.
*
xvid_encore or xvid_decore : something was wrong and en/decoding
- * operation has not been completed
- * sucessfully. At your option, you can
- * stop the en/decoding process or just ignore
- * and go on.
+ * operation was not completed sucessfully.
+ * you can stop the en/decoding process or just
+ * ignore and go on.
* xvid_stop : you can safely ignore it if you call this function at the
* end of your program.
*
@@ -102,14 +123,12 @@
#define XVID_ERR_MEMORY 1 /**< Operation failed.
*
- * No memory was available on the host system, this is probably time to kill
- * some unuseful programs (WinSpyWare, KDE, GNOME) in order to
- * use XviD.
+ * Insufficent memory was available on the host system.
*/
#define XVID_ERR_FORMAT 2 /**< Operation failed.
*
- * The format of the parameters, input stream were wrong.
+ * The format of the parameters or input stream were incorrect.
*/
/** @} */
@@ -125,18 +144,20 @@
* @{
*/
-#define XVID_CSP_RGB24 0 /**< Input/output frame uses the RGB24 colorspace format */
-#define XVID_CSP_YV12 1 /**< Input/output frame uses the YV12 colorspace format */
-#define XVID_CSP_YUY2 2 /**< Input/output frame uses the YUV2 colorspace format */
-#define XVID_CSP_UYVY 3 /**< Input/output frame uses the UYVY colorspace format */
-#define XVID_CSP_I420 4 /**< Input/output frame uses the I420 colorspace format */
-#define XVID_CSP_RGB555 10 /**< Input/output frame uses the RGB555 colorspace format */
-#define XVID_CSP_RGB565 11 /**< Input/output frame uses the RGB565 colorspace format */
-#define XVID_CSP_USER 12 /**< Input/output frame uses the USER colorspace format
- *
- * XviD will not perform any colorspace conversion. The
- * output will be the native MPEG4 YV12 colorspace. Up to
- * the client application to convert it to a usable format. */
+#define XVID_CSP_RGB24 0 /**< 24-bit RGB colorspace (b,g,r packed) */
+#define XVID_CSP_YV12 1 /**< YV12 colorspace (y,v,u planar) */
+#define XVID_CSP_YUY2 2 /**< YUY2 colorspace (y,u,y,v packed) */
+#define XVID_CSP_UYVY 3 /**< UYVY colorspace (u,y,v,y packed) */
+#define XVID_CSP_I420 4 /**< I420 colorsapce (y,u,v planar) */
+#define XVID_CSP_RGB555 10 /**< 16-bit RGB555 colorspace */
+#define XVID_CSP_RGB565 11 /**< 16-bit RGB565 colorspace */
+#define XVID_CSP_USER 12 /**< user colorspace format, where the image buffer points
+ * to a DEC_PICTURE (y,u,v planar) structure.
+ *
+ * For encoding, image is read from the DEC_PICTURE
+ * parameter values. For decoding, the DEC_PICTURE
+ * parameters are set, pointing to the internal XviD
+ * image buffer. */
#define XVID_CSP_EXTERN 1004 /**< Special colorspace used for slice rendering
*
* The application provides an external buffer to XviD.
@@ -144,11 +165,11 @@
* buffer, no need to specify this is a speed boost feature.
* This feature is only used by mplayer at the moment, refer
* to mplayer code to see how it can be used. */
-#define XVID_CSP_YVYU 1002 /**< Input/output frame uses the YVYU colorspace format */
-#define XVID_CSP_RGB32 1000 /**< Input/output frame uses the RGB32 colorspace format */
-#define XVID_CSP_NULL 9999 /**< Input/output frame uses the NULL colorspace format */
+#define XVID_CSP_YVYU 1002 /**< YVYU colorspace (y,v,y,u packed) */
+#define XVID_CSP_RGB32 1000 /**< 32-bit RGB colorspace (b,g,r,a packed) */
+#define XVID_CSP_NULL 9999 /**< NULL colorspace; no conversion is performed */
-#define XVID_CSP_VFLIP 0x80000000 /**< Flips input/output frames */
+#define XVID_CSP_VFLIP 0x80000000 /**< (flag) Flip frame vertically during conversion */
/** @} */
@@ -188,7 +209,7 @@
#define XVID_CPU_SSE 0x00000004 /**< use/has SSE (pentium3) instruction set */
#define XVID_CPU_SSE2 0x00000008 /**< use/has SSE2 (pentium4) instruction set */
#define XVID_CPU_3DNOW 0x00000010 /**< use/has 3dNOW (k6-2) instruction set */
-#define XVID_CPU_3DNOWEXT 0x00000020 /**< use/has 3dNOW-ext (???) instruction set */
+#define XVID_CPU_3DNOWEXT 0x00000020 /**< use/has 3dNOW-ext (athlon) instruction set */
#define XVID_CPU_TSC 0x00000040 /**< has TimeStampCounter instruction */
/** @} */
@@ -199,7 +220,7 @@
*/
#define XVID_CPU_IA64 0x00000080 /**< Forces ia64 optimized code usage
- *
+ *
* This flags allow client applications to force IA64 optimized functions.
* This feature is considered exeperimental and should be treated as is.
*/
@@ -248,8 +269,7 @@
* library
*/
int core_build; /**< [out]
- * \todo Still unused at the moment, what do we
- * do with that ?
+ * \todo Unused.
*/
}
XVID_INIT_PARAM;
@@ -292,7 +312,7 @@
* \defgroup decoder_grp Decoder related functions and structures.
*
* This part describes all the structures/functions from XviD's API needed for
- * decoding a MPEG4 compliant stream.
+ * decoding a MPEG4 compliant streams.
* @{
*/
@@ -338,7 +358,7 @@
XVID_DEC_FRAME;
- // This struct is used for per slice rendering
+ /* This struct is used for per slice rendering */
typedef struct
{
void *y,*u,*v;
@@ -367,9 +387,8 @@
#define XVID_DEC_CREATE 1 /**< Creates a decoder instance
*
* This operation constant is used by a client application in order to create
- * a decoder instance. All instances are independant from each other, so
- * client application can use safely various threads, each decoding a
- * different MPEG4 bitstream.
+ * a decoder instance. Decoder instances are independant from each other, and
+ * can be safely threaded.
*/
#define XVID_DEC_DESTROY 2 /**< Destroys a decoder instance
@@ -394,10 +413,10 @@
* This is the XviD's decoder entry point. The possible operations are
* described in the \ref decops_grp section.
*
- * \param handle Todo
- * \param opt Todo
- * \param param1 Todo
- * \param param2 Todo
+ * \param handle Decoder instance handle.
+ * \param opt Decoder option constant
+ * \param param1 Used to pass a XVID_DEC_PARAM or XVID_DEC_FRAME structure
+ * \param param2 Reserved for future use.
*/
int xvid_decore(void *handle,
@@ -438,26 +457,26 @@
* This flag forces XviD to use MPEG4 quantization type */
#define XVID_HALFPEL 0x00000040 /**< Halfpel motion estimation
*
-* informs xvid to perform a half pixel motion estimation. */
+* informs xvid to perform a half pixel motion estimation. */
#define XVID_ADAPTIVEQUANT 0x00000080/**< Adaptive quantization
*
-* informs xvid to perform an adaptative quantization using a Luminance
+* informs xvid to perform an adaptative quantization using a Luminance
* masking algorithm */
-#define XVID_LUMIMASKING 0x00000100/**< Lumiomasking flag
+#define XVID_LUMIMASKING 0x00000100/**< Lumimasking flag
*
-* \deprecated Please do not use this flag anymore */
+ * \deprecated This flag is no longer used. */
#define XVID_LATEINTRA 0x00000200/**< Unknown
*
-* ??? */
+ * \deprecated This flag is no longer used. */
#define XVID_INTERLACING 0x00000400/**< MPEG4 interlacing mode.
*
-* Switches MPEG4 interlacing mode */
-#define XVID_TOPFIELDFIRST 0x00000800/**<
- *
-* */
+ * Enables interlacing encoding mode */
+#define XVID_TOPFIELDFIRST 0x00000800/**< Unknown
+ *
+ * \deprecated This flag is no longer used. */
#define XVID_ALTERNATESCAN 0x00001000/**<
*
-* */
+ * \deprecated This flag is no longer used. */
#define XVID_HINTEDME_GET 0x00002000/**< Gets Motion vector data from ME system.
*
* informs xvid to return Motion Estimation vectors from the ME encoder
@@ -490,9 +509,9 @@
*
* This flags forces XviD to discard chroma data, this is not mpeg4 greyscale
* mode, it simply drops chroma MBs using cbp == 0 for these blocks */
-#define XVID_GRAYSCALE XVID_GREYSCALE /**< XVID_GREYSCALE alia for US speakerss
+#define XVID_GRAYSCALE XVID_GREYSCALE /**< XVID_GREYSCALE alias
*
-* Same as above */
+* United States locale support. */
/** @} */
@@ -514,8 +533,8 @@
*/
#define PMV_HALFPELREFINE16 0x00020000/**< Turns on halfpel refinement step
*
-* After normal diamond search, an extra halfpel refinement step is performed. Should always be used if
-* XVID_HALFPEL is on, because it gives a rather big increase in quality.
+* After normal diamond search, an extra halfpel refinement step is performed. Should always be used if
+* XVID_HALFPEL is on, because it gives a rather big increase in quality.
*/
#define PMV_EXTSEARCH16 0x00040000/**< Extends search for 16x16 blocks
*
@@ -531,7 +550,7 @@
*/
#define PMV_QUICKSTOP16 0x00100000/**< Dynamic ME thresholding
*
-* like EARLYSTOP, but not even halfpel refinement is done. Normally worse quality, so it defaults to
+* like EARLYSTOP, but not even halfpel refinement is done. Normally worse quality, so it defaults to
* off. Might be removed, too.
*/
#define PMV_UNRESTRICTED16 0x00200000/**< Not implemented
@@ -684,7 +703,7 @@
* Frame quantizer :
*
* - 0 (zero) : Then the rate controler chooses the right quantizer
- * for you. Tipically used in ABR encoding or first pass of a VBR
+ * for you. Typically used in ABR encoding, or first pass of a VBR
* encoding session.
*
- != 0 : Then you force the encoder to use this specific
* quantizer value. It is clamped in the interval
@@ -727,13 +746,13 @@
* Header bytes in the resulting MPEG4 stream */
int kblks; /**< [out]
*
- * Number of MacroBlocks coded as Intra blocks */
+ * Number of intra macro blocks */
int mblks; /**< [out]
*
- * Number of MacroBlocks coded as Inter blocks */
+ * Number of inter macro blocks */
int ublks; /**< [out]
*
- * Number of MacroBlocks coded as skipped blocks */
+ * Number of skipped macro blocks */
}
XVID_ENC_STATS;
@@ -750,7 +769,7 @@
* @{
*/
-#define XVID_ENC_DECODE 0 /**< Encodes a frame
+#define XVID_ENC_ENCODE 0 /**< Encodes a frame
*
* This operation constant is used when client application wants to encode a
* frame. Client application must also fill XVID_ENC_FRAME appropriately.
@@ -759,9 +778,7 @@
#define XVID_ENC_CREATE 1 /**< Creates a decoder instance
*
* This operation constant is used by a client application in order to create
- * an encoder instance. All instances are independant from each other, so
- * client application can use safely various threads, each encoding a
- * different set of frames.
+ * an encoder instance. Encoder instances are independant from each other.
*/
#define XVID_ENC_DESTROY 2 /**< Destroys a encoder instance
@@ -785,10 +802,10 @@
* This is the XviD's encoder entry point. The possible operations are
* described in the \ref encops_grp section.
*
- * \param handle Todo
- * \param opt Todo
- * \param param1 Todo
- * \param param2 Todo
+ * \param handle Encoder instance handle
+ * \param opt Encoder option constant
+ * \param param1 Used to pass XVID_ENC_PARAM or XVID_ENC_FRAME structures.
+ * \param param2 Optionally used to pass the XVID_ENC_STATS structure.
*/
int xvid_encore(void *handle,
int opt,