docs/user/game/FileGameSound.dox

   1 /*
   2  * Copyright 2012 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              John Scipione, jscipione@gmail.com
   7  *
   8  * Corresponds to:
   9  *              src/kits/game/FileGameSound.cpp hrev45076
  10  *              src/kits/game/FileGameSound.h   hrev45076
  11  */
  12
  13
  14 /*!
  15         \file FileGameSound.h
  16         \ingroup game
  17         \ingroup libbe
  18         \brief Provides the BFileGameSound class.
  19 */
  20
  21
  22 /*!
  23         \class BFileGameSound
  24         \ingroup game
  25         \ingroup libbe
  26         \brief Playback audio from a sound file on disk.
  27
  28         \since BeOS R5
  29 */
  30
  31
  32 /*!
  33         \fn BFileGameSound::BFileGameSound(const entry_ref* file, bool looping,
  34                 BGameSoundDevice* device)
  35         \brief Creates and initializes a BFileGameSound object from an
  36                    \c entry_ref allowing you to play the specified sound file.
  37
  38         If \a looping is \c true, the sound automatically replays from the
  39         beginning once the end is reached. This is useful for playing
  40         background music in a loop.
  41
  42         You can specify the sound devise to use by setting the \a device
  43         parameter. Setting \a device to \c NULL uses the default sound device.
  44
  45         \param file The entry ref pointing to the sound file on disk.
  46         \param looping Whether or not to repeat the sound in a loop.
  47         \param device The sound device to use to play the sound, use \c NULL for
  48                    default.
  49
  50         \since BeOS R5
  51 */
  52
  53
  54 /*!
  55         \fn BFileGameSound::BFileGameSound(const char* file, bool looping,
  56                 BGameSoundDevice* device)
  57         \brief Creates and initializes a BFileGameSound object from a file path
  58                    allowing you to play the specified sound file.
  59
  60         If \a looping is \c true, the sound automatically replays from the
  61         beginning once the end is reached. This is useful for playing
  62         background music in a loop.
  63
  64         You can specify the sound devise to use by setting the \a device
  65         parameter. Setting \a device to \c NULL uses the default sound device.
  66
  67         \param file The path of the sound file on disk.
  68         \param looping Whether or not to repeat the sound in a loop.
  69         \param device The sound device to use to play the sound, use \c NULL for
  70                default.
  71
  72         \since BeOS R5
  73 */
  74
  75
  76 /*!
  77         \fn BFileGameSound::~BFileGameSound()
  78         \brief Destroys the BFileGameSound object.
  79
  80         \since BeOS R5
  81 */
  82
  83
  84 /*!
  85         \fn BGameSound* BFileGameSound::Clone() const
  86         \brief Not implemented, always returns \c NULL.
  87
  88         \since BeOS R5
  89 */
  90
  91
  92 /*!
  93         \fn status_t BFileGameSound::StartPlaying()
  94         \brief Plays the sound file.
  95
  96         \returns A status code, \c B_OK on success or an error code on error.
  97
  98         \since BeOS R5
  99 */
 100
 101
 102 /*!
 103         \fn status_t BFileGameSound::StopPlaying()
 104         \brief Stops playback of the sound file.
 105
 106         \returns A status code, \c B_OK on success or an error code on error.
 107
 108         \since BeOS R5
 109 */
 110
 111
 112 /*!
 113         \fn status_t BFileGameSound::Preload()
 114         \brief Preload the sound file into memory so that playback won't be delayed.
 115
 116         \returns A status code, \c B_OK on success or an error code if we were
 117                  unable to communicate with the sound port.
 118
 119         \since BeOS R5
 120 */
 121
 122
 123 /*!
 124         \fn void BFileGameSound::FillBuffer(void* inBuffer, size_t inByteCount)
 125         \brief Fill a buffer with sound data.
 126
 127         \param inBuffer The buffer to fill.
 128         \param inByteCount The number of bytes to fill buffer with.
 129
 130         \since BeOS R5
 131 */
 132
 133
 134 /*!
 135         \fn status_t BFileGameSound::SetPaused(bool isPaused, bigtime_t rampTime)
 136         \brief Pauses playback if \a isPaused is \c true or resumes play if
 137                \a isPaused is \c false.
 138
 139         \param isPaused \c true to pause playback, \c false to resume playback.
 140         \param rampTime Determines how long the change in playback state should
 141                take to complete in microseconds. Set to 0 for an instantaneous
 142                change.
 143
 144         \returns A status code.
 145         \retval B_OK The playback state was updated.
 146         \retval EALREADY Already in the requested playback state.
 147
 148         \since BeOS R5
 149 */
 150
 151
 152 /*!
 153         \fn int32 BFileGameSound::IsPaused()
 154         \brief Returns the current playback status.
 155
 156         \returns An integer indicating the current playback status.
 157         \retval B_NOT_PAUSED Sound is playing.
 158         \retval B_PAUSE_IN_PROGRESS The sound is transitioning to or from a paused state.
 159         \retval B_PAUSED Sound is paused.
 160
 161         \since BeOS R5
 162 */