BFileGameSound

Derived from: BStreamingGameSound
Declared in:  be/game/FileGameSound.h
Library: libgame.so
Allocation: Constructor only
Summary:  more...

If you want to play back audio from a disk file, such as background music, or low-priority sound effects, BFileGameSound is for you. Keep in mind that if the sound needs to play at precise moments, or latency is an issue, that BFileGameSound may not be appropriate for your needs.

Using BFileGameSound is easy, and it supports automatically looping sounds. The following code snippet starts up the theme music for the hot new game "Mystery Warriors From the Doomed Planet Z":

BFileGameSound themeSong("music/theme.aif", true); themeSong.StartPlaying();

This starts up a looped sound from the file music/theme.aif. If you want the theme to only play through once, just specify false instead of true for the looping argument to the BFileGameSound constructor.

You can pause the BFileGameSound by calling SetPaused():

themeSong.SetPaused(true, 0);

This pauses the sound, effective immediately. The pause can optionally be ramped, so that the sound slows down or speeds up to reach the new setting. For example:

themeSong.SetPaused(true, 2);

This causes the sound to slow down over the course of two seconds, until it's stopped.

The inverse is also possible:

themeSong.SetPaused(false, 0);

This resumes playback immediately. You can ramp the resume by specifying a non-zero value for the ramp time.

BFileGameSound uses the BMediaFile class to access the sound file. If BMediaFile can't identify the sound, the file is assumed to contain raw 44.1kHz, 16-bit stereo.

Constructor and Destructor

BFileGameSound()

BFileGameSound(const entry_ref *inFile,       bool looping = true,       BGameSoundDevice *device = NULL) BFileGameSound(const char *inFile,       bool looping = true,       BGameSoundDevice *device = NULL)

Prepares the object to play the specified sound file, which can be specified either by entry_ref or pathname in the inFile argument.

If the looping flag is true (which it is by default), the sound automatically loops back to the beginning and replays when the end of the sound is reached. This is useful for easily playing background music (for example).

In both cases, device specifies the sound device that should be used for playing the sound; NULL uses the default sound player.

Currently, device must always be NULL.

After instantiating the BFileGameSound object, you should call InitCheck() to determine whether or not the sound was successfully created.

~BFileGameSound

virtual ~BFileGameSound()

A typical destructor.

Member Functions

InitCheck()

status_t InitCheck(void) const

Returns a status_t indicating whether or not the object was successfully instantiated.

RETURN CODES

• B_OK. The sound was successfully initialized.

• B_ERROR. Unable to create a sound player.

• B_NO_MEMORY. Can't get enough memory to preload the sound.

• Other errors. The sound player may return errors.

IsPaused() see SetPaused()

Preload()

status_t Preload(void)

Preload() preloads enough of the sound file into memory that starting playback of the sound won't cuase a delay while the first chunk of data is fetched from disk.

RETURN CODES

• B_OK. Preloading was successful.

• Port errors. Unable to communicate with the streaming sound port.

SetPaused() , IsPaused()

status_t SetPaused(bool isPaused, bigtime_t rampTime) int32 IsPaused(void)

SetPaused() pauses if isPaused is true, and unpauses if isPaused is false. If rampTime is nonzero, the sound ramps up to speed (or down to stopped) instead of instantly changing state. The number of microseconds specified by rampTime indicates how long the change should take to complete.

IsPaused() returns value indicating whether or not the sound is paused, or if a pause is in process of being initiated (if ramping is underway). The result is one of these values:

• B_NOT_PAUSED—the sound is playing normally.

• B_PAUSE_IN_PROGRESS—the sound is ramping toward or away from a paused state.

• B_PAUSED—the sound is paused.

Because these constants are members of the BFileGameSound class, be sure to refer to them as BFileGameSound::B_NOT_PAUSED and so forth.

RETURN CODES

• B_OK. The pause occurred without error.

• EALREADY. The sound is already in the requested state.