From 79b68aa7f9f67a3ce2f48582bc062e8c5cba2413 Mon Sep 17 00:00:00 2001 From: Tom Rondeau Date: Sun, 9 Oct 2011 21:58:40 -0400 Subject: docs: adding doc directory, Doxygen page, and README for audio package. --- gr-audio/doc/Makefile.am | 27 +++++++++++++ gr-audio/doc/README.audio | 20 ++++++++++ gr-audio/doc/audio.dox | 51 +++++++++++++++++++++++++ gr-audio/include/gr_audio_sink.h | 13 +++++++ gr-audio/include/gr_audio_source.h | 13 +++++++ gr-audio/lib/alsa/audio_alsa_sink.h | 1 + gr-audio/lib/alsa/audio_alsa_source.h | 1 + gr-audio/lib/jack/audio_jack_sink.h | 1 + gr-audio/lib/jack/audio_jack_source.h | 1 + gr-audio/lib/oss/audio_oss_sink.h | 1 + gr-audio/lib/oss/audio_oss_source.h | 1 + gr-audio/lib/osx/audio_osx_sink.h | 1 + gr-audio/lib/osx/audio_osx_source.h | 1 + gr-audio/lib/portaudio/audio_portaudio_sink.h | 3 +- gr-audio/lib/portaudio/audio_portaudio_source.h | 3 +- gr-audio/lib/windows/audio_windows_sink.h | 1 + gr-audio/lib/windows/audio_windows_source.h | 1 + 17 files changed, 138 insertions(+), 2 deletions(-) create mode 100644 gr-audio/doc/Makefile.am create mode 100644 gr-audio/doc/README.audio create mode 100644 gr-audio/doc/audio.dox (limited to 'gr-audio') diff --git a/gr-audio/doc/Makefile.am b/gr-audio/doc/Makefile.am new file mode 100644 index 000000000..959a9044f --- /dev/null +++ b/gr-audio/doc/Makefile.am @@ -0,0 +1,27 @@ +# +# Copyright 2011 Free Software Foundation, Inc. +# +# This file is part of GNU Radio +# +# GNU Radio is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3, or (at your option) +# any later version. +# +# GNU Radio is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with GNU Radio; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, +# Boston, MA 02110-1301, USA. +# + +include $(top_srcdir)/Makefile.common + +SUBDIRS = + +dist_gr_doc_DATA = \ + README.audio diff --git a/gr-audio/doc/README.audio b/gr-audio/doc/README.audio new file mode 100644 index 000000000..ebd0fe5d7 --- /dev/null +++ b/gr-audio/doc/README.audio @@ -0,0 +1,20 @@ +This is the gr-audio package. This package includes all of the +supported audio interfaces, including: + - alsa + - oss + - jack + - portaudio + - osx + - windows + +Typically, the audio package will auto-detect the proper driver to use +based on the system it is run on. Import this package with: + + from gnuradio import audio + +See the Doxygen documentation for details about the blocks available +in this package. A quick listing of the details can be found in Python +after importing by using: + + help(audio) + diff --git a/gr-audio/doc/audio.dox b/gr-audio/doc/audio.dox new file mode 100644 index 000000000..3a0cb5e48 --- /dev/null +++ b/gr-audio/doc/audio.dox @@ -0,0 +1,51 @@ +/*! \page page_audio Audio Interface + +\section Introduction + +This is the gr-audio package. This package includes all of the +supported audio interfaces, including: + +\li alsa +\li oss +\li jack +\li portaudio +\li osx +\li windows + +\code + from gnuradio import audio +\endcode + +See the Doxygen documentation for details about the blocks available +in this package. The relevant blocks are listed in the \ref audio_blk group. + +A quick listing of the details can be found in Python after importing +by using: + +\code + help(digital) +\endcode + + +\section Usage +For an audio source, a typical OptionParser option and it's use looks +like: + +\code + parser.add_option("-O", "--audio-output", type="string", default="", + help="pcm device name. E.g., hw:0,0 or surround51 or /dev/dsp") + audio_rate = 32e3 + audio_sink = audio.sink (int (audio_rate), options.audio_output) +\endcode + +Similarly, an audio sink would have a typical OptionParser option and +its use would look like: + +\code + parser.add_option("-I", "--audio-input", type="string", default="", + help="pcm input device name. E.g., hw:0,0 or /dev/dsp") + audio_rate = 32e3 + audio_source = audio.source(int(audio_rate), audio_input) +\endcode + +*/ diff --git a/gr-audio/include/gr_audio_sink.h b/gr-audio/include/gr_audio_sink.h index ca3b15a37..ec064b64b 100644 --- a/gr-audio/include/gr_audio_sink.h +++ b/gr-audio/include/gr_audio_sink.h @@ -25,6 +25,19 @@ #include #include +/*! + * \brief Creates a sink from an audio device. + * \ingroup audio_blk + * + * Creates a sink from an audio device at a specified + * sample_rate. The specific audio device to use can be specified as + * the device_name parameter. Typical choices are: + * \li pulse + * \li hw:0,0 + * \li plughw:0,0 + * \li surround51 + * \li /dev/dsp + */ class GR_AUDIO_API audio_sink : virtual public gr_sync_block{ public: typedef boost::shared_ptr sptr; diff --git a/gr-audio/include/gr_audio_source.h b/gr-audio/include/gr_audio_source.h index b8ae2ca5f..eca22e3eb 100644 --- a/gr-audio/include/gr_audio_source.h +++ b/gr-audio/include/gr_audio_source.h @@ -25,6 +25,19 @@ #include #include +/*! + * \brief Creates a source from an audio device. + * \ingroup audio_blk + * + * Creates a source from an audio device at a specified + * sample_rate. The specific audio device to use can be specified as + * the device_name parameter. Typical choices are: + * \li pulse + * \li hw:0,0 + * \li plughw:0,0 + * \li surround51 + * \li /dev/dsp + */ class GR_AUDIO_API audio_source : virtual public gr_sync_block{ public: typedef boost::shared_ptr sptr; diff --git a/gr-audio/lib/alsa/audio_alsa_sink.h b/gr-audio/lib/alsa/audio_alsa_sink.h index 23e406d6b..b33b84644 100644 --- a/gr-audio/lib/alsa/audio_alsa_sink.h +++ b/gr-audio/lib/alsa/audio_alsa_sink.h @@ -34,6 +34,7 @@ /*! * \brief audio sink using ALSA + * \ingroup audio_blk * * The sink has N input streams of floats, where N depends * on the hardware characteristics of the selected device. diff --git a/gr-audio/lib/alsa/audio_alsa_source.h b/gr-audio/lib/alsa/audio_alsa_source.h index e38af3872..142ae711a 100644 --- a/gr-audio/lib/alsa/audio_alsa_source.h +++ b/gr-audio/lib/alsa/audio_alsa_source.h @@ -37,6 +37,7 @@ typedef boost::shared_ptr audio_alsa_source_sptr; /*! * \brief audio source using ALSA + * \ingroup audio_blk * * The source has between 1 and N input streams of floats, where N is * depends on the hardware characteristics of the selected device. diff --git a/gr-audio/lib/jack/audio_jack_sink.h b/gr-audio/lib/jack/audio_jack_sink.h index a11863ee0..5500b3641 100644 --- a/gr-audio/lib/jack/audio_jack_sink.h +++ b/gr-audio/lib/jack/audio_jack_sink.h @@ -32,6 +32,7 @@ int jack_sink_process (jack_nframes_t nframes, void *arg); /*! * \brief audio sink using JACK + * \ingroup audio_blk * * The sink has one input stream of floats. * diff --git a/gr-audio/lib/jack/audio_jack_source.h b/gr-audio/lib/jack/audio_jack_source.h index 858f34528..a155bf95b 100644 --- a/gr-audio/lib/jack/audio_jack_source.h +++ b/gr-audio/lib/jack/audio_jack_source.h @@ -32,6 +32,7 @@ int jack_source_process (jack_nframes_t nframes, void *arg); /*! * \brief audio source using JACK + * \ingroup audio_blk * * The source has one input stream of floats. * diff --git a/gr-audio/lib/oss/audio_oss_sink.h b/gr-audio/lib/oss/audio_oss_sink.h index 0d7280c2f..47b1407d3 100644 --- a/gr-audio/lib/oss/audio_oss_sink.h +++ b/gr-audio/lib/oss/audio_oss_sink.h @@ -28,6 +28,7 @@ /*! * \brief audio sink using OSS + * \ingroup audio_blk * * input signature is one or two streams of floats. * Input samples must be in the range [-1,1]. diff --git a/gr-audio/lib/oss/audio_oss_source.h b/gr-audio/lib/oss/audio_oss_source.h index b20ef5c05..df9f68e42 100644 --- a/gr-audio/lib/oss/audio_oss_source.h +++ b/gr-audio/lib/oss/audio_oss_source.h @@ -28,6 +28,7 @@ /*! * \brief audio source using OSS + * \ingroup audio_blk * * Output signature is one or two streams of floats. * Output samples will be in the range [-1,1]. diff --git a/gr-audio/lib/osx/audio_osx_sink.h b/gr-audio/lib/osx/audio_osx_sink.h index 13bd95d53..e7598097d 100644 --- a/gr-audio/lib/osx/audio_osx_sink.h +++ b/gr-audio/lib/osx/audio_osx_sink.h @@ -31,6 +31,7 @@ /*! * \brief audio sink using OSX + * \ingroup audio_blk * * input signature is one or two streams of floats. * Input samples must be in the range [-1,1]. diff --git a/gr-audio/lib/osx/audio_osx_source.h b/gr-audio/lib/osx/audio_osx_source.h index a373ea94f..435172a2c 100644 --- a/gr-audio/lib/osx/audio_osx_source.h +++ b/gr-audio/lib/osx/audio_osx_source.h @@ -31,6 +31,7 @@ /*! * \brief audio source using OSX + * \ingroup audio_blk * * Input signature is one or two streams of floats. * Samples must be in the range [-1,1]. diff --git a/gr-audio/lib/portaudio/audio_portaudio_sink.h b/gr-audio/lib/portaudio/audio_portaudio_sink.h index 6426a32ac..04a881f7e 100644 --- a/gr-audio/lib/portaudio/audio_portaudio_sink.h +++ b/gr-audio/lib/portaudio/audio_portaudio_sink.h @@ -34,7 +34,8 @@ PaStreamCallback portaudio_sink_callback; /*! - * \ Audio sink using PORTAUDIO + * \brief Audio sink using PORTAUDIO + * \ingroup audio_blk * * Input samples must be in the range [-1,1]. */ diff --git a/gr-audio/lib/portaudio/audio_portaudio_source.h b/gr-audio/lib/portaudio/audio_portaudio_source.h index 245b3410b..b555bc759 100644 --- a/gr-audio/lib/portaudio/audio_portaudio_source.h +++ b/gr-audio/lib/portaudio/audio_portaudio_source.h @@ -33,7 +33,8 @@ PaStreamCallback portaudio_source_callback; /*! - * \ Audio source using PORTAUDIO + * \brief Audio source using PORTAUDIO + * \ingroup audio_blk * * Input samples must be in the range [-1,1]. */ diff --git a/gr-audio/lib/windows/audio_windows_sink.h b/gr-audio/lib/windows/audio_windows_sink.h index 6819bd448..d4ca259b3 100644 --- a/gr-audio/lib/windows/audio_windows_sink.h +++ b/gr-audio/lib/windows/audio_windows_sink.h @@ -34,6 +34,7 @@ /*! * \brief audio sink using winmm mmsystem (win32 only) + * \ingroup audio_blk * * input signature is one or two streams of floats. * Input samples must be in the range [-1,1]. diff --git a/gr-audio/lib/windows/audio_windows_source.h b/gr-audio/lib/windows/audio_windows_source.h index 36311968d..9cb789576 100644 --- a/gr-audio/lib/windows/audio_windows_source.h +++ b/gr-audio/lib/windows/audio_windows_source.h @@ -28,6 +28,7 @@ /*! * \brief audio source using winmm mmsystem (win32 only) + * \ingroup audio_blk * * Output signature is one or two streams of floats. * Output samples will be in the range [-1,1]. -- cgit From c182a39e22f44b0d1fe1e56d123b564ba1cf6a98 Mon Sep 17 00:00:00 2001 From: Tom Rondeau Date: Sun, 9 Oct 2011 23:29:40 -0400 Subject: docs: include the doc directory in gr-aduio. --- gr-audio/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'gr-audio') diff --git a/gr-audio/Makefile.am b/gr-audio/Makefile.am index cde1702f2..da4106c23 100644 --- a/gr-audio/Makefile.am +++ b/gr-audio/Makefile.am @@ -21,7 +21,7 @@ include $(top_srcdir)/Makefile.common -SUBDIRS = include lib examples +SUBDIRS = include lib examples doc if PYTHON SUBDIRS += grc swig -- cgit From 06860c309153890a6a42babfbedf230eb24f0042 Mon Sep 17 00:00:00 2001 From: Tom Rondeau Date: Sun, 9 Oct 2011 23:31:34 -0400 Subject: docs: adding gitignore for gr-audio/doc --- gr-audio/doc/.gitignore | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 gr-audio/doc/.gitignore (limited to 'gr-audio') diff --git a/gr-audio/doc/.gitignore b/gr-audio/doc/.gitignore new file mode 100644 index 000000000..b336cc7ce --- /dev/null +++ b/gr-audio/doc/.gitignore @@ -0,0 +1,2 @@ +/Makefile +/Makefile.in -- cgit