driver: Update doxygen documentation

This lets me remove the Audio Driver section of the DESIGN document.

Signed-off-by: Anna Schumaker <Anna@OcarinaProject.net>

DESIGN

@@ -66,81 +66,6 @@ Callbacks:
 
 
 
-Audio Driver:
-	The audio driver creates a way to fake audio playback for testing.  This
-	will allow for more accurate tests, since I will know in advance what
-	values are returned to the Audio layer.  This layer will derive from
-	the Driver class to implement either the GSTDriver or the TestDriver.
-
-- Seconds -> Nanoseconds conversion:
-	static const unsigned long O_SECOND = 1000000000;
-
-- Driver:
-	class Driver {
-	protected:
-		void (*on_eos)();
-
-	public:
-		Driver();
-		~Driver();
-		virtual void init(int *, char ***, void (*)(), void (*)()) = 0;
-
-		virtual void load(const std::string &) = 0;
-		virtual void play() = 0;
-		virtual void pause() = 0;
-		virtual void is_playing() = 0;
-
-		virtual void seek_to(long) = 0;
-		virtual long position() = 0;
-		virtual long duration() = 0
-	};
-
-- Driver API:
-	void Driver :: Driver();
-		Initialize the audio driver.  This involves setting up a GST
-		Bus in the GSTDriver case.
-
-	void Driver :: ~Driver();
-		In the GSTDriver case, call gst_deinit() to avoid memory leak
-		false positives.
-
-	void Driver :: init(int argc, char **argv, void (*eos_cb)(),
-			    void (*error_cb)());
-		The GSTDriver will use this function to set up the playbin2.
-		When an end-of-stream message is received, call eos_cb().
-		If there is an error, call error_cb();
-
-	void Driver :: load(const std::string &file);
-		Load file for playback, but do not begin playback yet.
-
-	void Driver :: play();
-		Start playback.  Return true if the state change operation
-		succeeds, false otherwise.
-
-	void Driver :: pause();
-		Pause playback.  Return true if the state change operation
-		succeeds, false otherwise.
-
-	bool Driver :: is_playing();
-		Return true if the player is currently playing, false otherwise.
-
-	void Driver :: seek_to(long pos);
-		Change playback position in the current track in nanoseconds.
-
-	long Driver :: position();
-		Return the current position in the track in nanoseconds.
-
-	long Driver :: duration();
-		Return the duration of the track in nanoseconds.
-
-- API:
-	Driver *driver :: get_driver();
-		Return the current driver to be used for audio playback.  This
-		could be either the GSTDriver or the TestDriver depending on
-		if CONFIG_TEST is set when compiling.
-
-
-
 Audio:
 	The audio layer uses the configured driver to control audio playback.
 

core/driver.cpp

@@ -111,9 +111,9 @@ bool GSTDriver :: is_playing()
 	return state == GST_STATE_PLAYING;
 }
 
-void GSTDriver :: seek_to(long pos)
+void GSTDriver :: seek_to(long offset)
 {
-	gst_element_seek_simple(player, GST_FORMAT_TIME, GST_SEEK_FLAG_FLUSH, pos);
+	gst_element_seek_simple(player, GST_FORMAT_TIME, GST_SEEK_FLAG_FLUSH, offset);
 }
 
 long GSTDriver :: position()

include/core/driver.h

@@ -12,61 +12,53 @@ static const unsigned long O_SECOND = 1000000000;
 
 
 /**
- * Base class for different audio drivers.
+ * The audio driver class gives us an interface for using multiple
+ * audio frameworks for audio playback.
  */
 class Driver {
 protected:
-	/**
-	 * End-of-stream callback function.
-	 */
-	void (*on_eos)();
-
-	/**
-	 * Error handling callback function.
-	 */
-	void (*on_error)();
+	void (*on_eos)   (); /**< End-of-stream callback function.   */
+	void (*on_error) (); /**< Error handling callback function.  */
 
 public:
-	/**
-	 * Default Driver constructor.
-	 */
-	Driver();
+	Driver();  /**< Default Driver constructor. */
+	~Driver(); /**< Driver destructor.          */
 
 	/**
-	 * Driver destructor.
-	 */
-	~Driver();
-
-	/**
-	 * Initialize a driver
+	 * Initialize an audio driver.
+	 *
 	 * @param  argc  Argc passed to the application's main() function.
 	 * @param  argv  Argv passed to the applicaiton's main() function.
 	 * @param  eos_cb  End-of-stream callback function.
 	 * @param  error_cb  Callback function used when the audio library encounters an error.
 	 */
-	virtual void init(int *, char ***, void (*)(), void (*)()) = 0;
+	virtual void init(int *argc, char ***argv, void (*eos_cb)(), void (*error_cb)()) = 0;
 
 
 	/**
-	 * Load an audio file for playback.
+	 * Loads an audio file for playback.
+	 *
 	 * @param  file  Filepath of the track to load.
 	 */
-	virtual void load(const std::string &) = 0;
+	virtual void load(const std::string &file) = 0;
 
 	/**
 	 * Called to begin playback on the currently loaded track.
+	 *
 	 * @return True if playback state was changed successfully, false otherwise.
 	 */
 	virtual bool play() = 0;
 
 	/**
 	 * Called to pause playback on the currently loaded track.
+	 *
 	 * @return True if playback state was changed successfully, false otherwise.
 	 */
 	virtual bool pause() = 0;
 
 	/**
 	 * Called to check if the audio library is currently playing a track.
+	 *
 	 * @return True if audio library is playing, false otherwise.
 	 */
 	virtual bool is_playing() = 0;
@@ -74,18 +66,21 @@ public:
 
 	/**
 	 * Seek to a specific position in the current track.
+	 *
 	 * @param  offset  Position from the beginning of the track where we will seek to, in nanoseconds.
 	 */
-	virtual void seek_to(long) = 0;
+	virtual void seek_to(long offset) = 0;
 
 	/**
 	 * Return the current position of the playback.
+	 *
 	 * @return The current playback position, in nanoseconds.
 	 */
 	virtual long position() = 0;
 
 	/**
 	 * Return the duration of the currently loaded track.
+	 *
 	 * @return The duration of the current track, in nanoseconds.
 	 */
 	virtual long duration() = 0;
@@ -212,6 +207,7 @@ namespace driver
 
 	/**
 	 * Called to access an audio driver.
+	 *
 	 * @return The current driver used by the application.
 	 */
 	Driver *get_driver();