Derived from: (none)
Declared in: be/media/Sound.h
Library: libmedia.so
Allocation: Constructor only
The BSound class represents a raw sound, either in memory or on disk. Once a BSound has been instantiated, it can be played by using the BSoundPlayer class, or read by calling the GetDataAt() function.
See the BSoundPlayer class for examples.
BSound(void *data, size_t size,
const media_raw_audio_format &format,
bool freeWhenDone = false)
BSound(const entry_ref *ref,
bool loadIntoMemory = false)
Prepares the BSound object for use by associating it with either a raw sound in memory or a raw sound file on disk.
The first form of the constructor accepts a reference to a buffer in the data argument; this buffer contains size bytes of raw audio data. The audio is assumed to be in the specified format. If freeWhenDone is true, the BSound will release the memory pointed to by data when the BSound object is deleted.
The second form of the constructor accepts a reference to an audio file in ref. If loadIntoMemory is true, the file is read into memory when the BSound is constructed, otherwise, it's read from disk as necessary when GetDataAt() is called to read the sound's data (such as when a BSoundPlayer object is playing the sound).
|
Sounds larger than 3 MB aren't loaded into memory, even if you specify true for loadIntoMemory; this prevents an application from inadvertantly stress-testing the virtual memory system. |
After instantiating a BSound object, you should always call InitCheck() before calling any other functions, to be sure no errors occurred.
BSound *AcquireRef(void)
bool ReleaseRef(void)
int32 RefCount(void) const
AcquireRef() increments the BSound object's reference count.
ReleaseRef() decrements the BSound object's reference count. If all references are finished (the reference count reaches 1), the BSound is deleted, and false is returned. Otherwise, this function returns true.
RefCount() returns the number of references to the BSound object.
 |
The reference count returned by RefCount() shouldn't be used for any important functionality; this value is volatile and may have changed by the time this function returns. |
RETURN CODES
B_OK. The item was added successfully.
B_NO_MEMORY. Not enough memory to add the item to the list.
virtual const void *Data(void) const
virtual bool GetDataAt(off_t offset,
void *intoBuffer, size_t bufferSize,
size_t *outSize)
Data() returns a pointer to the audio data buffer. This returns NULL if the audio isn't loaded into memory.
|
Even if you specify in the constructor that you want the sound loaded into memory, it's possible that the sound may still be on disk instead of in memory (if the sound is too large to load into memory). Unless you're certain the sound won't be on disk, you should be prepared to handle the possibility that NULL will be returned. |
GetDataAt() fills the buffer specified by intoBuffer with up to bufferSize bytes of data, starting at the specified offset into the sound. On return, outSize is set to the number of bytes of data actually placed in the buffer. This function can read data from the sound whether it's in memory or on disk. Returns true if there's more data to read beyond what was read, otherwise returns false.
virtual bigtime_t Duration(void) const
virtual off_t Size(void) const
Duration() returns the duration of the sound in microseconds.
Size() returns the size of the sound in bytes.
virtual const media_raw_audio_format &Format(void) const
Returns the audio data's format.
status_t InitCheck(void)
Returns the error code of the error that occurred while instantiating the BSound object.
RETURN CODES
B_OK. The BSound was instantiated without error.
B_ERROR. An error occurred while preloading the audio data.
B_MEDIA_BAD_FORMAT. The sound file's format couldn't be identified, or is unsupported.
B_NO_MEMORY. Can't allocate buffer memory.
File errors. An error occurred while trying to locate and identify the audio file.
The Be Book, in lovely HTML, for BeOS Release 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified November 2, 1998.