comparison projects/basic_passthru/render.cpp @ 285:5433c83ce04e Doxy prerelease

Doxygen content added to more project render.cpp files and amended in others.

  *  Created on: Oct 24, 2014
  *      Author: parallels
  */
 
 /**
-\example 1_basic_audio_passthrough
+\example 1_basic_audio_analog_passthrough
 
-Audio passthrough: input to output
+Audio and analog passthrough: input to output
 -----------------------------------------
 
-This sketch demonstrates the simplest possible case of using audio: it passes 
-audio input straight to audio output.
+This sketch demonstrates how to read from and write to the audio and analog input and output buffers.
 
-Note the nested `for` loop structure. You will see this in all Bela projects. The 
-first `for` loop cycles through the audio frames, the second through each of the 
-audio channels (in this case left 0 and right 1).
+In `render()` you'll see a nested for loop structure. You'll see this in all Bela projects. 
+The first for loop cycles through `audioFrames`, the second through 
+`audioChannels` (in this case left 0 and right 1).
+
+You can access any information about current audio and sensor settings you can do the following: 
+`context->name_of_item`. For example `context->audioChannels` returns current number of channels,
+`context->audioFrames` returns the current number of audio frames, 
+`context->audioSampleRate` returns the audio sample rate.
+
+You can look at all the information you can access in ::BeagleRTContext.
+
+Reading and writing from the audio buffers
+------------------------------------------
+
+The simplest way to read samples from the audio input buffer is with
+`audioReadFrame()` which we pass three arguments context, current audio 
+frame and current channel. In this example we have 
+`audioReadFrame(context, n, ch)` where both `n` and `ch` are provided by 
+the nested for loop structure.
+
+We can write samples to the audio output buffer in a similar way using 
+`audioWriteFrame()`. This has a fourth argument which is the value of the output.
+For example `audioWriteFrame(context, n, ch, value_to_output)`.
+
+Reading and writing from the analog buffers
+-------------------------------------------
+
+The same is true for `analogReadFrame()` and `analogWriteFrame()`.
+
+Note that for the analog channels we write to and read from the buffers in a separate set 
+of nested for loops. This is because the they are sampled at half audio rate by default. 
+The first of these for loops cycles through `analogFrames`, the second through
+`analogChannels`.
+
+By setting `audioWriteFrame(context, n, ch, audioReadFrame(context, n, ch))` and
+`analogWriteFrame(context, n, ch, analogReadFrame(context, n, ch))` we have a simple 
+passthrough of audio input to output and analog input to output.
 
 
-We write samples to the audio output buffer like this: 
-`context->audioOut[n * context->audioChannels + ch]` where `n` is the current audio 
-frame and `ch` is the current channel, both provided by the nested for loop structure.
-
-We can access samples in the audio input buffer in a similar way, like this: 
-`context->audioIn[n * context->audioChannels + ch]`.
-
-So a simple audio pass through is achieved by setting output buffer equal to 
-input buffer: 
-`context->audioOut[n * context->audioChannels + ch] = context->audioIn[n * context->audioChannels + ch]`.
+It is also possible to address the buffers directly like this: 
+`context->audioOut[n * context->audioChannels + ch]`.
 
 
 */
 
 

 			// Or using the macros:
 			audioWriteFrame(context, n, ch, audioReadFrame(context, n, ch));
 		}
 	}
 
-	// Same with analog channelss
+	// Same with analog channels
 	for(unsigned int n = 0; n < context->analogFrames; n++) {
 		for(unsigned int ch = 0; ch < context->analogChannels; ch++) {
 			// Two equivalent ways to write this code
 
 			// The long way, using the buffers directly: