Add BFileGameSound class documentation

docs/user/game/FileGameSound.dox

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2012 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		John Scipione, jscipione@gmail.com
+ *
+ * Corresponds to:
+ *		src/kits/game/FileGameSound.cpp	hrev45076
+ *		src/kits/game/FileGameSound.h	hrev45076
+ */
+
+
+/*!
+	\file FileGameSound.h
+	\brief Provides the FileGameSound class.
+*/
+
+
+/*!
+	\class BFileGameSound
+	\ingroup game
+	\ingroup libbe
+	\brief Provides the ability to playback audio from a sound file on disk.
+*/
+
+
+/*!
+	\fn BFileGameSound::BFileGameSound(const entry_ref *file, bool looping,
+		BGameSoundDevice *device)
+	\brief Creates and initializes a BFileGameSound object from an
+		   \c entry_ref allowing you to play the specified sound file.
+
+	If \a looping is \c true, the sound automatically replays from the
+	beginning once the end is reached. This is useful for playing
+	background music in a loop.
+
+	You can specify the sound devise to use by setting the \a device
+	parameter. Setting \a device to \c NULL uses the default sound device.
+
+	\param file The entry ref pointing to the sound file on disk.
+	\param looping Whether or not to repeat the sound in a loop.
+	\param device The sound device to use to play the sound, use \c NULL for
+		   default.
+*/
+
+
+/*!
+	\fn BFileGameSound::BFileGameSound(const char *file, bool looping,
+		BGameSoundDevice *device)
+	\brief Creates and initializes a BFileGameSound object from a file path
+		   allowing you to play the specified sound file.
+
+	If \a looping is \c true, the sound automatically replays from the
+	beginning once the end is reached. This is useful for playing
+	background music in a loop.
+
+	You can specify the sound devise to use by setting the \a device
+	parameter. Setting \a device to \c NULL uses the default sound device.
+
+	\param file The path of the sound file on disk.
+	\param looping Whether or not to repeat the sound in a loop.
+	\param device The sound device to use to play the sound, use \c NULL for
+		   default.
+*/
+
+
+/*!
+	\fn BFileGameSound::~BFileGameSound()
+	\brief Destroys the BFileGameSound object.
+*/
+
+
+/*!
+	\fn BGameSound* BFileGameSound::Clone() const
+	\brief Not implemented, always returns \c NULL.
+*/
+
+
+/*!
+	\fn status_t BFileGameSound::StartPlaying()
+	\brief Plays the sound file.
+
+	\returns A status code, \c B_OK on success or an error code on error.
+*/
+
+
+/*!
+	\fn status_t BFileGameSound::StopPlaying()
+	\brief Stops playback of the sound file.
+
+	\returns A status code, \c B_OK on success or an error code on error.
+*/
+
+
+/*!
+	\fn status_t BFileGameSound::Preload()
+	\brief Preload the sound file into memory so that playback won't be delayed.
+
+	\returns A status code, \c B_OK on success or an error code if we were
+			 unable to communicate with the sound port.
+*/
+
+
+/*!
+	\fn void BFileGameSound::FillBuffer(void *inBuffer, size_t inByteCount)
+	\brief Fill a buffer with sound data.
+
+	\param inBuffer The buffer to fill.
+	\param inByteCount The number of bytes to fill buffer with.
+*/
+
+
+/*!
+	\fn status_t BFileGameSound::SetPaused(bool isPaused, bigtime_t rampTime)
+	\brief Pauses playback if \a isPaused is \c true or resumes play if
+		   \a isPaused is \c false.
+
+	\param isPaused \c true to pause playback, \c false to resume playback.
+	\param rampTime Determines how long the change in playback state should
+		   take to complete in microseconds. Set to 0 for an instantaneous
+		   change.
+
+	\returns A status code indicating the current playback status.
+	\retval B_OK The operating was successful.
+	\retval EALREADY Already in the requested playback state.
+*/