The Media Kit Table of Contents The Media Kit Index

BSound

Derived from: (none)

Declared in: be/media/Sound.h

Library: libmedia.so

Allocation: Constructor only

Summary

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.


Hook Functions

  • BindTo()
  • Data()
  • Duration()
  • Format()
  • GetDataAt()
  • Size()
  • UnbindFrom()


    Constructor


    BSound()

                                                             
      

    BSound(void *data, size_t size,
          const media_raw_audio_format &format,
          bool freeWhenDone = false)
    BSound(const entry_ref *ref,
          bool loadIntoMemory = false)

    protected:
                                                             
      

    BSound(const media_raw_audio_format &format)

    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.


    Member Functions


    AcquireRef(), ReleaseRef(), RefCount()

                                                             
      

    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.


    BindTo(), UnbindFrom()

                                                             
      

    virtual status_t BindTo(BSoundPlayer *player,
          const media_raw_audio_format &format)
    virtual status_t UnbindFrom(BSoundPlayer *player)

    BindTo() binds the BSound to the specified player, using the given format. UnbindFrom() disassociates the BSound from the indicated player.

    RETURN CODES

    B_OK. No error.

    EAGAIN. (BindTo() only) You tried to bind to a new BSoundPlayer without first unbinding from the old one.

    B_BAD_VALUE. (UnbindFrom() only) You tried to unbind but didn't specify the same BSoundPlayer to which the BSound is currently bound.


    Data(), GetDataAt()

                                                             
      

    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.


    Duration(), Size()

                                                             
      

    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.


    Format()

                                                             
      

    virtual const media_raw_audio_format &Format(void) const

    Returns the audio data's format.


    GetDataAt() see Data()


    InitCheck()

                                                             
      

    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.


    RefCount() see RefCount()


    ReleaseRef() see AcquireRef()


    Size() see Duration()


    UnbindFrom() see BindTo()


    The Media Kit Table of Contents The Media Kit Index


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

    Copyright © 1999 Be, Inc. All rights reserved.

    Text last modified June 4, 1999.