The Game Kit: BFileGameSound

The Game Kit Table of Contents | The Game Kit Index

# BFileGameSound

Derived from: BStreamingGameSound

Declared in: be/game/FileGameSound.h

Library: libgame.so

Allocation: Constructor only

###### Summary

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.

The Game Kit Table of Contents | The Game Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..