Documentation for OSCSender and OSCReceiver

IDE/public/index.html

@@ -431,49 +431,31 @@ <h1>Documentation</h1>
 								</li>
 								<li>
 									<input type="checkbox" class="docs" id="tit4">
-									<label for="tit4" class="docSectionHeader">OSC Server</label>
-									<ul id="OSCServerDocs" class="subsections">
+									<label for="tit4" class="docSectionHeader">OSC Receiver</label>
+									<ul id="OSCReceiverDocs" class="subsections">
 									</ul>
 								</li>
 								<li>
 									<input type="checkbox" class="docs" id="tit5">
-									<label for="tit5" class="docSectionHeader">OSC Client</label>
-									<ul id="OSCClientDocs" class="subsections">
+									<label for="tit5" class="docSectionHeader">OSC Sender</label>
+									<ul id="OSCSenderDocs" class="subsections">
 									</ul>
 								</li>
 								<li>
 									<input type="checkbox" class="docs" id="tit6">
-									<label for="tit6" class="docSectionHeader">OSC Message Factory</label>
-									<ul id="OSCMessageFactoryDocs" class="subsections">
-									</ul>
-								</li>
-								<li>
-									<input type="checkbox" class="docs" id="tit7">
-									<label for="tit7" class="docSectionHeader">UDP Server</label>
-									<ul id="UdpServerDocs" class="subsections">
-									</ul>
-								</li>
-								<li>
-									<input type="checkbox" class="docs" id="tit8">
-									<label for="tit8" class="docSectionHeader">UDP Client</label>
-									<ul id="UdpClientDocs" class="subsections">
-									</ul>
-								</li>
-								<li>
-									<input type="checkbox" class="docs" id="tit9">
-									<label for="tit9" class="docSectionHeader">Midi</label>
+									<label for="tit6" class="docSectionHeader">Midi</label>
 									<ul id="MidiDocs" class="subsections">
 									</ul>
 								</li>
 								<li>
-									<input type="checkbox" class="docs" id="tit10">
-									<label for="tit10" class="docSectionHeader">Midi Parser</label>
+									<input type="checkbox" class="docs" id="tit7">
+									<label for="tit7" class="docSectionHeader">Midi Parser</label>
 									<ul id="MidiParserDocs" class="subsections">
 									</ul>
 								</li>
 								<li>
-									<input type="checkbox" class="docs" id="tit11">
-									<label for="tit11" class="docSectionHeader">WriteFile data logging</label>
+									<input type="checkbox" class="docs" id="tit8">
+									<label for="tit8" class="docSectionHeader">WriteFile data logging</label>
 									<ul id="WriteFileDocs" class="subsections">
 									</ul>
 								</li>

dev/src/Views/DocumentationView.js

@@ -4,11 +4,8 @@ var apiFuncs = ['setup', 'render', 'cleanup', 'Bela_createAuxiliaryTask', 'Bela_
 
 var classes = [
 	'Scope',
-	'OSCServer',
-	'OSCClient',
-	'OSCMessageFactory',
-	'UdpServer',
-	'UdpClient',
+	'OSCReceiver',
+	'OSCSender',
 	'Midi',
 	'MidiParser',
 	'WriteFile'

include/OSCClient.h

@@ -8,7 +8,7 @@
 #include <queue>
 
 /**
- * \brief OSCMessageFactory provides functions for building OSC messages within Bela.
+ * \brief OSCMessageFactory is deprecated, please use OSCSender instead
  *
  * This class is safe to use on the audio thread.
  *
@@ -70,7 +70,7 @@ class OSCMessageFactory{
 };
 
 /**
- * \brief OSCClient provides functions for sending OSC messages from Bela.
+ * \brief OSCClient is deprecated, please use OSCSender instead
  *
  * Care must be taken to use the correct methods while running on the audio thread to
  * prevent Xenomai mode switches and audio glitches.

include/OSCReceiver.h

@@ -9,11 +9,42 @@
 #define OSCRECEIVER_POLL_MS 5
 #define OSCRECEIVER_BUFFERSIZE 65536
 
+/**
+ * \brief OSCReceiver provides functions for receiving OSC messages in Bela.
+ *
+ * When an OSC message is received over UDP on the port number passed to 
+ * OSCReceiver::setup() it is passed in the form of an oscpkt::Message
+ * to the onreceive callback. This callback, which must be passed to
+ * OSCReceiver::setup() by the user, is run off the audio thread at 
+ * non-realtime priority.
+ *
+ * For documentation of oscpkt see http://gruntthepeon.free.fr/oscpkt/
+ */
 class OSCReceiver{
     public:
         OSCReceiver(){}
-
-        void setup(int port, void (*callback)(oscpkt::Message* msg));
+
+        /**
+		 * \brief Initiliases OSCReceiver
+		 *
+		 * Must be called once during setup()
+		 *
+		 * @param port the port number used to receive OSC messages
+		 * @param onreceive the callback function which received OSC messages are passed to
+		 *
+		 */
+        void setup(int port, void (*onreceive)(oscpkt::Message* msg));
+
+        /**
+		 * \brief Blocks execution until an OSC message is received
+		 *
+		 * This optional method can be used to block execution until an OSC message is 
+		 * received. It should only be used in setup() or from an auxiliary thread, if
+		 * used from render() it will cause mode switches. 
+		 *
+		 * @param timeout the time in milliseconds to block for if no messages are received. Null will block indefinitely.
+		 * 
+		 */
         int waitForMessage(int timeout_ms);
 
     private:

include/OSCSender.h

@@ -8,43 +8,144 @@
 
 #define OSCSENDER_DEFAULT_STREAMING_BUFFERSIZE 1024
 
+/**
+ * \brief OSCSender provides functions for sending OSC messages from Bela.
+ *
+ * Functionality is provided for sending messages with int, float, bool, 
+ * std::string and binary blob arguments. Sending a stream of floats is
+ * also supported.
+ *
+ * Uses oscpkt (http://gruntthepeon.free.fr/oscpkt/) underneath
+ */
 class OSCSender{
 	public:
 		OSCSender();
 
+        /**
+		 * \brief Initialises OSCSender
+		 *
+		 * Must be called once during setup()
+		 *
+		 * If address is left blank it will default to localhost (127.0.0.1)
+		 *
+		 * @param port the UDP port number used to send OSC messages
+		 * @param address the IP address OSC messages are sent to (defaults to 127.0.0.1)
+		 *
+		 */
 		void setup(int port, std::string ip_address=std::string("127.0.0.1"));
 
+		/**
+		 * \brief Creates a new OSC message
+		 *
+		 * @param address the address which the OSC message will be sent to
+		 *
+		 */
 		OSCSender &newMessage(std::string address);
+		/**
+		 * \brief Adds an int argument to a message
+		 *
+		 * Can optionally be chained with other calls to add(), newMessage() and
+		 * send() or sendNow()
+		 *
+		 * @param payload the argument to be added to the message
+		 */
 		OSCSender &add(int payload);
+		/**
+		 * \brief Adds a float argument to a message
+		 *
+		 * Can optionally be chained with other calls to add(), newMessage() and
+		 * send() or sendNow()
+		 *
+		 * @param payload the argument to be added to the message
+		 */
 		OSCSender &add(float payload);
+		/**
+		 * \brief Adds a string argument to a message
+		 *
+		 * Can optionally be chained with other calls to add(), newMessage() and
+		 * send() or sendNow()
+		 *
+		 * @param payload the argument to be added to the message
+		 */
 		OSCSender &add(std::string payload);
+		/**
+		 * \brief Adds a boolean argument to a message
+		 *
+		 * Can optionally be chained with other calls to add(), newMessage() and
+		 * send() or sendNow()
+		 *
+		 * @param payload the argument to be added to the message
+		 */
 		OSCSender &add(bool payload);
+		/**
+		 * \brief Adds a binary blob argument to a message
+		 *
+		 * Copies binary data into a buffer, which is sent as a binary blob.
+		 * Can optionally be chained with other calls to add(), newMessage() and
+		 * send() or sendNow()
+		 *
+		 * @param ptr pointer to the data to be sent
+		 * @param num_bytes the number of bytes to be sent
+		 */
 		OSCSender &add(void *ptr, size_t num_bytes);
-		void sendNow();
+		/**
+		 * \brief Sends the message
+		 *
+		 * After creating a message with newMessage() and adding arguments to it
+		 * with add(), the message is sent with this function. It is safe to call
+		 * from the audio thread.
+		 *
+		 */
 		void send();
+		/**
+		 * \brief Blocks execution until message is sent
+		 *
+		 * As an alternative to send(), sendNow() blocks until the message is sent
+		 * and should only be used from setup() or a seperate thread.
+		 *
+		 */
+		void sendNow();
 
+		/**
+		 * \brief Sets the address and buffer size when streaming
+		 *
+		 * Must be called once during setup() to prepare OSCSender for streaming
+		 *
+		 * @param address the OSC address which data will be steamed to
+		 * @param streaming_buffer_size the buffer size used when streaming data. Defaults to 1024
+		 *
+		 */
 		void streamTo(std::string address, int streaming_buffer_size = OSCSENDER_DEFAULT_STREAMING_BUFFERSIZE);
+		/**
+		 * \brief Streams data to the address set in streamTo()
+		 *
+		 * Data passed to this function is added to an internal buffer which is
+		 * sent as a binary blob when the buffer is full
+		 *
+		 * @param in data to be streamed
+		 *
+		 */
 		void stream(float in);
 		// void stream(float* buf, int num_floats);
 
 	private:
 		std::string ip_address;
-        int port;
+        	int port;
 
-        UdpClient socket;
+        	UdpClient socket;
 
-        oscpkt::Message msg;
-        oscpkt::PacketWriter pw;
+        	oscpkt::Message msg;
+        	oscpkt::PacketWriter pw;
 
-        AuxTaskNonRT send_task;
-        static void send_task_func(void* ptr, void* buf, int size);
+        	AuxTaskNonRT send_task;
+        	static void send_task_func(void* ptr, void* buf, int size);
 
-        std::string streamAddress;
-        std::vector<float> streamBuffer;
-        int streamBufferSize;
+        	std::string streamAddress;
+        	std::vector<float> streamBuffer;
+        	int streamBufferSize;
 
-        AuxTaskNonRT stream_task;
-        static void stream_task_func(void* ptr, void* buf, int size);
+        	AuxTaskNonRT stream_task;
+        	static void stream_task_func(void* ptr, void* buf, int size);
 };
 
-#endif
+#endif

include/OSCServer.h

@@ -11,7 +11,7 @@
 #define UDP_RECEIVE_MAX_LENGTH 16384
 
 /**
- * \brief OSCServer provides functions for receiving OSC messages in Bela.
+ * \brief OSCServer is deprecated, please use OSCReceiver instead
  *
  * When an OSC message is received, the message is decoded by the OSCServer off the audio
  * thread and placed in an internal queue. This queue can be polled from the audio thread