third_party_libsnd/docs/linux_games_programming.txt

# Here are some some emails I exchanged with a guy trying to use 
# libsndfile version 1 with code from the book "Linux Games Programming"
# by John Hall. The email addresses have been changed to foil the spam
# bots.

Date: Tue, 20 Jul 2004 22:49:21 +0100
From: Paul <paul@fake-domain-name.co.uk>
To: erikd@fake-domain-name.com
Subject: Can you help with a problem?
Date: Tue, 20 Jul 2004 22:49:21 +0100

Hi,

I'm trying to get the source examples in the "Programming Linux Games" 
(NoStarch, Loki Software + John R. Hall) which use sndfile.h/libsndfile.

While I can guess some of the newer versions of function calls and 
enumerations, there are some which I cannot guess.

Would you be able to translate them to the current version of 
enumeration and function calls so that I can update the source?

These are the three currently failing me:

    sf_open_read(filename, SF_INFO *sfinfo) (guess: sf_open(filename,SFM_READ, &sfinfo))
    SF_FORMAT_PCM (guess: either SF_FORMAT_PCM_U8 or _RAW)
    SF_INFO.pcmbitwidth (guess: no idea!)

There are probably more. I'm happy to send you the source files for 
sound calls, scan the pages or anything else. Failing that, is there 
somewhere with the changes listed so I can try and fix the code for myself?

Thanks

TTFN

Paul

================================================================================

Date: Wed, 21 Jul 2004 17:38:08 +1000
From: Erik de Castro Lopo <erikd@fake-domain-name.com>
To: Paul <paul@fake-domain-name.co.uk>
Subject: Re: Can you help with a problem?

On Tue, 20 Jul 2004 22:49:21 +0100
Paul <paul@fake-domain-name.co.uk> wrote:

> Hi,
> 
> I'm trying to get the source examples in the "Programming Linux Games" 
> (NoStarch, Loki Software + John R. Hall) which use sndfile.h/libsndfile.
> 
> While I can guess some of the newer versions of function calls and 
> enumerations, there are some which I cannot guess.
> 
> Would you be able to translate them to the current version of 
> enumeration and function calls so that I can update the source?
> 
> These are the three currently failing me:
> 
> sf_open_read(filename, SF_INFO *sfinfo) (guess: sf_open(filename, 
> SFM_READ, &sfinfo))

yes.

> SF_FORMAT_PCM (guess: either SF_FORMAT_PCM_U8 or _RAW)

Actually this list:

    SF_FORMAT_PCM_U8
    SF_FORMAT_PCM_S8
    SF_FORMAT_PCM_16
    SF_FORMAT_PCM_24
    SF_FORMAT_PCM_32

> SF_INFO.pcmbitwidth (guess: no idea!)

WIth the above change, pcmbitwidth becomes redundant.

> There are probably more. I'm happy to send you the source files for 
> sound calls, scan the pages or anything else. Failing that, is there 
> somewhere with the changes listed so I can try and fix the code for
> myself?

Version 1.0.0 came out some time ago, but I think this:

    http://www.mega-nerd.com/libsndfile/version-1.html

lists most of the changes. You should also look at the API docs:

    http://www.mega-nerd.com/libsndfile/api.html

HTH,
Erik
-- 
+-----------------------------------------------------------+
  Erik de Castro Lopo      nospam@fake-domain-name.com
+-----------------------------------------------------------+
"There is no reason why anyone would want a computer in their home"
Ken Olson, DEC, 1977

================================================================================

From: PFJ <paul@fake-domain-name.co.uk>
To: Erik de Castro Lopo <erikd@fake-domain-name.com>
Subject: Re: Can you help with a problem?
Date: Wed, 21 Jul 2004 09:07:39 +0100


Hi Erik,

Thanks for getting back to me.

> > sf_open_read(filename, SF_INFO *sfinfo) (guess: sf_open(filename, SFM_READ, &sfinfo))
>
> yes.

Yay!

> > SF_FORMAT_PCM (guess: either SF_FORMAT_PCM_U8 or _RAW)
>
> Actually this list:
>
>     SF_FORMAT_PCM_U8
>     SF_FORMAT_PCM_S8
>     SF_FORMAT_PCM_16
>     SF_FORMAT_PCM_24
>     SF_FORMAT_PCM_32

I know, but the source code explicitly has SF_FORMAT_PCM which given the
code afterwards would equate to one of the above, but given that PCM
files can have a varied bitwidth the author probably wanted to cover all
bases.

> Version 1.0.0 came out some time ago, but I think this:
>
>     http://www.mega-nerd.com/libsndfile/version-1.html
>
> lists most of the changes. You should also look at the API docs:
>
>     http://www.mega-nerd.com/libsndfile/api.html

I'll download them and see what I can gleen.

Thanks again for getting back to me

TTFN

Paul

================================================================================

Date: Wed, 21 Jul 2004 18:20:29 +1000
From: Erik de Castro Lopo <erikd@fake-domain-name.com>
To: PFJ <paul@fake-domain-name.co.uk>
Subject: Re: Can you help with a problem?

On Wed, 21 Jul 2004 09:07:39 +0100
PFJ <paul@fake-domain-name.co.uk> wrote:

> I know, but the source code explicitly has SF_FORMAT_PCM which given the
> code afterwards would equate to one of the above, but given that PCM
> files can have a varied bitwidth the author probably wanted to cover all
> bases.

But surely the existing code does something like:

    sfinfo.format = SF_FORMAT_WAV | SF_FORMAT_PCM;
    sfinfo.pcmbitwidth = 16;

which can be directly translated to:

    sfinfo.format = SF_FORMAT_WAV | SF_FORMAT_PCM_16;

and the same for pcmbitwitdhs of 24 and 32. For pcmbitwidth of 8
you need to know that WAV files use SF_FORMAT_PCM_U8 and AIFF
files use SF_FORMAT_PCM_S8. Thats all there is to it.

Erik
-- 
+-----------------------------------------------------------+
  Erik de Castro Lopo      nospam@fake-domain-name.com
+-----------------------------------------------------------+
"Python addresses true pseudocode's two major failings: that it
isn't standardized, and it isn't executable."
- Grant R. Griffin  in comp.dsp

================================================================================

Subject: Re: Can you help with a problem?
From: PFJ <paul@fake-domain-name.co.uk>
To: Erik de Castro Lopo <erikd@fake-domain-name.com>
Date: Wed, 21 Jul 2004 09:50:55 +0100

Hi Erik,

> > I know, but the source code explicitly has SF_FORMAT_PCM which given the
> > code afterwards would equate to one of the above, but given that PCM
> > files can have a varied bitwidth the author probably wanted to cover all
> > bases.
>
> But surely the existing code does something like:
>
>     sfinfo.format = SF_FORMAT_WAV | SF_FORMAT_PCM;
>     sfinfo.pcmbitwidth = 16;

If only!

The actual code is this

int LoadSoundFile(char *filename, sound_p sound)
{
    SNDFILE *file;
    SF_INFO file_info;
    short *buffer_short = NULL;
    u_int8_t *buffer_8 = NULL;
    int16_t *buffer_16 = NULL;
    unsigned int i;

    /* Open the file and retrieve sample information. */
    file = sf_open_read(filename, &file_info);
    // I've sorted this one already - PFJ

    /* Make sure the format is acceptable. */
    if ((file_info.format & 0x0F) != SF_FORMAT_PCM) {
		printf("'%s' is not a PCM-based audio file.\n", filename);
		sf_close(file);
		return -1;
    }

    if ((file_info.pcmbitwidth == 8) && (file_info.channels == 1)) {
		sound->format = AL_FORMAT_MONO8;
    } else if ((file_info.pcmbitwidth == 8) && (file_info.channels == 2)) {
		sound->format = AL_FORMAT_STEREO8;
    } else if ((file_info.pcmbitwidth == 16) && (file_info.channels == 1)) {
		sound->format = AL_FORMAT_MONO16;
    } else if ((file_info.pcmbitwidth == 16) && (file_info.channels == 2)) {
		sound->format = AL_FORMAT_STEREO16;
    } else {
		printf("Unknown sample format in %s.\n", filename);
		sf_close(file);
		return -1;
    }

    /* Allocate buffers. */
    buffer_short = (short *)malloc(file_info.samples * file_info.channels * sizeof (short));

    buffer_8 = (u_int8_t *)malloc(file_info.samples * file_info.channels * file_info.pcmbitwidth / 8);

    buffer_16 = (int16_t *)buffer_8;

    if (buffer_short == NULL || buffer_8 == NULL) {
		printf("Unable to allocate enough memory for '%s'.\n", filename);
		goto error_cleanup;
    }

    /* Read the entire sound file. */
    if (sf_readf_short(file,buffer_short,file_info.samples) == (size_t)-1) {
		printf("Error while reading samples from '%s'.\n", filename);
		goto error_cleanup;
    }

<minor snip>

    /* Fill in the sound data structure. */
    sound->freq = file_info.samplerate;
    sound->size = file_info.samples * file_info.channels * file_info.pcmbitwidth / 8;

    /* Give our sound data to OpenAL. */
    alGenBuffers(1, &sound->name);
    if (alGetError() != AL_NO_ERROR) {
		printf("Error creating an AL buffer name for %s.\n", filename);
		goto error_cleanup;
    }

    alBufferData(sound->name, sound->format, buffer_8, sound->size,sound->freq);
    if (alGetError() != AL_NO_ERROR) {
		printf("Error sending buffer data to OpenAL for %s.\n", filename);
		goto error_cleanup;
    }

    /* Close the file and return success. */
    sf_close(file);
    free(buffer_short);
    free(buffer_8);

    return 0;

 error_cleanup:
    if (file != NULL) fclose(file);
    free(buffer_short);
    free(buffer_8);
    return -1;
}

As you can see, the PCM material in the listing will not currently
compile and for the other sndfile material, it probably won't either.

Any help would be appreciated.

TTFN

Paul

================================================================================

From: Erik de Castro Lopo <erikd@fake-domain-name.com>
To: PFJ <paul@fake-domain-name.co.uk>
Subject: Re: Can you help with a problem?
Date: Wed, 21 Jul 2004 19:36:46 +1000

On Wed, 21 Jul 2004 09:50:55 +0100
PFJ <paul@fake-domain-name.co.uk> wrote:

> Hi Erik,
> 
> > > I know, but the source code explicitly has SF_FORMAT_PCM which given the
> > > code afterwards would equate to one of the above, but given that PCM
> > > files can have a varied bitwidth the author probably wanted to cover all
> > > bases.
> > 
> > But surely the existing code does something like:
> > 
> >     sfinfo.format = SF_FORMAT_WAV | SF_FORMAT_PCM;
> >     sfinfo.pcmbitwidth = 16;
> 
> If only!

No, really.

Drop this completely:

>     /* Make sure the format is acceptable. */
>     if ((file_info.format & 0x0F) != SF_FORMAT_PCM) {
> 	printf("'%s' is not a PCM-based audio file.\n", filename);
> 	sf_close(file);
> 	return -1;
>     }

Replace this block:

>     if ((file_info.pcmbitwidth == 8) && (file_info.channels == 1)) {
> 	        sound->format = AL_FORMAT_MONO8;
>     } else if ((file_info.pcmbitwidth == 8) && (file_info.channels == 2)) {
>           sound->format = AL_FORMAT_STEREO8;
>     } else if ((file_info.pcmbitwidth == 16) && (file_info.channels == 1)) {
>           sound->format = AL_FORMAT_MONO16;
>     } else if ((file_info.pcmbitwidth == 16) && (file_info.channels == 2)) {
>           sound->format = AL_FORMAT_STEREO16;
>     } else {
>           printf("Unknown sample format in %s.\n", filename);
>           sf_close(file);
>           return -1;
>     }

with:

    int pcmbitwidth = 0;

    if (file_info.format & SF_FORMAT_SUBMASK != SF_FORMAT_PCM_16)
    { 	printf("'%s' is not a PCM-based audio file.\n", filename);
        sf_close(file);
        return -1;
        }

    if (file_info.channels < 1 || file_info.channels > 2)
    { 	printf("'%s' bad channel count.\n", filename);
        sf_close(file);
        return -1;
        }

    switch (file_info.format & SF_FORMAT_SUBMASK + file_info.channels << 16)
    {    case (SF_FORMAT_PCM_U8 + 1 << 16):
             sound->format = AL_FORMAT_MONO8;
             pcmbitwidth = 8;
             break;
         case (SF_FORMAT_PCM_U8 + 2 << 16):
             sound->format = AL_FORMAT_STEREO8;
             pcmbitwidth = 8;
             break;
         case (SF_FORMAT_PCM_16 + 1 << 16):
             sound->format = AL_FORMAT_MONO16;
             pcmbitwidth = 16;
             break;
         case (SF_FORMAT_PCM_16 + 2 << 16):
             sound->format = AL_FORMAT_STEREO16;
             pcmbitwidth = 16;
             break;
         default:
             printf("Unknown sample format in %s.\n", filename);
             sf_close(file);
             return -1;
         }

>     /* Allocate buffers. */
>     buffer_short = (short *)malloc(file_info.samples *
> 				   file_info.channels * 
> 				   sizeof (short));
> 
>     buffer_8 = (u_int8_t *)malloc(file_info.samples *
> 				  file_info.channels *
> 				  file_info.pcmbitwidth / 8);

Use pcmbitwidth as calculated above.

>     buffer_16 = (int16_t *)buffer_8;
> 
>     if (buffer_short == NULL || buffer_8 == NULL) {
> 	printf("Unable to allocate enough memory for '%s'.\n", filename);
> 	goto error_cleanup;
>     }
> 
>     /* Read the entire sound file. */
>     if (sf_readf_short(file,buffer_short,file_info.samples) == (size_t)- 1) {

Replace "(size_t) - 1" with " < 0".

> As you can see, the PCM material in the listing will not currently
> compile and for the other sndfile material, it probably won't either.

None of the changes above should have been very difficult to figure
out.

Erik
-- 
+-----------------------------------------------------------+
  Erik de Castro Lopo      nospam@fake-domain-name.com
+-----------------------------------------------------------+
Microsoft is finally bringing all of its Windows operating system families
under one roof. It will combine all of the features of CE, stability and
support of ME and the speed of NT.
It will be called Windows CEMENT...