Changeset a8e87da in mainline for uspace/app/wavplay/dplay.c

Timestamp:

2013-04-10T18:49:43Z (12 years ago)

Author:

Jan Vesely <jano.vesely@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

b1dfe13

Parents:

76e863c

Message:

wavplay: comments

File:

• uspace/app/wavplay/dplay.c (modified) (15 diffs)

uspace/app/wavplay/dplay.c

@@ -52 +52 @@
 #define DEFAULT_FRAGMENTS 2
 
+/** Playback helper structure */
 typedef struct {
         struct {
@@ -66 +67 @@
 } playback_t;
 
+/**
+ * Initialize playback helper structure.
+ * @param pb Pointer to helper structure to initialize
+ * @param sess Pointer to audio device IPC session
+ * @return
+ */
 static void playback_initialize(playback_t *pb, audio_pcm_sess_t *sess)
 {
@@ -80 +87 @@
 }
 
-
+/**
+ * Fragment playback callback function.
+ * @param iid IPC call id.
+ * @param icall Pointer to the call structure
+ * @param arg Argument, pointer to the playback helper function
+ */
 static void device_event_callback(ipc_callid_t iid, ipc_call_t *icall, void* arg)
 {
@@ -125 +137 @@
 }
 
+/**
+ * Start event based playback.
+ * @param pb Playback helper structure.
+ */
 static void play_fragment(playback_t *pb)
 {
@@ -166 +182 @@
 }
 
+/**
+ * Count occupied space in a cyclic buffer.
+ * @param pb Playback helper structure.
+ * @param pos read pointer position.
+ * @return Occupied space size.
+ */
 static size_t buffer_occupied(const playback_t *pb, size_t pos)
 {
@@ -176 +198 @@
 }
 
+/**
+ * Count available space in a cyclic buffer.
+ * @param pb Playback helper structure.
+ * @param pos read pointer position.
+ * @return Free space size.
+ */
 static size_t buffer_avail(const playback_t *pb, size_t pos)
 {
@@ -185 +213 @@
 }
 
+/**
+ * Size of the space between write pointer and the end of a cyclic buffer
+ * @param pb Playback helper structure.
+ */
 static size_t buffer_remain(const playback_t *pb)
 {
@@ -191 +223 @@
 }
 
+/**
+ * Move write pointer forward. Wrap around the end.
+ * @param pb Playback helper structure.
+ * @param bytes NUmber of bytes to advance.
+ */
 static void buffer_advance(playback_t *pb, size_t bytes)
 {
@@ -202 +239 @@
         printf("%.2lu:%.6lu   "f, time.tv_sec % 100, time.tv_usec, __VA_ARGS__)
 
-
+/**
+ * Start playback using buffer position api.
+ * @param pb Playback helper function.
+ */
 static void play(playback_t *pb)
 {
@@ -217 +257 @@
         do {
                 size_t available = buffer_avail(pb, pos);
-                /* Writing might need wrap around the end */
+                /* Writing might need wrap around the end,
+                 * read directly to device buffer */
                 size_t bytes = fread(pb->buffer.write_ptr, sizeof(uint8_t),
                     min(available, buffer_remain(pb)), pb->source);
@@ -225 +266 @@
                     pb->buffer.write_ptr - pb->buffer.base);
                 available -= bytes;
+
+                /* continue if we wrapped around the end */
                 if (available) {
                         bytes = fread(pb->buffer.write_ptr,
@@ -254 +297 @@
                     pcm_format_size_to_usec(to_play, &pb->f);
 
+                /* Compute delay time */
                 const useconds_t real_delay = (usecs > work_time)
                     ? usecs - work_time : 0;
@@ -260 +304 @@
                 if (real_delay)
                         async_usleep(real_delay);
+                /* update buffer position */
                 const int ret = audio_pcm_get_buffer_pos(pb->device, &pos);
                 if (ret != EOK) {
@@ -265 +310 @@
                 }
                 getuptime(&time);
+
+                /* we did not use all the space we had,
+                 * that is the end */
                 if (available)
                         break;
@@ -272 +320 @@
 }
 
+/**
+ * Play audio file usign direct device access.
+ * @param device The device.
+ * @param file The file.
+ * @return Error code.
+ */
 int dplay(const char *device, const char *file)
 {