[Ffmpeg-cvslog] CVS: ffmpeg/doc faq.texi, 1.22, 1.23 ffmpeg-doc.texi, 1.92, 1.93

[Diego Biurrun CVS]

Update of /cvsroot/ffmpeg/ffmpeg/doc
In directory mail:/var2/tmp/cvs-serv16918/doc

Modified Files:
	faq.texi ffmpeg-doc.texi 
Log Message:
Since there have been quite a few questions recently on how to use the
FFmpeg libraries with Visual C++, here's a patch for the documentation
that explains everything in (excruciating) detail.

patch by Martin Boehme <boehme -- at -- inb -- dot -- uni-luebeck -- dot -- de>


Index: faq.texi
===================================================================
RCS file: /cvsroot/ffmpeg/ffmpeg/doc/faq.texi,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -d -r1.22 -r1.23
--- faq.texi	13 Sep 2005 23:33:53 -0000	1.22
+++ faq.texi	28 Sep 2005 21:18:11 -0000	1.23
@@ -160,8 +160,8 @@
 
 Yes, but the MinGW tools @emph{must} be used to compile FFmpeg. You
 can link the resulting DLLs with any other Windows program. Read the
- at emph{Native Windows Compilation} section in the FFmpeg documentation
-to find more information.
+ at emph{Native Windows Compilation} and @emph{Visual C++ compatibility}
+sections in the FFmpeg documentation to find more information.
 
 @section Can you add automake, libtool or autoconf support ?
 
@@ -201,6 +201,7 @@
 You need a C compiler (Visual C++ is not compliant to the C standard).
 If you wish - for whatever weird reason - to use Visual C++ for your
 project then you can link the Visual C++ code with libav* as long as
-you compile the latter with a working C compiler.
+you compile the latter with a working C compiler. For more information, see
+the @emph{Visual C++ compatibility} section in the FFmpeg documentation.
 
 @bye

Index: ffmpeg-doc.texi
===================================================================
RCS file: /cvsroot/ffmpeg/ffmpeg/doc/ffmpeg-doc.texi,v
retrieving revision 1.92
retrieving revision 1.93
diff -u -d -r1.92 -r1.93
--- ffmpeg-doc.texi	12 Sep 2005 16:30:46 -0000	1.92
+++ ffmpeg-doc.texi	28 Sep 2005 21:18:11 -0000	1.93
@@ -918,10 +918,134 @@
 when configuring FFmpeg, FFmpeg tries to use the Microsoft Visual
 C++ @code{lib} tool to build @code{avcodec.lib} and
 @code{avformat.lib}. With these libraries you can link your Visual C++
-code directly with the FFmpeg DLLs.
+code directly with the FFmpeg DLLs (see below).
 
 @end itemize
 
+ at subsection Visual C++ compatibility
+
+FFmpeg will not compile under Visual C++ -- and it has too many
+dependencies on the GCC compiler to make a port viable. However,
+if you want to use the FFmpeg libraries in your own applications,
+you can still compile those applications using Visual C++. An
+important restriction to this is that you have to use the
+dynamically linked versions of the FFmpeg libraries (i.e. the
+DLLs), and you have to make sure that Visual-C++-compatible
+import libraries are created during the FFmpeg build process.
+
+This description of how to use the FFmpeg libraries with Visual C++ is
+based on Visual C++ 2005 Express Edition Beta 2. If you have a different
+version, you might have to modify the procedures slightly.
+
+Here are the step-by-step instructions for building the FFmpeg libraries
+so they can be used with Visual C++:
+
+ at enumerate
+
+ at item Install Visual C++ (if you haven't done so already).
+
+ at item Install MinGW and MSYS as described above.
+
+ at item Add a call to @file{vcvars32.bat} (which sets up the environment
+variables for the Visual C++ tools) as the first line of
+ at file{msys.bat}. The standard location for @file{vcvars32.bat} is
+ at file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat},
+and the standard location for @file{msys.bat} is
+ at file{C:\msys\1.0\msys.bat}. If this corresponds to your setup, add the
+following line as the first line of @file{msys.bat}:
+
+ at code{call "C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat"}
+
+ at item Start the MSYS shell (file @file{msys.bat}) and type @code{link.exe}.
+If you get a help message with the command line options of @code{link.exe},
+this means your environment variables are set up correctly, the
+Microsoft linker is on the path and will be used by FFmpeg to
+create Visual-C++-compatible import libraries.
+
+ at item Extract the current version of FFmpeg (the latest release version or
+the current CVS snapshot, whichever is recommended) and change to the
+FFmpeg directory.
+
+ at item Type the command
+ at code{./configure --enable-shared --enable-memalign-hack} to configure and,
+if that didn't produce any errors, type @code{make} to build FFmpeg.
+
+ at item The subdirectories @file{libavformat}, @file{libavcodec}, and
+ at file{libavutil} should now contain the files @file{avformat.dll},
+ at file{avformat.lib}, @file{avcodec.dll}, @file{avcodec.lib},
+ at file{avutil.dll}, and @file{avutil.lib}, respectively. Copy the three
+DLLs to your System32 directory (typically @file{C:\Windows\System32}).
+
+ at end enumerate
+
+And here is how to use these libraries with Visual C++:
+
+ at enumerate
+
+ at item Create a new console application ("File / New / Project") and then
+select "Win32 Console Application". On the appropriate page of the
+Application Wizard, uncheck the "Precompiled headers" option.
+
+ at item Write the source code for your application, or, for testing, just
+copy the code from an existing sample application into the source file
+that Visual C++ has already created for you. (Note that your source
+filehas to have a @code{.cpp} extension; otherwise, Visual C++ won't
+compile the FFmpeg headers correctly because in C mode, it doesn't
+recognize the @code{inline} keyword.)  For example, you can copy
+ at file{output_example.c} from the FFmpeg distribution (but you will
+have to make minor modifications so the code will compile under
+C++, see below).
+
+ at item Open the "Project / Properties" dialog box. In the "Configuration"
+combo box, select "All Configurations" so that the changes you make will
+affect both debug and release builds. In the tree view on the left hand
+side, select "C/C++ / General", then edit the "Additional Include
+Directories" setting to contain the complete paths to the
+ at file{libavformat}, @file{libavcodec}, and @file{libavutil}
+subdirectories of your FFmpeg directory. Note that the directories have
+to be separated using semicolons. Now select "Linker / General" from the
+tree view and edit the "Additional Library Directories" setting to
+contain the same three directories.
+
+ at item Still in the "Project / Properties" dialog box, select "Linker / Input"
+from the tree view, then add the files @file{avformat.lib},
+ at file{avcodec.lib}, and @file{avutil.lib} to the end of the "Additional
+Dependencies". Note that the names of the libraries have to be separated
+using spaces.
+
+ at item Now, select "C/C++ / Preprocessor" from the tree view. Select "Debug"
+in the "Configuration" combo box. Add @code{EMULATE_INTTYPES} to the
+"Preprocessor Definitions". (Note that the various preprocessor
+definitions have to be separated using semicolons.) Select "Release" in
+the "Configuration" combo box and, again, add @code{EMULATE_INTTYPES} to
+the "Preprocessor Definitions". (This has to be done separately because
+debug and release builds have different preprocessor definitions.)
+Finally, select "C/C++ / Code Generation" from the tree view. Select
+"Debug" in the "Configuration" combo box. Make sure that "Runtime
+Library" is set to "Multi-threaded Debug DLL". Then, select "Release" in
+the "Configuration" combo box and make sure that "Runtime Library" is
+set to "Multi-threaded DLL".
+
+ at item Click "OK" to close the "Project / Properties" dialog box and build
+the application. Hopefully, it should compile and run cleanly. If you
+used @file{output_example.c} as your sample application, you will get a
+few compiler errors, but they are easy to fix. The first type of error
+occurs because Visual C++ doesn't allow an @code{int} to be converted to
+an @code{enum} without a cast. To solve the problem, insert the required
+casts (this error occurs once for a @code{CodecID} and once for a
+ at code{CodecType}).  The second type of error occurs because C++ requires
+the return value of @code{malloc} to be cast to the exact type of the
+pointer it is being assigned to. Visual C++ will complain that, for
+example, @code{(void *)} is being assigned to @code{(uint8_t *)} without
+an explicit cast. So insert an explicit cast in these places to silence
+the compiler. The third type of error occurs because the @code{snprintf}
+library function is called @code{_snprintf} under Visual C++.  So just
+add an underscore to fix the problem. With these changes,
+ at file{output_example.c} should compile under Visual C++, and the
+resulting executable should produce valid video files.
+
+ at end enumerate
+
 @subsection Cross compilation for Windows with Linux
 
 You must use the MinGW cross compilation tools available at