§ ¶VirtualDub Plugin SDK 1.0 released
The new VirtualDub Plugin SDK has been released and supercedes the old Filter SDK. You'll find it via the navigation links on the right, or on the main site, if you're reading this via a feed. This is intended for anyone writing plugins or even attempting to host plugins. The differences from the filter SDK are as follows:
- Describes plugin API functionality through the current version of VirtualDub (1.8.6).
- Contains new information about 64-bit plugins and input drivers.
- Reorganized and improved documentation in HTML Help (CHM) format.
- Includes project files for Visual C++ 6.0 and Visual Studio 2005 (easily convertable to VS2008).
- Includes new wrappers to make it easier to create video filters in object oriented form instead of procedural form.
If you've ever tried to write documentation like this before, you probably discovered like I did that it takes a lot of time. In fact, it often takes longer to document functionality than it takes to implement it, at least if you want to write docs that are a bit more useful and better formatted than slightly warmed over headers. Describing the meaning of symbols and calls in an API is one thing; actually writing coherent documentation that shows how they should be used to an end is another.
Another change in the documentation style is that the Plugin SDK omits most of the information from the Filter SDK about how to write optimized code, particularly the assembly/MMX portions. One reason is that it didn't fit well with the purpose of documenting the API, and another is that a lot of the advice in the filter SDK is outdated, given that it was written in the days of the 80486 and Pentium architectures, and it would take a lot of work to revise it. That isn't to say that the information isn't important, as the potential gains from vector optimization are as great today as they were years ago, but looking back at the old documentation I was dissatisfied with the treatment of the topic. That's probably a reflection of the way that I've evolved as a programmer over the years.
Comments
Comments posted:
Tangental but related: in my experience, Doxygen was the worst thing to happen to library documentation. People end up with a maze of documentation of individual functions (crude reference material at best), with no high-level information about how to actually use the library, and this is sufficient enough in the minds of many developers as "documentation" to prevent the creation of real, useful documentation permanently.
Glenn Maynard - 05 10 08 - 00:02
Yeah, I've noticed that too. I still think autodoc tools like Doxygen are advantageous, but you need to write the full docs elsewhere. Doxygen output itself isn't sufficient for external developers, and if you try to generate that level of output from comments in the header you end up with unreadable header files. The default Doxygen formatting is also IMO awful, but that can at least be somewhat fixed up with a bit of options tweaking.
I tried running Doxygen over the VirtualDub code base at one point, and decided it wasn't worth it. The quality of the documentation wasn't up to snuff, and because VirtualDub is something like 9MB of source code, it took about 10 minutes to generate the docs, which is way too slow.
So far, I like the MSDN Win32 documentation style best, with its one page per method/structure style, and everything broken out in the TOC. Doxygen docs aren't sufficiently and require too much scrolling. The .NET Framework documentation style has way too many layers of cruft and the multi-language thing bloats the docs.
One area that tends to be pretty badly neglected in documentation is samples. Writing useful samples is difficult, but doing so often helps show the weaknesses in the API and the docs, and working code is helpful to newbies trying to get things working. Many parts of the current plugin API and VDXFrame library were borne out of a desire to reduce the amount of boilerplate needed in the samples.
Phaeron - 05 10 08 - 21:16
Great work Avery! Can't wait to test it.
Igor Levicki (link) - 17 10 08 - 00:21
IMO, the version number should be 2.0 :)
And yes, documentation is hard task.
Fizick - 18 10 08 - 07:24
Comment form
Please keep comments on-topic for this entry. If you have unrelated comments about VirtualDub, the forum is a better place to post them.
