comparison include/BeagleRT.h @ 56:3c3a1357657d newapi

Further API update to name three primary functions setup(), render() and cleanup(). Changed include paths so now can #include <BeagleRT.h>. Removed stale pru_rtaudio.bin file as this is now done as pru_rtaudio_bin.h. Updated examples to new API and fixed minor compiler warnings along the way. Network example needs further attention to compile.

 
 /**
  * \ingroup render
  * \brief Structure holding current audio and sensor settings and pointers to data buffers.
  *
- * This structure is passed to initialise_render(), render() and cleanup_render(). It is
+ * This structure is passed to setup(), render() and cleanup(). It is
  * initialised in BeagleRT_initAudio() based on the contents of the BeagleRTInitSettings
  * structure.
  */
 typedef struct {
 	/// \brief Buffer holding audio input samples

 } BeagleRTContext;
 
 /** \ingroup auxtask
  *
  * Auxiliary task variable. Auxiliary tasks are created using createAuxiliaryTask() and
- * automatically cleaned up after cleanup_render() finishes.
+ * automatically cleaned up after cleanup() finishes.
  */
 typedef void* AuxiliaryTask;	// Opaque data type to keep track of aux tasks
 
 /** \ingroup render
  *

  * memory or resources that will be needed in render().
  *
  * \param context Data structure holding information on sample rates, numbers of channels,
  * frame sizes and other state. Note: the buffers for audio, analog and digital data will
  * \b not yet be available to use. Do not attempt to read or write audio or sensor data
- * in initialise_render().
+ * in setup().
  * \param userData An opaque pointer to an optional user-defined data structure. Whatever
  * is passed as the second argument to BeagleRT_initAudio() will appear here.
  *
  * \return true on success, or false if an error occurred. If no initialisation is
- * required, initialise_render() should return true.
- */
-bool initialise_render(BeagleRTContext *context, void *userData);
+ * required, setup() should return true.
+ */
+bool setup(BeagleRTContext *context, void *userData);
 
 /**
  * \brief User-defined callback function to process audio and sensor data.
  *
  * This function is called regularly by the system every time there is a new block of

  * of data, store the results within \c context, and return.
  *
  * \param context Data structure holding buffers for audio, analog and digital data. The
  * structure also holds information on numbers of channels, frame sizes and sample rates,
  * which are guaranteed to remain the same throughout the program and to match what was
- * passed to initialise_render().
+ * passed to setup().
  * \param userData An opaque pointer to an optional user-defined data structure. Will
- * be the same as the \c userData parameter passed to initialise_render().
+ * be the same as the \c userData parameter passed to setup().
  */
 void render(BeagleRTContext *context, void *userData);
 
 /**
  * \brief User-defined cleanup function which runs when the program finishes.
  *
  * This function is called by the system once after audio rendering has finished, before the
- * program quits. Use it to release any memory allocated in initialise_render() and to perform
- * any other required cleanup. If no initialisation is performed in initialise_render(), then
+ * program quits. Use it to release any memory allocated in setup() and to perform
+ * any other required cleanup. If no initialisation is performed in setup(), then
  * this function will usually be empty.
  *
  * \param context Data structure holding information on sample rates, numbers of channels,
  * frame sizes and other state. Note: the buffers for audio, analog and digital data will
  * no longer be available to use. Do not attempt to read or write audio or sensor data
- * in cleanup_render().
+ * in cleanup().
  * \param userData An opaque pointer to an optional user-defined data structure. Will
- * be the same as the \c userData parameter passed to initialise_render() and render().
- */
-void cleanup_render(BeagleRTContext *context, void *userData);
+ * be the same as the \c userData parameter passed to setup() and render().
+ */
+void cleanup(BeagleRTContext *context, void *userData);
 
 /** @} */
 
 /**
  * \defgroup control Control and command line functions

 /**
  * \brief Initialise audio and sensor rendering environment.
  *
  * This function prepares audio rendering in BeagleRT. It should be called from main() sometime
  * after command line option parsing has finished. It will initialise the rendering system, which
- * in the process will result in a call to the user-defined initialise_render() function.
+ * in the process will result in a call to the user-defined setup() function.
  *
  * \param settings Data structure holding system settings, including numbers of channels, frame sizes,
  * volume levels and other information.
  * \param userData An opaque pointer to a user-defined data structure which will be passed to
- * initialise_render(), render() and cleanup_render(). You can use this to pass custom information
+ * setup(), render() and cleanup(). You can use this to pass custom information
  * to the rendering functions, as an alternative to using global variables.
  *
  * \return 0 on success, or nonzero if an error occurred.
  */
 int BeagleRT_initAudio(BeagleRTInitSettings *settings, void *userData);

 /**
  * \brief Clean up resources from audio and sensor processing.
  *
  * This function should only be called after BeagleRT_stopAudio(). It will release any
  * internal resources for audio and sensor processing. In the process, it will call the
- * user-defined cleanup_render() function.
+ * user-defined cleanup() function.
  */
 void BeagleRT_cleanupAudio();
 
 /** @} */
 

  * These functions are used to create separate real-time tasks (threads) which run at lower
  * priority than the audio processing. They can be used, for example, for large time-consuming
  * calculations which would take more than one audio frame length to process, or they could be
  * used to communicate with external hardware when that communication might block or be delayed.
  *
- * All auxiliary tasks used by the program should be created in initialise_render(). The tasks
+ * All auxiliary tasks used by the program should be created in setup(). The tasks
  * can then be scheduled at will within the render() function.
  *
  * @{
  */
 

 /**
  * \brief Create a new auxiliary task.
  *
  * This function creates a new auxiliary task which, when scheduled, runs the function specified
  * in the first argument. Note that the task does not run until scheduleAuxiliaryTask() is called.
- * Auxiliary tasks should be created in initialise_render() and never in render() itself.
+ * Auxiliary tasks should be created in setup() and never in render() itself.
  *
  * The second argument specifies the real-time priority. Valid values are between 0
  * and 99, and usually should be lower than \ref BEAGLERT_AUDIO_PRIORITY. Tasks with higher priority always
  * preempt tasks with lower priority.
  *