[vorbis-dev] Documentation Suggestions

[Marc Templin]

I'm a developer for a game company and I'm almost done adding support for
Vorbis to our game engine.  As such, I wanted to simply plug in the read
function, let it decode, and then send the PCM data on to DirectSound just
like I always have.   There were several occasions where I spent 4 or 5
hours trying to fix a bug, digging through newsgroups and sound-format
specs, when that info could easily have been in the Vorbis documentation.
In the interest of helping other lazy developers, and improving Ogg's
ease-of-use and rapid deployment, maybe you could add these tidbits to the
libvorbisfile docs somewhere?

-> ov_read() wants to know if your data is signed or unsigned.  It would be
nice if the comments told you outright that 8-bit PCM data is unsigned,
16-bit is signed (at least, as far as I could find in various specs).

-> I spent a long time on linker issues and then crashing before I found one
post that mentioned problems with the fseek wrapper in the default
callbacks.  I set up a callbacks struct to use the standard fopen, fseek,
etc, and the problems went away.

-> If your music license specifies that the music on your CD must be
inaccessible to the average user somehow, you can simply stick your custom
header on a .ogg file, read that header in first, and then pass the slightly
used FILE* to ov_open.  Vorbisfile doesn't have a problem with that at all
(whether it's secure enough is up to you.  It is for me).

-> If you're only playing one file at a time, and you encoded the file
yourself from a single .wav, don't worry about the whole
current_section-switching-formats thing.

If any of these are not true for the general case, then feel free to correct
me, but this is my experience trying to use vorbisfile to improve our game's
audio system.

-Marc Templin
Engine and Tools Developer
Her Interactive

<p>--- >8 ----
List archives:  http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'vorbis-dev-request at xiph.org'
containing only the word 'unsubscribe' in the body.  No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.