tao-1.0-beta-10May2006/0000777000372200037200000000000010430370135011244 500000000000000tao-1.0-beta-10May2006/doc/0000777000372200037200000000000010430370135012011 500000000000000tao-1.0-beta-10May2006/doc/ClassReference/0000777000372200037200000000000010430370135014675 500000000000000tao-1.0-beta-10May2006/doc/ClassReference/Makefile.am0000755000372200037200000000003206762572350016663 00000000000000EXTRA_DIST = tao.doxy.cnf tao-1.0-beta-10May2006/doc/ClassReference/Makefile.in0000644000372200037200000002230210430117005016650 00000000000000# Makefile.in generated by automake 1.9.6 from Makefile.am. # @configure_input@ # Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, # 2003, 2004, 2005 Free Software Foundation, Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, # with or without modifications, as long as this notice is preserved. # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY, to the extent permitted by law; without # even the implied warranty of MERCHANTABILITY or FITNESS FOR A # PARTICULAR PURPOSE. @SET_MAKE@ srcdir = @srcdir@ top_srcdir = @top_srcdir@ VPATH = @srcdir@ pkgdatadir = $(datadir)/@PACKAGE@ pkglibdir = $(libdir)/@PACKAGE@ pkgincludedir = $(includedir)/@PACKAGE@ top_builddir = ../.. am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd INSTALL = @INSTALL@ install_sh_DATA = $(install_sh) -c -m 644 install_sh_PROGRAM = $(install_sh) -c install_sh_SCRIPT = $(install_sh) -c INSTALL_HEADER = $(INSTALL_DATA) transform = $(program_transform_name) NORMAL_INSTALL = : PRE_INSTALL = : POST_INSTALL = : NORMAL_UNINSTALL = : PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ subdir = doc/ClassReference DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ $(srcdir)/tao.doxy.cnf.in ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/configure.in am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ $(ACLOCAL_M4) mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs CONFIG_HEADER = $(top_builddir)/config.h CONFIG_CLEAN_FILES = tao.doxy.cnf SOURCES = DIST_SOURCES = DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) ACLOCAL = @ACLOCAL@ AMDEP_FALSE = @AMDEP_FALSE@ AMDEP_TRUE = @AMDEP_TRUE@ AMTAR = @AMTAR@ AR = @AR@ AUTOCONF = @AUTOCONF@ AUTOHEADER = @AUTOHEADER@ AUTOMAKE = @AUTOMAKE@ AWK = @AWK@ CC = @CC@ CCDEPMODE = @CCDEPMODE@ CFLAGS = @CFLAGS@ CPP = @CPP@ CPPFLAGS = @CPPFLAGS@ CXX = @CXX@ CXXCPP = @CXXCPP@ CXXDEPMODE = @CXXDEPMODE@ CXXFLAGS = @CXXFLAGS@ CYGPATH_W = @CYGPATH_W@ DATE = @DATE@ DEFS = @DEFS@ DEPDIR = @DEPDIR@ ECHO = @ECHO@ ECHO_C = @ECHO_C@ ECHO_N = @ECHO_N@ ECHO_T = @ECHO_T@ EGREP = @EGREP@ EXEEXT = @EXEEXT@ F77 = @F77@ FFLAGS = @FFLAGS@ GLLIB = @GLLIB@ GLULIB = @GLULIB@ HAVENULL = @HAVENULL@ INSTALL_DATA = @INSTALL_DATA@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_SCRIPT = @INSTALL_SCRIPT@ INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ LDFLAGS = @LDFLAGS@ LEX = @LEX@ LEXLIB = @LEXLIB@ LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@ LIBOBJS = @LIBOBJS@ LIBS = @LIBS@ LIBTOOL = @LIBTOOL@ LN_S = @LN_S@ LTLIBOBJS = @LTLIBOBJS@ LT_AGE = @LT_AGE@ LT_CURRENT = @LT_CURRENT@ LT_RELEASE = @LT_RELEASE@ LT_REVISION = @LT_REVISION@ MAINT = @MAINT@ MAINTAINER_MODE_FALSE = @MAINTAINER_MODE_FALSE@ MAINTAINER_MODE_TRUE = @MAINTAINER_MODE_TRUE@ MAKEINFO = @MAKEINFO@ OBJEXT = @OBJEXT@ PACKAGE = @PACKAGE@ PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ PACKAGE_NAME = @PACKAGE_NAME@ PACKAGE_STRING = @PACKAGE_STRING@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ RANLIB = @RANLIB@ SET_MAKE = @SET_MAKE@ SHELL = @SHELL@ STRIP = @STRIP@ TAODIR = @TAODIR@ TAO_BINARY_AGE = @TAO_BINARY_AGE@ TAO_INTERFACE_AGE = @TAO_INTERFACE_AGE@ TAO_MAJOR_VERSION = @TAO_MAJOR_VERSION@ TAO_MICRO_VERSION = @TAO_MICRO_VERSION@ TAO_MINOR_VERSION = @TAO_MINOR_VERSION@ TAO_VERSION = @TAO_VERSION@ VERSION = @VERSION@ X_CFLAGS = @X_CFLAGS@ X_EXTRA_LIBS = @X_EXTRA_LIBS@ X_LIBS = @X_LIBS@ X_PRE_LIBS = @X_PRE_LIBS@ YACC = @YACC@ ac_ct_AR = @ac_ct_AR@ ac_ct_CC = @ac_ct_CC@ ac_ct_CXX = @ac_ct_CXX@ ac_ct_F77 = @ac_ct_F77@ ac_ct_RANLIB = @ac_ct_RANLIB@ ac_ct_STRIP = @ac_ct_STRIP@ am__fastdepCC_FALSE = @am__fastdepCC_FALSE@ am__fastdepCC_TRUE = @am__fastdepCC_TRUE@ am__fastdepCXX_FALSE = @am__fastdepCXX_FALSE@ am__fastdepCXX_TRUE = @am__fastdepCXX_TRUE@ am__include = @am__include@ am__leading_dot = @am__leading_dot@ am__quote = @am__quote@ am__tar = @am__tar@ am__untar = @am__untar@ bindir = @bindir@ build = @build@ build_alias = @build_alias@ build_cpu = @build_cpu@ build_os = @build_os@ build_vendor = @build_vendor@ datadir = @datadir@ exec_prefix = @exec_prefix@ host = @host@ host_alias = @host_alias@ host_cpu = @host_cpu@ host_os = @host_os@ host_vendor = @host_vendor@ includedir = @includedir@ infodir = @infodir@ install_sh = @install_sh@ libdir = @libdir@ libexecdir = @libexecdir@ localstatedir = @localstatedir@ mandir = @mandir@ mkdir_p = @mkdir_p@ oldincludedir = @oldincludedir@ prefix = @prefix@ program_transform_name = @program_transform_name@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ x_includes = @x_includes@ EXTRA_DIST = tao.doxy.cnf all: all-am .SUFFIXES: $(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ && exit 0; \ exit 1;; \ esac; \ done; \ echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/ClassReference/Makefile'; \ cd $(top_srcdir) && \ $(AUTOMAKE) --gnu doc/ClassReference/Makefile .PRECIOUS: Makefile Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status @case '$?' in \ *config.status*) \ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ *) \ echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ esac; $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh $(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh $(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh tao.doxy.cnf: $(top_builddir)/config.status $(srcdir)/tao.doxy.cnf.in cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ mostlyclean-libtool: -rm -f *.lo clean-libtool: -rm -rf .libs _libs distclean-libtool: -rm -f libtool uninstall-info-am: tags: TAGS TAGS: ctags: CTAGS CTAGS: distdir: $(DISTFILES) @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \ list='$(DISTFILES)'; for file in $$list; do \ case $$file in \ $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \ esac; \ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ if test "$$dir" != "$$file" && test "$$dir" != "."; then \ dir="/$$dir"; \ $(mkdir_p) "$(distdir)$$dir"; \ else \ dir=''; \ fi; \ if test -d $$d/$$file; then \ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ fi; \ cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ else \ test -f $(distdir)/$$file \ || cp -p $$d/$$file $(distdir)/$$file \ || exit 1; \ fi; \ done check-am: all-am check: check-am all-am: Makefile installdirs: install: install-am install-exec: install-exec-am install-data: install-data-am uninstall: uninstall-am install-am: all-am @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am installcheck: installcheck-am install-strip: $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ `test -z '$(STRIP)' || \ echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install mostlyclean-generic: clean-generic: distclean-generic: -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) maintainer-clean-generic: @echo "This command is intended for maintainers to use" @echo "it deletes files that may require special tools to rebuild." clean: clean-am clean-am: clean-generic clean-libtool mostlyclean-am distclean: distclean-am -rm -f Makefile distclean-am: clean-am distclean-generic distclean-libtool dvi: dvi-am dvi-am: html: html-am info: info-am info-am: install-data-am: install-exec-am: install-info: install-info-am install-man: installcheck-am: maintainer-clean: maintainer-clean-am -rm -f Makefile maintainer-clean-am: distclean-am maintainer-clean-generic mostlyclean: mostlyclean-am mostlyclean-am: mostlyclean-generic mostlyclean-libtool pdf: pdf-am pdf-am: ps: ps-am ps-am: uninstall-am: uninstall-info-am .PHONY: all all-am check check-am clean clean-generic clean-libtool \ distclean distclean-generic distclean-libtool distdir dvi \ dvi-am html html-am info info-am install install-am \ install-data install-data-am install-exec install-exec-am \ install-info install-info-am install-man install-strip \ installcheck installcheck-am installdirs maintainer-clean \ maintainer-clean-generic mostlyclean mostlyclean-generic \ mostlyclean-libtool pdf pdf-am ps ps-am uninstall uninstall-am \ uninstall-info-am # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. .NOEXPORT: tao-1.0-beta-10May2006/doc/ClassReference/tao.doxy.cnf.in0000755000372200037200000002207607013415432017470 00000000000000# This file describes the settings to be used by doxygen for a project # # All text after a hash (#) is considered a comment and will be ignored # The format is: # TAG = value [value, ...] # Values that contain spaces should be placed between quotes (" ") #--------------------------------------------------------------------------- # General configuration options #--------------------------------------------------------------------------- # The PROJECT_NAME tag is a single word (or a sequence of word surrounded # by quotes) that should identify the project. PROJECT_NAME = Tao # The PROJECT_NUMBER tag can be used to enter a project or revision number. # This could be handy for archiving the generated documentation or # if some version control system is used. PROJECT_NUMBER = @TAO_VERSION@ # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) # base path where the generated documentation will be put. # If a relative path is entered, it will be relative to the location # where doxygen was started. If left blank the current directory will be used. OUTPUT_DIRECTORY = # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `html' will be used as the default path. HTML_OUTPUT = html # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `latex' will be used as the default path. LATEX_OUTPUT = latex # The HTML_HEADER tag can be used to specify a personal HTML header for # each generated HTML page. If it is left blank doxygen will generate a # standard header. HTML_HEADER = # The HTML_FOOTER tag can be used to specify a personal HTML footer for # each generated HTML page. If it is left blank doxygen will generate a # standard footer. HTML_FOOTER = # The QUIET tag can be used to turn on/off the messages that are generated # by doxygen. Possible values are YES and NO. If left blank NO is used. QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are # generated by doxygen. Possible values are YES and NO. If left blank # NO is used. WARNINGS = YES # The DISABLE_INDEX tag can be used to turn on/off the condensed index at # top of each page. A value of NO (the default) enables the index and the # value YES disables it. DISABLE_INDEX = NO # If the EXTRACT_ALL tag is set to YES all classes and functions will be # included in the documentation, even if no documentation was available. EXTRACT_ALL = YES # If the EXTRACT_PRIVATE tag is set to YES all private members of a class # will be included in the documentation. EXTRACT_PRIVATE = NO # If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all # undocumented members inside documented classes or files. HIDE_UNDOC_MEMBERS = NO # If the GENERATE_LATEX tag is set to YES (the default) Doxygen will # generate Latex output. GENERATE_LATEX = YES # If the GENERATE_HTML tag is set to YES (the default) Doxygen will # generate HTML output GENERATE_HTML = YES # If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will # include brief member descriptions after the members that are listed in # the file and class documentation (similar to JavaDoc). # Set to NO to disable this. BRIEF_MEMBER_DESC = YES # If the FULL_PATH_NAMES tag is set to YES Doxygen will prepend the full # path before files name in the file list and in the header files. If set # to NO the shortest path that makes the file name unique will be used FULL_PATH_NAMES = NO #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- # The INPUT tag is used to specify the files and/or directories that contain # documented source files. You may enter file names like "myfile.cpp" or # directories like "/usr/src/myproject". Separate the files or directories # with spaces. INPUT = ../../include ../../libtao ../../taoparse ../../tao2aiff # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp # and *.h) to filter out the source-files in the directories. If left # blank all files are included. FILE_PATTERNS = *.cc *.h *.hh *.yy *.ll # The EXAMPLE_PATH tag can be used to specify one or more files or # directories that contain example code fragments that are included (see # the \include command). EXAMPLE_PATH = # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. # If left blank NO is used. RECURSIVE = NO # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program # by executing (via popen()) the command , where # is the value of the INPUT_FILTER tag, and is the name of an # input file. Doxygen will then use the output that the filter program writes # to standard output. INPUT_FILTER = #--------------------------------------------------------------------------- # Configuration options related to the preprocessor #--------------------------------------------------------------------------- # If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will # evaluate all C-preprocessor directives found in the sources and include # files. ENABLE_PREPROCESSING = YES # If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro # names in the source code. If set to NO (the default) only conditional # compilation will be performed. MACRO_EXPANSION = NO # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # in the INCLUDE_PATH (see below) will be search if a #include is found. SEARCH_INCLUDES = YES # The INCLUDE_PATH tag can be used to specify one or more directories that # contain include files that are not input files but should be processed by # the preprocessor. INCLUDE_PATH = ../../include # The PREDEFINED tag can be used to specify one or more macro names that # are defined before the preprocessor is started (similar to the -D option of # gcc). The argument of the tag is a list of macros of the form: name # or name=definition (no spaces). In the former case 1 is used as the # definition. PREDEFINED = # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES # then the macro expansion is limited to the macros specified with the # PREDEFINED tag. EXPAND_ONLY_PREDEF = NO #--------------------------------------------------------------------------- # Configuration options related to external references #--------------------------------------------------------------------------- # The TAGFILES tag can be used to specify one or more tagfiles. TAGFILES = # When a file name is specified after GENERATE_TAGFILE, doxygen will create # a tag file that is based on the input files it reads. GENERATE_TAGFILE = # If the ALLEXTERNALS tag is set to YES all external classes will be listed # in the class index. If set to NO only the inherited external classes # will be listed. ALLEXTERNALS = NO # The PERL_PATH should be the absolute path and name of the perl script # interpreter (i.e. the result of `which perl'). PERL_PATH = /usr/bin/perl #--------------------------------------------------------------------------- # Configuration options related to the search engine #--------------------------------------------------------------------------- # The SEARCHENGINE tag specifies whether or not a search engine should be # used. If set to NO the values of all tags below this one will be ignored. SEARCHENGINE = NO # The CGI_NAME tag should be the name of the CGI script that # starts the search engine (doxysearch) with the correct parameters. # A script with this name will be generated by doxygen. CGI_NAME = search.cgi # The CGI_URL tag should be the absolute URL to the directory where the # cgi binaries are located. See the documentation of your http daemon for # details. CGI_URL = # The DOC_URL tag should be the absolute URL to the directory where the # documentation is located. If left blank the absolute path to the # documentation, with file:// prepended to it, will be used. DOC_URL = # The DOC_ABSPATH tag should be the absolute path to the directory where the # documentation is located. If left blank the directory on the local machine # will be used. DOC_ABSPATH = # The BIN_ABSPATH tag must point to the directory where the doxysearch binary # is installed. BIN_ABSPATH = /usr/local/bin/ # The EXT_DOC_PATHS tag can be used to specify one or more paths to # documentation generated for other projects. This allows doxysearch to search # the documentation for these projects as well. EXT_DOC_PATHS = tao-1.0-beta-10May2006/doc/ClassReference/tao.doxy.cnf0000644000372200037200000002210310430370107017043 00000000000000# This file describes the settings to be used by doxygen for a project # # All text after a hash (#) is considered a comment and will be ignored # The format is: # TAG = value [value, ...] # Values that contain spaces should be placed between quotes (" ") #--------------------------------------------------------------------------- # General configuration options #--------------------------------------------------------------------------- # The PROJECT_NAME tag is a single word (or a sequence of word surrounded # by quotes) that should identify the project. PROJECT_NAME = Tao # The PROJECT_NUMBER tag can be used to enter a project or revision number. # This could be handy for archiving the generated documentation or # if some version control system is used. PROJECT_NUMBER = 1.0-beta-10May2006 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) # base path where the generated documentation will be put. # If a relative path is entered, it will be relative to the location # where doxygen was started. If left blank the current directory will be used. OUTPUT_DIRECTORY = # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `html' will be used as the default path. HTML_OUTPUT = html # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be # put in front of it. If left blank `latex' will be used as the default path. LATEX_OUTPUT = latex # The HTML_HEADER tag can be used to specify a personal HTML header for # each generated HTML page. If it is left blank doxygen will generate a # standard header. HTML_HEADER = # The HTML_FOOTER tag can be used to specify a personal HTML footer for # each generated HTML page. If it is left blank doxygen will generate a # standard footer. HTML_FOOTER = # The QUIET tag can be used to turn on/off the messages that are generated # by doxygen. Possible values are YES and NO. If left blank NO is used. QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are # generated by doxygen. Possible values are YES and NO. If left blank # NO is used. WARNINGS = YES # The DISABLE_INDEX tag can be used to turn on/off the condensed index at # top of each page. A value of NO (the default) enables the index and the # value YES disables it. DISABLE_INDEX = NO # If the EXTRACT_ALL tag is set to YES all classes and functions will be # included in the documentation, even if no documentation was available. EXTRACT_ALL = YES # If the EXTRACT_PRIVATE tag is set to YES all private members of a class # will be included in the documentation. EXTRACT_PRIVATE = NO # If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all # undocumented members inside documented classes or files. HIDE_UNDOC_MEMBERS = NO # If the GENERATE_LATEX tag is set to YES (the default) Doxygen will # generate Latex output. GENERATE_LATEX = YES # If the GENERATE_HTML tag is set to YES (the default) Doxygen will # generate HTML output GENERATE_HTML = YES # If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will # include brief member descriptions after the members that are listed in # the file and class documentation (similar to JavaDoc). # Set to NO to disable this. BRIEF_MEMBER_DESC = YES # If the FULL_PATH_NAMES tag is set to YES Doxygen will prepend the full # path before files name in the file list and in the header files. If set # to NO the shortest path that makes the file name unique will be used FULL_PATH_NAMES = NO #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- # The INPUT tag is used to specify the files and/or directories that contain # documented source files. You may enter file names like "myfile.cpp" or # directories like "/usr/src/myproject". Separate the files or directories # with spaces. INPUT = ../../include ../../libtao ../../taoparse ../../tao2aiff # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp # and *.h) to filter out the source-files in the directories. If left # blank all files are included. FILE_PATTERNS = *.cc *.h *.hh *.yy *.ll # The EXAMPLE_PATH tag can be used to specify one or more files or # directories that contain example code fragments that are included (see # the \include command). EXAMPLE_PATH = # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. # If left blank NO is used. RECURSIVE = NO # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program # by executing (via popen()) the command , where # is the value of the INPUT_FILTER tag, and is the name of an # input file. Doxygen will then use the output that the filter program writes # to standard output. INPUT_FILTER = #--------------------------------------------------------------------------- # Configuration options related to the preprocessor #--------------------------------------------------------------------------- # If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will # evaluate all C-preprocessor directives found in the sources and include # files. ENABLE_PREPROCESSING = YES # If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro # names in the source code. If set to NO (the default) only conditional # compilation will be performed. MACRO_EXPANSION = NO # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # in the INCLUDE_PATH (see below) will be search if a #include is found. SEARCH_INCLUDES = YES # The INCLUDE_PATH tag can be used to specify one or more directories that # contain include files that are not input files but should be processed by # the preprocessor. INCLUDE_PATH = ../../include # The PREDEFINED tag can be used to specify one or more macro names that # are defined before the preprocessor is started (similar to the -D option of # gcc). The argument of the tag is a list of macros of the form: name # or name=definition (no spaces). In the former case 1 is used as the # definition. PREDEFINED = # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES # then the macro expansion is limited to the macros specified with the # PREDEFINED tag. EXPAND_ONLY_PREDEF = NO #--------------------------------------------------------------------------- # Configuration options related to external references #--------------------------------------------------------------------------- # The TAGFILES tag can be used to specify one or more tagfiles. TAGFILES = # When a file name is specified after GENERATE_TAGFILE, doxygen will create # a tag file that is based on the input files it reads. GENERATE_TAGFILE = # If the ALLEXTERNALS tag is set to YES all external classes will be listed # in the class index. If set to NO only the inherited external classes # will be listed. ALLEXTERNALS = NO # The PERL_PATH should be the absolute path and name of the perl script # interpreter (i.e. the result of `which perl'). PERL_PATH = /usr/bin/perl #--------------------------------------------------------------------------- # Configuration options related to the search engine #--------------------------------------------------------------------------- # The SEARCHENGINE tag specifies whether or not a search engine should be # used. If set to NO the values of all tags below this one will be ignored. SEARCHENGINE = NO # The CGI_NAME tag should be the name of the CGI script that # starts the search engine (doxysearch) with the correct parameters. # A script with this name will be generated by doxygen. CGI_NAME = search.cgi # The CGI_URL tag should be the absolute URL to the directory where the # cgi binaries are located. See the documentation of your http daemon for # details. CGI_URL = # The DOC_URL tag should be the absolute URL to the directory where the # documentation is located. If left blank the absolute path to the # documentation, with file:// prepended to it, will be used. DOC_URL = # The DOC_ABSPATH tag should be the absolute path to the directory where the # documentation is located. If left blank the directory on the local machine # will be used. DOC_ABSPATH = # The BIN_ABSPATH tag must point to the directory where the doxysearch binary # is installed. BIN_ABSPATH = /usr/local/bin/ # The EXT_DOC_PATHS tag can be used to specify one or more paths to # documentation generated for other projects. This allows doxysearch to search # the documentation for these projects as well. EXT_DOC_PATHS = tao-1.0-beta-10May2006/doc/UserManual/0000777000372200037200000000000010430370132014062 500000000000000tao-1.0-beta-10May2006/doc/UserManual/Makefile.am0000755000372200037200000000275607103062376016062 00000000000000SUBDIRS = html HTMLARNAME = tao-${TAO_VERSION}-usermanual-html PSFILENAME = tao-${TAO_VERSION}-usermanual.ps GZIPENV = --best EXTRA_DIST = \ UserManual.tex \ closing_comments.tex \ conceptual_overview.tex \ getting_started.tex \ installation.tex \ introduction.tex \ script_language.tex \ script_reference.tex \ tutorial.tex \ user_interface.tex \ cells.eps \ circle_example.eps \ circle_waves.eps \ compound_example.eps \ instrument_coord_system.eps \ instrvis.eps \ joining.eps \ new.eps \ xandyfreqs.eps CLEANFILES = \ UserManual.bbl \ UserManual.ilg \ UserManual.blg \ UserManual.dvi \ UserManual.ps \ UserManual.log \ UserManual.idx \ UserManual.ind \ UserManual.toc \ UserManual.lof \ UserManual.aux \ ${HTMLARNAME}.tgz \ ${PSFILENAME}.gz MAINTAINERCLEANFILES = introduction.tex html: html/UserManual.html ps: UserManual.ps html-archive: html/UserManual.html mkdir /tmp/${HTMLARNAME} cp html/*.html html/*.gif /tmp/${HTMLARNAME} cd /tmp ; ${TAR} czvf ${HTMLARNAME}.tar.gz ${HTMLARNAME} mv /tmp/${HTMLARNAME}.tar.gz . rm -rf /tmp/${HTMLARNAME} psgzip: UserManual.ps gzip ${GZIP_ENV} UserManual.ps mv UserManual.ps.gz ${PSFILENAME}.gz html/UserManual.html: ${EXTRA_DIST} hyperlatex UserManual UserManual.dvi: ${EXTRA_DIST} latex UserManual latex UserManual makeindex UserManual latex UserManual UserManual.ps: UserManual.dvi allneeded UserManual.dvi dvips -f UserManual.ps downloads: psgzip html-archive .PHONY: html ps html-archive psgziptao-1.0-beta-10May2006/doc/UserManual/Makefile.in0000644000372200037200000004003010430117006016037 00000000000000# Makefile.in generated by automake 1.9.6 from Makefile.am. # @configure_input@ # Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, # 2003, 2004, 2005 Free Software Foundation, Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, # with or without modifications, as long as this notice is preserved. # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY, to the extent permitted by law; without # even the implied warranty of MERCHANTABILITY or FITNESS FOR A # PARTICULAR PURPOSE. @SET_MAKE@ srcdir = @srcdir@ top_srcdir = @top_srcdir@ VPATH = @srcdir@ pkgdatadir = $(datadir)/@PACKAGE@ pkglibdir = $(libdir)/@PACKAGE@ pkgincludedir = $(includedir)/@PACKAGE@ top_builddir = ../.. am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd INSTALL = @INSTALL@ install_sh_DATA = $(install_sh) -c -m 644 install_sh_PROGRAM = $(install_sh) -c install_sh_SCRIPT = $(install_sh) -c INSTALL_HEADER = $(INSTALL_DATA) transform = $(program_transform_name) NORMAL_INSTALL = : PRE_INSTALL = : POST_INSTALL = : NORMAL_UNINSTALL = : PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ subdir = doc/UserManual DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ $(srcdir)/introduction.tex.in ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/configure.in am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ $(ACLOCAL_M4) mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs CONFIG_HEADER = $(top_builddir)/config.h CONFIG_CLEAN_FILES = introduction.tex SOURCES = DIST_SOURCES = RECURSIVE_TARGETS = all-recursive check-recursive dvi-recursive \ html-recursive info-recursive install-data-recursive \ install-exec-recursive install-info-recursive \ install-recursive installcheck-recursive installdirs-recursive \ pdf-recursive ps-recursive uninstall-info-recursive \ uninstall-recursive ETAGS = etags CTAGS = ctags DIST_SUBDIRS = $(SUBDIRS) DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) ACLOCAL = @ACLOCAL@ AMDEP_FALSE = @AMDEP_FALSE@ AMDEP_TRUE = @AMDEP_TRUE@ AMTAR = @AMTAR@ AR = @AR@ AUTOCONF = @AUTOCONF@ AUTOHEADER = @AUTOHEADER@ AUTOMAKE = @AUTOMAKE@ AWK = @AWK@ CC = @CC@ CCDEPMODE = @CCDEPMODE@ CFLAGS = @CFLAGS@ CPP = @CPP@ CPPFLAGS = @CPPFLAGS@ CXX = @CXX@ CXXCPP = @CXXCPP@ CXXDEPMODE = @CXXDEPMODE@ CXXFLAGS = @CXXFLAGS@ CYGPATH_W = @CYGPATH_W@ DATE = @DATE@ DEFS = @DEFS@ DEPDIR = @DEPDIR@ ECHO = @ECHO@ ECHO_C = @ECHO_C@ ECHO_N = @ECHO_N@ ECHO_T = @ECHO_T@ EGREP = @EGREP@ EXEEXT = @EXEEXT@ F77 = @F77@ FFLAGS = @FFLAGS@ GLLIB = @GLLIB@ GLULIB = @GLULIB@ HAVENULL = @HAVENULL@ INSTALL_DATA = @INSTALL_DATA@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_SCRIPT = @INSTALL_SCRIPT@ INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ LDFLAGS = @LDFLAGS@ LEX = @LEX@ LEXLIB = @LEXLIB@ LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@ LIBOBJS = @LIBOBJS@ LIBS = @LIBS@ LIBTOOL = @LIBTOOL@ LN_S = @LN_S@ LTLIBOBJS = @LTLIBOBJS@ LT_AGE = @LT_AGE@ LT_CURRENT = @LT_CURRENT@ LT_RELEASE = @LT_RELEASE@ LT_REVISION = @LT_REVISION@ MAINT = @MAINT@ MAINTAINER_MODE_FALSE = @MAINTAINER_MODE_FALSE@ MAINTAINER_MODE_TRUE = @MAINTAINER_MODE_TRUE@ MAKEINFO = @MAKEINFO@ OBJEXT = @OBJEXT@ PACKAGE = @PACKAGE@ PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ PACKAGE_NAME = @PACKAGE_NAME@ PACKAGE_STRING = @PACKAGE_STRING@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ RANLIB = @RANLIB@ SET_MAKE = @SET_MAKE@ SHELL = @SHELL@ STRIP = @STRIP@ TAODIR = @TAODIR@ TAO_BINARY_AGE = @TAO_BINARY_AGE@ TAO_INTERFACE_AGE = @TAO_INTERFACE_AGE@ TAO_MAJOR_VERSION = @TAO_MAJOR_VERSION@ TAO_MICRO_VERSION = @TAO_MICRO_VERSION@ TAO_MINOR_VERSION = @TAO_MINOR_VERSION@ TAO_VERSION = @TAO_VERSION@ VERSION = @VERSION@ X_CFLAGS = @X_CFLAGS@ X_EXTRA_LIBS = @X_EXTRA_LIBS@ X_LIBS = @X_LIBS@ X_PRE_LIBS = @X_PRE_LIBS@ YACC = @YACC@ ac_ct_AR = @ac_ct_AR@ ac_ct_CC = @ac_ct_CC@ ac_ct_CXX = @ac_ct_CXX@ ac_ct_F77 = @ac_ct_F77@ ac_ct_RANLIB = @ac_ct_RANLIB@ ac_ct_STRIP = @ac_ct_STRIP@ am__fastdepCC_FALSE = @am__fastdepCC_FALSE@ am__fastdepCC_TRUE = @am__fastdepCC_TRUE@ am__fastdepCXX_FALSE = @am__fastdepCXX_FALSE@ am__fastdepCXX_TRUE = @am__fastdepCXX_TRUE@ am__include = @am__include@ am__leading_dot = @am__leading_dot@ am__quote = @am__quote@ am__tar = @am__tar@ am__untar = @am__untar@ bindir = @bindir@ build = @build@ build_alias = @build_alias@ build_cpu = @build_cpu@ build_os = @build_os@ build_vendor = @build_vendor@ datadir = @datadir@ exec_prefix = @exec_prefix@ host = @host@ host_alias = @host_alias@ host_cpu = @host_cpu@ host_os = @host_os@ host_vendor = @host_vendor@ includedir = @includedir@ infodir = @infodir@ install_sh = @install_sh@ libdir = @libdir@ libexecdir = @libexecdir@ localstatedir = @localstatedir@ mandir = @mandir@ mkdir_p = @mkdir_p@ oldincludedir = @oldincludedir@ prefix = @prefix@ program_transform_name = @program_transform_name@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ x_includes = @x_includes@ SUBDIRS = html HTMLARNAME = tao-${TAO_VERSION}-usermanual-html PSFILENAME = tao-${TAO_VERSION}-usermanual.ps GZIPENV = --best EXTRA_DIST = \ UserManual.tex \ closing_comments.tex \ conceptual_overview.tex \ getting_started.tex \ installation.tex \ introduction.tex \ script_language.tex \ script_reference.tex \ tutorial.tex \ user_interface.tex \ cells.eps \ circle_example.eps \ circle_waves.eps \ compound_example.eps \ instrument_coord_system.eps \ instrvis.eps \ joining.eps \ new.eps \ xandyfreqs.eps CLEANFILES = \ UserManual.bbl \ UserManual.ilg \ UserManual.blg \ UserManual.dvi \ UserManual.ps \ UserManual.log \ UserManual.idx \ UserManual.ind \ UserManual.toc \ UserManual.lof \ UserManual.aux \ ${HTMLARNAME}.tgz \ ${PSFILENAME}.gz MAINTAINERCLEANFILES = introduction.tex all: all-recursive .SUFFIXES: $(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ && exit 0; \ exit 1;; \ esac; \ done; \ echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/UserManual/Makefile'; \ cd $(top_srcdir) && \ $(AUTOMAKE) --gnu doc/UserManual/Makefile .PRECIOUS: Makefile Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status @case '$?' in \ *config.status*) \ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ *) \ echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ esac; $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh $(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh $(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh introduction.tex: $(top_builddir)/config.status $(srcdir)/introduction.tex.in cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ mostlyclean-libtool: -rm -f *.lo clean-libtool: -rm -rf .libs _libs distclean-libtool: -rm -f libtool uninstall-info-am: # This directory's subdirectories are mostly independent; you can cd # into them and run `make' without going through this Makefile. # To change the values of `make' variables: instead of editing Makefiles, # (1) if the variable is set in `config.status', edit `config.status' # (which will cause the Makefiles to be regenerated when you run `make'); # (2) otherwise, pass the desired values on the `make' command line. $(RECURSIVE_TARGETS): @failcom='exit 1'; \ for f in x $$MAKEFLAGS; do \ case $$f in \ *=* | --[!k]*);; \ *k*) failcom='fail=yes';; \ esac; \ done; \ dot_seen=no; \ target=`echo $@ | sed s/-recursive//`; \ list='$(SUBDIRS)'; for subdir in $$list; do \ echo "Making $$target in $$subdir"; \ if test "$$subdir" = "."; then \ dot_seen=yes; \ local_target="$$target-am"; \ else \ local_target="$$target"; \ fi; \ (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ || eval $$failcom; \ done; \ if test "$$dot_seen" = "no"; then \ $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \ fi; test -z "$$fail" mostlyclean-recursive clean-recursive distclean-recursive \ maintainer-clean-recursive: @failcom='exit 1'; \ for f in x $$MAKEFLAGS; do \ case $$f in \ *=* | --[!k]*);; \ *k*) failcom='fail=yes';; \ esac; \ done; \ dot_seen=no; \ case "$@" in \ distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \ *) list='$(SUBDIRS)' ;; \ esac; \ rev=''; for subdir in $$list; do \ if test "$$subdir" = "."; then :; else \ rev="$$subdir $$rev"; \ fi; \ done; \ rev="$$rev ."; \ target=`echo $@ | sed s/-recursive//`; \ for subdir in $$rev; do \ echo "Making $$target in $$subdir"; \ if test "$$subdir" = "."; then \ local_target="$$target-am"; \ else \ local_target="$$target"; \ fi; \ (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ || eval $$failcom; \ done && test -z "$$fail" tags-recursive: list='$(SUBDIRS)'; for subdir in $$list; do \ test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) tags); \ done ctags-recursive: list='$(SUBDIRS)'; for subdir in $$list; do \ test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) ctags); \ done ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES) list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ unique=`for i in $$list; do \ if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ done | \ $(AWK) ' { files[$$0] = 1; } \ END { for (i in files) print i; }'`; \ mkid -fID $$unique tags: TAGS TAGS: tags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ $(TAGS_FILES) $(LISP) tags=; \ here=`pwd`; \ if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \ include_option=--etags-include; \ empty_fix=.; \ else \ include_option=--include; \ empty_fix=; \ fi; \ list='$(SUBDIRS)'; for subdir in $$list; do \ if test "$$subdir" = .; then :; else \ test ! -f $$subdir/TAGS || \ tags="$$tags $$include_option=$$here/$$subdir/TAGS"; \ fi; \ done; \ list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ unique=`for i in $$list; do \ if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ done | \ $(AWK) ' { files[$$0] = 1; } \ END { for (i in files) print i; }'`; \ if test -z "$(ETAGS_ARGS)$$tags$$unique"; then :; else \ test -n "$$unique" || unique=$$empty_fix; \ $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ $$tags $$unique; \ fi ctags: CTAGS CTAGS: ctags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ $(TAGS_FILES) $(LISP) tags=; \ here=`pwd`; \ list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ unique=`for i in $$list; do \ if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ done | \ $(AWK) ' { files[$$0] = 1; } \ END { for (i in files) print i; }'`; \ test -z "$(CTAGS_ARGS)$$tags$$unique" \ || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \ $$tags $$unique GTAGS: here=`$(am__cd) $(top_builddir) && pwd` \ && cd $(top_srcdir) \ && gtags -i $(GTAGS_ARGS) $$here distclean-tags: -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags distdir: $(DISTFILES) @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \ list='$(DISTFILES)'; for file in $$list; do \ case $$file in \ $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \ esac; \ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ if test "$$dir" != "$$file" && test "$$dir" != "."; then \ dir="/$$dir"; \ $(mkdir_p) "$(distdir)$$dir"; \ else \ dir=''; \ fi; \ if test -d $$d/$$file; then \ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ fi; \ cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ else \ test -f $(distdir)/$$file \ || cp -p $$d/$$file $(distdir)/$$file \ || exit 1; \ fi; \ done list='$(DIST_SUBDIRS)'; for subdir in $$list; do \ if test "$$subdir" = .; then :; else \ test -d "$(distdir)/$$subdir" \ || $(mkdir_p) "$(distdir)/$$subdir" \ || exit 1; \ distdir=`$(am__cd) $(distdir) && pwd`; \ top_distdir=`$(am__cd) $(top_distdir) && pwd`; \ (cd $$subdir && \ $(MAKE) $(AM_MAKEFLAGS) \ top_distdir="$$top_distdir" \ distdir="$$distdir/$$subdir" \ distdir) \ || exit 1; \ fi; \ done check-am: all-am check: check-recursive all-am: Makefile installdirs: installdirs-recursive installdirs-am: install: install-recursive install-exec: install-exec-recursive install-data: install-data-recursive uninstall: uninstall-recursive install-am: all-am @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am installcheck: installcheck-recursive install-strip: $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ `test -z '$(STRIP)' || \ echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install mostlyclean-generic: clean-generic: -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) distclean-generic: -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) maintainer-clean-generic: @echo "This command is intended for maintainers to use" @echo "it deletes files that may require special tools to rebuild." -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES) clean: clean-recursive clean-am: clean-generic clean-libtool mostlyclean-am distclean: distclean-recursive -rm -f Makefile distclean-am: clean-am distclean-generic distclean-libtool \ distclean-tags dvi: dvi-recursive dvi-am: info: info-recursive info-am: install-data-am: install-exec-am: install-info: install-info-recursive install-man: installcheck-am: maintainer-clean: maintainer-clean-recursive -rm -f Makefile maintainer-clean-am: distclean-am maintainer-clean-generic mostlyclean: mostlyclean-recursive mostlyclean-am: mostlyclean-generic mostlyclean-libtool pdf: pdf-recursive pdf-am: ps-am: uninstall-am: uninstall-info-am uninstall-info: uninstall-info-recursive .PHONY: $(RECURSIVE_TARGETS) CTAGS GTAGS all all-am check check-am \ clean clean-generic clean-libtool clean-recursive ctags \ ctags-recursive distclean distclean-generic distclean-libtool \ distclean-recursive distclean-tags distdir dvi dvi-am html \ html-am info info-am install install-am install-data \ install-data-am install-exec install-exec-am install-info \ install-info-am install-man install-strip installcheck \ installcheck-am installdirs installdirs-am maintainer-clean \ maintainer-clean-generic maintainer-clean-recursive \ mostlyclean mostlyclean-generic mostlyclean-libtool \ mostlyclean-recursive pdf pdf-am ps ps-am tags tags-recursive \ uninstall uninstall-am uninstall-info-am html: html/UserManual.html ps: UserManual.ps html-archive: html/UserManual.html mkdir /tmp/${HTMLARNAME} cp html/*.html html/*.gif /tmp/${HTMLARNAME} cd /tmp ; ${TAR} czvf ${HTMLARNAME}.tar.gz ${HTMLARNAME} mv /tmp/${HTMLARNAME}.tar.gz . rm -rf /tmp/${HTMLARNAME} psgzip: UserManual.ps gzip ${GZIP_ENV} UserManual.ps mv UserManual.ps.gz ${PSFILENAME}.gz html/UserManual.html: ${EXTRA_DIST} hyperlatex UserManual UserManual.dvi: ${EXTRA_DIST} latex UserManual latex UserManual makeindex UserManual latex UserManual UserManual.ps: UserManual.dvi allneeded UserManual.dvi dvips -f UserManual.ps downloads: psgzip html-archive .PHONY: html ps html-archive psgzip # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. .NOEXPORT: tao-1.0-beta-10May2006/doc/UserManual/introduction.tex.in0000755000372200037200000001223707077441430017673 00000000000000\chapter{Introduction} Welcome to the \tao\ user manual. This manual is for version @TAO_VERSION@ built on @DATE@. \tao\ is a software package for sound synthesis using physical modelling techniques. It is written in C++ and provides a kind of virtual material consisting of masses and springs, which can be used to construct a wide variety of virtual musical instruments. New instruments are described using a text-based synthesis language (contained in what is referred to as a \tao\ \index{script} script). When a script is invoked \tao\ carries out the synthesis described and automatically produces 3-D animated visualisations of the instruments. The animations show the actual acoustic waves propagating through the instruments and play a central role in \tao's user interface. In particular they make it much easier to think of the instruments as tangible physical objects rather than abstract synthesis algorithms. \tao\ will eventually come with full documentation for the C++ class library API (application programming interface) so that it can also be used by those who wish to write their own C++ applications incorporating \tao's capabilities. This is not complete at the present time. \section{Where to find \tao} \tao\ is available from the download section of \TaoWebSite This user manual is also available for separate download either as a tar'd gzip'd archive of HTML files or a gzip'd postscript file. \section{Who was it designed for?} \tao\ was conceived as a compositional tool for electroacoustic and computer music. Therefore more emphasis has been placed on its ability to produce a wide range of interesting and complex sounds than on catering for traditional music based on scales, rhythms, harmony etc. From a personal perspective I wanted to design a synthesis program which would allow me to deal with tangible physical instruments rather than abstract synthesis algorithms. I wanted to be able to construct virtual musical instruments with very complex behaviours and experiment with them in an intuitive physical manner. \section{How \tao\ is structured} \tao\ consists of a library of C++ classes for building synthesis scenarios. The classes provide the means for creating primitive acoustic building blocks, coupling these building blocks together into more complex instruments, applying external excitations, and generating sound output from the instruments. \tao's synthesis language provides the same functionality as the C++ API but is easier to use. In addition to providing a language for creating virtual instruments it also provides an algorithmic score language for playing them. From the user's perspective the synthesis language appears to be interpreted rather than compiled since a script may be invoked with a simple one-line command. In reality though this process involves translating the \tao\ script into C++ first, linking it with the C++ \tao\ library \Filename{libtao.so} and then invoking the executable produced. You shouldn't have to worry about the details of this process when using the synthesis language interface though. \section{What this manual contains} This user manual is divided into eight chapters as follows: \begin{description} \item[1. Introduction] This introductory chapter. \item[2. Building and Installing \tao] Instructions on where to obtain the \tao\ distribution and how to build and install it. \item[3. Conceptual Overview] Introduces the main concepts which should be understood before attempting to use \tao. \item[4. Getting Started] Skips the details and goes straight to a practical example session using \tao. \item[5. Tao's User Interface] Self-explanatory. \item[5. \tao's Synthesis Language in Detail] Gives a detailed description of the synthesis language provided. \item[6. Object Method Reference] A detailed reference for all of \tao's classes which are available within the synthesis language. \item[7. Tutorial] Gives lots of example scripts describing what they do and how. \item[8. Closing Comments] General comments about the current state of \tao\ and areas for future development. \end{description} \section{Typographic conventions used} This manual adopts a number of typographic conventions \index{typographic conventions} which are described below. The \texttt{monospace} font indicates shell window output, filenames and names of environment variables; keywords, functions and operators in \tao's synthesis language; and finally verbatim examples which should be typed exactly as shown. The \textbf{\texttt{monospace bold}} font is used in the index to highlight entries for keywords, functions and operators in \tao's synthesis language. The \emph{italic} font indicates important terminology being introduced for the first time. In addition to the above conventions sometimes it is necessary to indicate where the user needs to supply some values in a \tao\ script. For example in the following script fragment \verb|| and \verb|| would need to be replaced with appropriate values by the user: \begin{verbatim} String myString(, ); \end{verbatim} Finally \tao\ refers to the entire software package whereas \verb|tao| refers to the name of the shell command used for executing a \tao\ script. tao-1.0-beta-10May2006/doc/UserManual/UserManual.tex0000755000372200037200000001642607103064022016611 00000000000000\documentclass[a4paper,twoside]{report} \usepackage{hyperlatex} \usepackage{epsfig} \usepackage{a4} \usepackage{caption} \usepackage{pslatex} \usepackage{float} \usepackage{makeidx} %% These commands are to set the overall format of the html output %% produced by hyperlatex. See the hyperlatex user manual for details. \setcounter{htmldepth}{5} \setcounter{htmlautomenu}{1} \newcommand{\toppanel}{ \begin{rawhtml}\end{rawhtml} \begin{rawhtml}\end{rawhtml} \begin{rawhtml}\end{rawhtml} \begin{rawhtml}\end{rawhtml} \begin{rawhtml}\end{rawhtml} \begin{rawhtml}\end{rawhtml} \begin{rawhtml}\end{rawhtml} \begin{rawhtml}\end{rawhtml} \begin{rawhtml}\end{rawhtml} } \newcommand{\bottompanel}{ \begin{rawhtml}\end{rawhtml} \begin{rawhtml}
\end{rawhtml} \EmptyP{\HlxUpUrl} {\xlink{\htmlimage[ALT="Up" ALIGN=BOTTOM BORDER=0]{up.gif}}{\HlxUpUrl}} { } \\\xlink{\HlxUpTitle}{\HlxUpUrl}\\ \htmlimage[width="167" height="1"]{trans1x1.gif} \begin{rawhtml}\end{rawhtml} \EmptyP{\HlxBackUrl} {\xlink{\htmlimage[ALT="Back" ALIGN=BOTTOM BORDER=0]{back.gif}}{\HlxBackUrl}} { } \\\xlink{\HlxBackTitle}{\HlxBackUrl}\\ \htmlimage[width="167" height="1"]{trans1x1.gif} \begin{rawhtml}\end{rawhtml} \EmptyP{\HlxForwUrl} {\xlink{\htmlimage[ALT="Forward" ALIGN=BOTTOM BORDER=0]{forward.gif}}{\HlxForwUrl}} { } \\\xlink{\HlxForwTitle}{\HlxForwUrl}\\ \htmlimage[width="167" height="1"]{trans1x1.gif} \begin{rawhtml}


\end{rawhtml} } \newcommand{\bottommatter}{ \\ \begin{rawhtml}
\end{rawhtml} \EmptyP{\HlxUpUrl} {\xlink{\htmlimage[ALT="Up" ALIGN=BOTTOM BORDER=0]{up.gif}}{\HlxUpUrl}} {} \\\xlink{\HlxUpTitle}{\HlxUpUrl}\\ \htmlimage[width="167" height="1"]{trans1x1.gif} \begin{rawhtml}\end{rawhtml} \EmptyP{\HlxBackUrl} {\xlink{\htmlimage[ALT="Back" ALIGN=BOTTOM BORDER=0]{back.gif}}{\HlxBackUrl}} {} \\\xlink{\HlxBackTitle}{\HlxBackUrl}\\ \htmlimage[width="167" height="1"]{trans1x1.gif} \begin{rawhtml}\end{rawhtml} \EmptyP{\HlxForwUrl} {\xlink{\htmlimage[ALT="Forward" ALIGN=BOTTOM BORDER=0]{forward.gif}}{\HlxForwUrl}} {} \\\xlink{\HlxForwTitle}{\HlxForwUrl} \htmlimage[width="167" height="1"]{trans1x1.gif} \begin{rawhtml}
\end{rawhtml} \HlxBlk\EmptyP{\HlxAddress} {\html{ADDRESS}\HlxAddress\HlxBlk\html{/ADDRESS}\\}{} \begin{rawhtml}
\end{rawhtml} } \htmltitle{Tao User Manual} \htmldirectory{html} \htmladdress{\small\copyright 1999,2000 Mark Pearson \xlink{m.pearson@ukonline.co.uk}{mailto:m.pearson@ukonline.co.uk} \today} \htmlattributes{BODY}{BACKGROUND="bg.gif"} \title{Tao User Manual} \author{Mark Pearson\\ m.pearson@ukonline.co.uk} \date{\today} \newcommand{\css}[1] {\renewcommand{\HlxMeta} {\begin{rawhtml} \end{rawhtml}}} \W\css{../../taomanual.css} \renewcommand{\textsf}{} \renewcommand{\samepage}{} %% Tao logo typeset in bold font \newcommand{\tao}{\textbf{Tao}} %% TaoWebSite produces the following text in the printed document: %% ... the Tao web site at http://web.ukonline.co.uk/taosynth ... %% In the html document the phrase 'the Tao web site' is made into %% a hyperlink. \newcommand{\TaoWebSite}{\xlink{the Tao home page}[\begin{itemize}\item\Path{http://web.ukonline.co.uk/taosynth}\end{itemize}]{http://web.ukonline.co.uk/taosynth}} % Image includes an eps image for TeX and either a jpg or gif for html % Args: % #1 - base name of image file % #2 - extra instructions for epsfig % #3 - html image file extension [gif,jpg] \newcommand{\Image}[3]{ \texonly{\epsfig{file=#1.eps,#2}} \htmlonly{\htmlimage{#1.#3}} } %% Commands for classifying index entries and typesetting %% them in the main text accordingly \newcommand{\hierindex}[1]{\texonly{\index{#1}}} \newcommand{\Term}[1]{\emph{#1}\index{#1}} \newcommand{\Index}[2]{#1\index{#1!#2}} \newcommand{\Prog}[1]{\texttt{#1}} \newcommand{\ProgIndex}[1]{\texttt{#1}\index{#1@\texttt{#1}}} \newcommand{\Class}[1]{\texttt{\texttt{#1}}} \newcommand{\ClassIndex}[1]{% \texttt{#1}% \index{classes!#1@\texttt{#1}}% \index{#1@\texttt{#1} class}} \newcommand{\Device}[1]{\texttt{#1}} \newcommand{\DeviceIndex}[1]{% \texttt{#1}% \texonly{\index{devices!#1@\texttt{#1}}}% \index{#1@\texttt{#1} device}} \newcommand{\Instr}[1]{\texttt{#1}} \newcommand{\InstrIndex}[1]{% \texttt{#1}% \texonly{\index{instrument!primitive types!#1@\texttt{#1}}}% \index{#1@\texttt{#1} instrument type}} \newcommand{\Attr}[1]{\texttt{#1}} \newcommand{\AttrIndex}[1]{% \texttt{#1}% \texonly{\index{attributes!#1@\textbf{\texttt{#1}}}}% \index{#1@\textbf{\texttt{#1}} attribute}} \newcommand{\Operator}[1]{% \texonly{\index{operators!#1@\textbf{\texttt{#1}}}}% \index{#1@\textbf{\texttt{#1}}}} \newcommand{\MathFunction}[1]{% \texonly{\index{math functions!#1@\textbf{\texttt{#1}}}}% \index{#1@\textbf{\texttt{#1}}}} \newcommand{\Type}[1]{% \texttt{#1}% \texonly{\index{types!#1@\textbf{\texttt{#1}}}}% \index{#1@\textbf{\texttt{#1}} type}} \newcommand{\Kwd}[1]{\texttt{#1}} \newcommand{\KwdIndex}[1]{% \texttt{#1}% \texonly{\index{keywords!#1@\textbf{\texttt{#1}}}}% \index{#1@\textbf{\texttt{#1}} keyword}} \newcommand{\Ctrl}[1]{\texttt{#1}} \newcommand{\CtrlIndex}[1]{% \texttt{#1}% \texonly{\index{control structures!#1@\textbf{\texttt{#1}}}}% \index{#1@\textbf{\texttt{#1}} control structure}} \newcommand{\Method}[1]{\texttt{#1}} \newcommand{\MethodIndex}[1]{% \texttt{#1}% \texonly{\index{methods!#1@\textbf{\texttt{#1}}}}% \index{#1@\textbf{\texttt{#1}} method}} \newcommand{\Var}[1]{\texttt{#1}} \newcommand{\VarIndex}[1]{% \texttt{#1}% \texonly{\index{variables!#1@\textbf{\texttt{#1}}}}% \index{#1@\textbf{\texttt{#1}} variable}} \newcommand{\Decl}[1]{#1} \newcommand{\DeclIndex}[1]{% #1% \texonly{\index{declarations!#1@\emph{#1}}}% \index{#1@\emph{#1} declaration}} \newcommand{\Filename}[1]{\texttt{#1}} \newcommand{\Statement}[1]{#1} \newcommand{\StatementIndex}[1]{% #1% \texonly{\index{statements!#1}}% \index{#1 statement}} \newcommand{\EnvVar}[1]{\texttt{#1}} \newcommand{\Path}[1]{\texttt{#1}} \newcommand{\Lib}[1]{\texttt{#1}} \newcommand{\Rpm}[1]{\texttt{#1}} \newenvironment{CodeFragment}{\begin{verbatim}}{\end{verbatim}} %\setmarginsrb{35mm}{10mm}{30mm}{35mm}{20pt}{20pt}{20pt}{36pt} \makeindex \T\raggedbottom \begin{document} \maketitle \renewcommand{\baselinestretch}{1} \small\normalsize \T\tableofcontents \T\listoffigures \include{introduction} \include{installation} \include{conceptual_overview} \include{getting_started} \include{user_interface} \include{script_language} \include{script_reference} \include{tutorial} \include{closing_comments} \printindex \end{document} tao-1.0-beta-10May2006/doc/UserManual/closing_comments.tex0000755000372200037200000003400207101676054020102 00000000000000\chapter{Closing Comments} This closing section of the User Manual is basically a place for anything else I thought was important enough to include, but couldn't find a suitable place for elsewhere. \section{Background to \tao's design and implementation} During my Music Technology masters degree at the University of York I was impressed by freeware audio and synthesis tools such as \Prog{Csound}. One of the things that impressed me about Csound in particular was that it was a synthesis language and allowed a finite set of primitive building blocks to be assembled in an infinite number of ways. However, my experience as a musician playing a variety of acoustic instruments told me that whilst Csound's unit generator approach was quite powerful, it also had several shortcomings. For example, when playing an acoustic instrument such as a guitar or even just experimenting with `found sounds' there is something very direct and intuitive about the mode of experimentation. If you want something to make a louder and brighter sound you just hit it harder! Whilst Csound's unit generator approach does allow you to design instruments with input parameters and feed different values into these inputs in a score, it doens't allow you to think directly in terms of forces, velocities, spatial positioning of excitations etc. So I wanted to set out to design a synthesis program which would carry on the tradition of programs like Csound, in providing an open-ended synthesis language, but would be capable of creating much more tangibly physical instruments. Another item which was high on the agenda was to be able to visualise the instruments. \tao\ arose out of my interests in a number of different areas including musical performance, electroacoustic music, computer modeling of complex dynamical systems, cellular automata, and computer graphics. I have thought for a long time that whilst GUIs (graphical user interfaces) are invaluable tools in certain situations there are still many things which are more elegantly expressed in text/language form. Take general computer programming languages for example, or the rapidly growing number of `mark-up languages' such as HTML, XML, VRML. Text is a very powerful tool for communicating structured ideas and has the advantage that it can serve as the basis for more user friendly GUI-based tools to sit on top. It is for this reason that I concentrated my efforts on designing a text based interface to \tao\ which would be simple to use, clear to read and above all accessible to musicians with some degree of technical competency (having used tools such as Csound for example). Having stated this however it is likely that the format of the language and the lack of a GUI will be addressed in the future, along with several other aspects of the user interface. \tao\ was originally developed as part of my DPhil at the University of York, England and then subsequently during a one year visiting research fellowship to the Australian Centre for the Arts and Technology at the Australian National University in Canberra. My DPhil addressed the question of precisely why it is that digitally synthesised sounds often lack the \emph{warmth}, \emph{life}, and \emph{organic} qualities of acoustically produced sounds, whether musical in the traditional sense or not. What came out of this work, apart from a thesis of course, was \tao. As mentioned earlier on I wanted a system which would be capable of producing \emph{organic sounds}. The term \emph{organic} is quite difficult to define precisely but my thesis \emph{Synthesis of Organic Sounds for Electroacoustic Music: Cellular Models and the TAO Computer Music Program} does a better job of addressing the issues than I have scope to do here. Very briefly though the term \emph{organic} is used to refer to sounds which are: \begin{itemize} \item complex \item fluid \item dynamic \item coherent \item lively \item suggestive of physical and energetic causality \end{itemize} The term \Term{coherence} is used to refer to the fact that in sounds produced by physical means, the transient behaviour, the perception of the sound having been produced by some physical mechanism and the overall character of the sound hang together very well. This cannot be said of many digitally synthesised sounds, even those produced by some physical modeling techniques. This problem of synthesising \emph{complex}, \emph{coherent} and \emph{organic} sounds was the main focus of the whole project. The original design goals which have been adhered to throughout \tao's development were to produce a system which would have the following features: \begin{itemize} \item capable of synthesising a wide variety of acoustic and instrumental-like sounds with organic qualities; \item relatively straightforward to use, making physical modeling accessible to those without a strong maths or physics background without compromising the power or flexibility of the tool; \item based around a flexible and open-ended synthesis language following in the tradition of other synthesis languages such as Csound (this objective is ongoing, the current synthesis language used by \tao\ is only one possible language for controlling it). \end{itemize} \section{The computational expense of Tao's synthesis engine} \tao\ takes what has been referred to as the `brute force' approach to physical modelling and as such is not as efficient as some of the digital waveguide models developed by Julius Smith et al. However at the time of designing \tao\ I made a conscious decision to steer away from the obsession with real-time performance and look at what would be possible if I just concentrated on the conceptual structure of the system. First and foremost I wanted to design a system which made instruments which were tangible objects. As a musician I am accustomed to being able to experiment with sound in a direct, physical and intuitive manner and having a system which was capable of visualising the instruments was quite high on the list of priorities. At least if I couldn't actually get my hands on the instruments I could see them, which would in turn fuel my imagination for things to try out. Real instruments such as stringed or percussion instruments have a wonderful property that their 'user interface' is spatially distributed, and more importantly, doing things to the instrument at different spatial locations leads to markedly different timbral results. In my DPhil thesis I argued that details which make a huge difference to the aesthetic appeal of the sounds produced from a physical model are often simply missed out in the name of real-time performance. I do not make any great claims about my model being so much more mathematically accurate than any others simply because it needs more processing power, but one thing I would say is that in the majority of cases musicians and composers who have heard the sounds which \tao\ is capable of producing have commented on their \emph{organic} and inherent musical qualities, which cannot be a bad thing. Besides, with the exponential growth in computing power, the number crunching needed by \tao\ simply may not be an issue in the near future. The calculations employed to animate the model are described in detail in my thesis. As they stand I am sure that improvements could be made in the name of efficiency and optimisation although they have already been optimised to an extent. There may be ways in which the efficiency could be radically improved without compromising the quality of the sounds produced and indeed I would be very interested to hear any ideas from individuals more mathematically skilled than myself. \tao\ is based upon mathematical skills I picked up at school level, so there should be room for improvement! \section{Deficiencies in Tao's synthesis language} \label{section:script_deficiencies} \tao's synthesis language was developed primarily as a test-bed for the synthesis engine. It has evolved into a usable language but lacks several features for larger scale compositional work including: \begin{itemize} \item Encapsulation of events \item Encapsulation of instrument components \item Table generating and reading functions \end{itemize} What is meant by `encapsulation of events' is the ability to describe a complex algorithm for producing some kind of high-level event and then place this algorithm inside a black box with input parameters. The algorithm would then be invoked whenever it was needed (much like a C or C++ function) using just its name and arguments. The addition of this feature would make it a much simpler matter to produce complex multi-layered textures of sound. Encapsulation as applied to instruments refers to the ability to create compound instruments where the components of the instrument are arranged hierarchically with parent-child relationships. For example an instrument named `guitar' might have child components named `string1', `string2' etc. In order to achieve this the syntax of \tao's synthesis language would need to be modified to allow components to be created within the scope of other components, much as local variables may be declared within C or C++ functions. It would also be possible to describe template instruments which would act as templates for whole families of instruments with similar characteristics. For example the description of a `guitar' template instrument would allow the construction of multiple instances each having their own body sizes and string tunings, but with aspects of the physical structure common to each instance. Table reading functions are an essential part of any synthesis program and the only way they can be implemented at the moment is by setting up arrays of values by hand and accessing (and interpolating them) yourself with parameters declared in the script. Of course all the math library functions are available in the synthesis language so it is feasible to write table initialisation code in the Init part of the score, but it is still cumbersome compared with \Prog{Csound}'s provision of table generating features. \section{New Devices} As it stands there are only a handful of devices available for use. A long term goal is to expand this set of available devices in order to make \tao a more powerful and enticing environment for sound design. \section{Parallel Processing} I did carry out some initial investigations into how \tao could be parallelised whilst at the Australian Centre for the Arts and Technology during 1997-8 and came up with the idea of using Posix threads (pthreads) to split the number crunching performed by the synthesis engine up into separate threads. Unfortunately the work went no further than that but will be resumed one day if I have access to a multi-processor machine. \section{The User Interface} As with the parallelisation of \tao's synthesis engine I did some evaluation of the various options available both on the SGI and Linux platforms for building a GUI for \tao\ whilst at ACAT. However at the time there were too many other things to be done to improve the basic synthesis engine and I never atually implemented anything concrete. Since then the main GUI toolkits for Linux (Gtk and Qt) have become more widely used and documented and as such are obvious choices. Of course the use of Qt would also make it very easy to create a port for other platforms such as MS Windows. I have had some more general thoughts on the subject of GUIs though and having had some brief experience of 3-D animation packages such as Side Effects' Houdini and more recently Blender I think that many of the concepts used in their interfaces would be applicable to \tao\. To be more specific the ability of such packages to control and animate the values of any parameters with the use of various spline, bezier and NURBS curves is directly applicable. The other obvious area in which there is overlap is that \tao\ is basically a modeling tool and many of the concepts used in the user interfaces of animation packages such as object heirarchies; different views, layers of objects etc. would also be applicable. Both Houdini and Blender allow the evolution of objects to be described in a procedural manner through the use of use of scripting. Blender in particular uses the Python OO scripting language. \tao\ could also benefit from the dual GUI/scripting approach. To summarise, the following features would be desirable in a new interface for \tao: \begin{itemize} \item a curve editor with editable curves representing arbitrary parameters; \item a graphical instrument editor with a suitable toolbox; \item a 3D visualisation window with rotate/zoom/translate capabilities; \item some kind of data block structure showing hierarchies of components, devices and other objects and their relationships; \item some kind of integrated graphical and text based score system where changes in the graphical representation would immediately lead to changes in the text version and vice versa. \end{itemize} \section{Contributing to Tao's development} Finally a word on how you can contribute to \tao's development. \begin{itemize} \item Email me if you find any glaring errors or mistakes in this manual or the software itself. \item Tell your friends about \tao. The more interest there is in \tao\ the more likely I am to continue development. \item If anyone would like to set up a CVS server or mailing list I would be happy to cooperate. I may eventually do both myself as and when I get time. \item I am happy to discuss ways in which any aspect of \tao\ can be improved or developed. \end{itemize} To conclude -- my vision when I started designing \tao\ was to create a powerful and intuitive sound synthesis tool which would allow composers to create their own `acoustic' instruments to order. There is still a long way to go to realise this vision but \tao\ is already fun to play with in its present state. As machines become faster and faster it will become possible to experiment with increasingly complex (and realistic) instruments, eventually in real-time. The provision of a sophisticated GUI and maybe even haptic feedback interfaces will eventually bring \tao\ closer to this goal. In the meantime I hope you find \tao\ useful and enjoy using it! Mark Pearson. tao-1.0-beta-10May2006/doc/UserManual/conceptual_overview.tex0000755000372200037200000005604207077105564020637 00000000000000\chapter{Conceptual Overview} \label{section:conceptual_overview} This section introduces the main concepts which you will need to have some grasp of in order to use \tao\ at anything but the simplest level. Topics covered include \tao's \emph{cellular material}; \emph{instruments}; \emph{devices}; \emph{access points}; \emph{parameters}; and \emph{pitches}. \section{\tao's Cellular Material} \label{section:cellular_material} \tao\ is based around the notion of building complex vibrating structures from simpler acoustic building blocks. In order to realise this goal a general purpose adaptable acoustic material is provided. The material consists of point masses arranged in a regular grid pattern and connected together with springs. The overall structure of the material is shown in figure \ref{fig:cells}. \begin{figure}[htb] \begin{Label}{fig:cells} \begin{center} \Image{cells}{height=5cm}{gif} \end{center} \caption{A small portion of \tao's cellular acoustic material} \end{Label} \end{figure} Each point mass or \Term{cell} maintains a set of state variables for its position, velocity, mass, etc., and the overall state is updated in discrete time steps or \Term{ticks} according to rules which take into account a cell's own state and the states of its immediate neighbours. More specifically a cell's spring connections to its neighbours exert forces on the cell and from these forces Newton's laws of motion can be used to calculate the acceleration and velocity of the cell. Note that the cells are constrained to have one degree of freedom (in the direction of the $z$ axis). This has two practical advantages: \begin{itemize} \item It makes the calculations involved in animating the material simpler. \item It also makes it a simple matter to generate time varying waveforms from the vibrations in the material since all cells will vibrate about a fixed zero reference point at $z=0$ so long as at least one cell is fixed at that position. \end{itemize} One question which has often been asked in relation to \tao's cellular material is: `have you experimented with 3D blocks of material?'. The answer to this question is no, for the following reasons. Firstly, the computational expense of such instruments would be prohibitive, and secondly, although the restriction of working with 2D instruments may at first seem like a limitation, in practice it doesn't significantly affect \tao's ability to produce an wide variety of interesting sounds. \subsection{Cell Attributes} \label{section:cell_attributes} The most important \Term{attributes} maintained by each cell are its \Attr{mass}, \Attr{position}, \Attr{velocity}, \Attr{force} and lastly \Attr{velocityMultiplier}. Not surprisingly these are used to keep track of the cell's state of motion and the forces acting upon it. The \Class{Cell} class is unusual in that it is seldom dealt with directly. However we will see that many of \tao's other classes have attributes which are often accessed and set via \Term{methods} The \Attr{velocityMultiplier} attribute is quite important. It holds a value in the range [0..1] and the velocity of the cell is multiplied by this value on each tick. This has the effect of dissipating energy (if the value is $<$ 1) and thus damping the vibrations of the cell. Each cell can have a different value for this attribute leading to non-uniform damping of the material and this feature is a very important tool for controlling the vibrational characteristics of the material as we will see later on in this manual. For example with a simple string-like instrument consisting of a single row of cells linked together with springs, damping small regions at either end of the string more highly than the rest of the cells causes the higher frequency vibrations to die away more quickly than the lower ones. This leads to a more natural string-like spectral decay in the sounds produced by the instrument, whereas a string with uniform damping exhibits no significant change in the distribution of spectral energy as the sound evolves. It is probably safe to say that all physically produced sounds exhibit some kind of spectral evolution, and as a general rule non-uniform damping always produces more interesting sounds from \tao\ instruments than uniform damping. The other main attributes that each cell maintains are pointers to its neighbours \Attr{north}, \Attr{east}, \Attr{south}, \Attr{west}, \Attr{neast}, \Attr{nwest}, \Attr{seast} and \Attr{swest}. Each pointer indicates to a particular cell that it is connected to a neighbouring cell via a virtual spring. Similarly the neighbouring cell will reciprocate by keeping a pointer to the first. You do not need to deal with these pointers directly as an end-user \tao\ but it is worth knowing that they are there. The final attribute is used to store other aspects of the cell's state, such as whether it is locked or free to move. This attribute is called \Attr{mode}. \subsection{The Emergent Behaviour of the Material} Having described the microscopic structure of the cellular material it is now time to say something about its macroscopic behaviour. One of the most appealing features of computer models in which many simple elements interact on a local basis according to well-defined rules is that they often exhibit interesting \Term{emergent behaviour}. In \tao's case the material appears to behave (not surpisingly) like an continuous elastic sheet when viewed from a distance. Figure \ref{fig:circle_example} shows a typical piece of \tao's material, in this case a circular sheet which has had a short impulse applied at a single point. The image is a snapshot taken some short time interval later and clearly shows wavefronts spreading out from the point of impact and also reflecting off of the boundary of the object. \begin{figure}[htb] \begin{Label}{fig:circle_example} \begin{center} \Image{circle_example}{height=6cm}{gif} \end{center} \caption{Screenshot of typical \tao\ instrument} \end{Label} \end{figure} In the graphical representation used the individual cells and springs are not visible. Instead what we see is a wireframe representation in which each line represents a single row of cells. Note how smoothly contoured the waves are, giving the impression that the material is continuous and elastic in behaviour. \subsection{Generating Sound Output from the Material} In order to generate output waveforms the vibrations of the material are `listened' to directly. In order to achieve this a `sensor' is placed on the surface of the material at a chosen point and a time-varying trace of the motion of the point with respect to the $z$ axis is written to an output file. This numerical data can then be played back as digital audio samples. Output signals may be derived from mathematical expressions involving more than one point on an instrument. In addition, the positions of the points from which the signals are generated may be moved around under algorithmic control. These are just two of the tools at your disposal for creating interesting dynamically evolving sounds. \section{Instruments and Devices} \label{section:instruments_and_devices} Although the cellular material is actually composed of many hundreds of individual objects representing the cells and springs, from the user's point of view a higher level of abstraction is provided for creating and interacting with pieces of the material. This abstraction comes in the form of \emph{instruments}\index{instrument} and \emph{devices}\index{device}. \tao\ provides a set of classes for creating primitive acoustic building blocks. These are derived from a generic \ClassIndex{Instrument} class and include \Instr{String}, \Instr{Rectangle}, \Instr{Circle}, \Instr{Ellipse} and \Instr{Triangle} \texonly{\index{instrument!building blocks}}. The \Instr{String} class creates a single line of cells and springs whilst the other classes create 2-D sheets of material in a variety of shapes. Using these instrument classes you don't need to worry about creating the individual cells or springs which link them together as this is taken care of for you. It should be mentioned here that in the rest of this document the generic term \Term{instrument} is used to refer both to these simple building blocks and also more complex arrangements in which several pieces of material are coupled together. In the latter case the term \Term{compound instrument} is used. A number of other classes derived from a common \ClassIndex{Device} class are also provided. Devices are objects which: \begin{itemize} \item allow the primitive instruments listed above to be coupled together into more interesting \Term{compound instruments}; \item provide the means for applying external excitations to the instruments; \item enable sound output to be generated by `listening' to points on instruments, writing the resulting time varying waveforms to sound files. \end{itemize} Devices which are available in the current version of \tao\ include bows, hammers, connectors, stops and outputs. The purpose of each of each type of device is explained in the following sections. But before moving on another fundamental object class needs to be introduced -- the \Term{access point}. Whenever a device interacts with an instrument in some way an access point is involved. You don't need to worry too much about how to use them at the moment but they are described later on in section \ref{section:access_points}. \subsection*{The Bow Device} \label{section:bow_device} \index{Bow device} The bow device provides the user with a model of the interaction between a bow and an instrument. It works by mathematically modelling the static and dynamical frictional forces which occur between the bow and the instrument. Each bow device has the following user accessible attributes: \begin{description} \item[\Attr{velocity}] -- the current velocity of the bow. \item[\Attr{force}] -- the downward force applied to the bow. \end{description} The bowing model used in this device is based loosely upon a model developed by Woodhouse. \subsection*{The Hammer Device} \label{section:hammer_device} \index{Hammer device} The Hammer device provides a generalised mechanism for producing percussive sounds. A Hammer device has the following attributes: \begin{description} \item[\Attr{mass}] -- the mass of the hammer. \item[\Attr{height}] -- the initial height from which the hammer is dropped. \item[\Attr{position}] -- the current height of the hammer. \item[\Attr{initVelocity}] -- the initial velocity of the hammer. \item[\Attr{velocity}] -- the current velocity of the hammer. \item[\Attr{maxImpacts}] -- the maximum number of the impacts with the target instrument. \item[\Attr{numImpacts}] -- the number of impacts with the target instrument since the hammer was dropped. \item[\Attr{gravity}] -- gravitational acceleration acting upon the hammer. \item[\Attr{damping}] -- degree of damping applied to the hammer. \item[\Attr{hardness}] -- how hard the impact surface of the hammer is. \end{description} All of these parameters may be altered under algorithmic control except the number of impacts which is read only. \subsection*{The Connector Device} \label{section:connector_device} \index{Connector device} The Connector device provides a flexible mechanism for coupling instrumental components together and coupling points on instrumental components to fixed \Term{anchor} points. It does so by installing springs between the access points or anchors specified. Anchor points may be numerical constants (usually 0.0) or arbitrary expressions, the latter being useful for driving an instrument with an external signal (external to the instrument, not \tao\ itself). The technique of connecting an access point to a fixed anchor point is sometimes useful for restricting the amplitude of vibrations at certain points on an instrument. For example a component might have too many low frequency partials making the sound too bottom-heavy in which case various points on the instrument can be connected to zero anchor points allowing only the higher partials to continue vibrating. An extra attribute allows the strength of the installed spring to be set. This takes a value in the range [0..1] normally although higher values may work. One of the most powerful features of \tao\ lies in the fact that the coordinates specifying the position of an access points do not have to be constant. They can be time-varying values derived from expressions in the score. This leads to the ability to create instruments which morph structurally as they are being played. The Connector device is therefore one of the most important provided by \tao\ since it enables complex, dynamically evolving instruments to be constructed. \subsection*{The Output Device} \label{output_device} \index{Output device} The Output device provides a general means for writing floating point samples to output files. The samples are initially un-normalised but the resulting data files may be normalised and converted into WAV format sound files with a separate program \Prog{tao2wav}. The minor inconvenience of having to convert \tao\ output files into a more usable format as a separate post-processing stage is imposed for good reason. Firstly it does have the advantage that the user doesn't have to worry about sound samples going out of range. Also, with a model which is heavily based around floating point calculations and physically vibrating entities it is impossible to know the amplitude of the vibrations in advance. The present version of \tao\ only allows one and two channel output files but this will be changed in future releases to allow for arbitrary numbers of channels. \subsection*{The Stop Device} \label{stop_device} \index{Stop device} The Stop device provides a mechanism for producing specific pitches from a string by stopping or fretting it, i.e. temporarily changing its effective vibrating length. The Stop device is not an entirely accurate model of how a stopped string behaves and will probably be refined in future releases. It currently works by installing a Connector device between the specified access point and a fixed anchor position at 0.0. This restricts the vibrations of the string at the access point. In addition there is a `damping' attribute which causes a small region around the access point to be more highly damped than the rest of the string. This causes the string to almost stand still at the access point, which is the desired effect. \subsection{The Information Needed to Create an Instrument} When a new instrument is created three pieces of information are required from the user in the case of rectangular and elliptical sheets and two in the case of strings and circular sheets. These are: \begin{itemize} \item A frequency or pitch specifying the dimensions of the instrument in the $x$ direction \item A frequency or pitch specifying the dimensions of the instrument in the $y$ direction (for rectangular and elliptical sheets only) \item A decay time \end{itemize} The dimensions of a new instrument are always described in terms of pitches or frequencies rather than physical units such as metres or millimetres. For example when creating a new string the pitch specified is used to determine the length of the string. You may be thinking `what about the tension in the string?', but in \tao's cellular material the tension is fixed at an optimum value which gives the best frequency response, so the only factor affecting the pitch of a string is its length and vice versa. In the case of a rectangular sheet two pitches or frequencies are required. The first relates to the time taken for a wavefront to make the round trip from the left hand side of the sheet to the right and back again (travelling in the $x$ direction). The second relates to the time taken for a wavefront to make the round trip from the bottom to the top and back again (travelling in the $y$ direction). \hierindex{instrument!information needed to create} \begin{figure}[hbt] \begin{Label}{fig:xandyfreqs} \begin{center} \Image{xandyfreqs}{height=7cm}{gif} \end{center} \caption{Relationship between x and y frequency and an instrument's size} \end{Label} \end{figure} The precise relationship between the frequencies and dimensions of the various instrument types is illustrated by figure \ref{fig:xandyfreqs}. The constant \verb|Hz2CellConst| is defined by \tao\ and is used to translate a frequency into the appropriate number of cells required to produce that frequency of vibration. In order to explain this more clearly figure \ref{fig:circle_waves} shows four snapshots of a circular sheet having had a short impulse applied at its centre. The white arrows indicate part of the wavefront traveling across the sheet in the $x$ direction, reflecting back off the boundary and eventually ending up back at the starting point again. Once the wavefront has traveled all the way to the other side of the sheet and then back to the centre again it has made one round trip. The speed of wave propagation is fixed for \tao's material so the \verb|Hz2CellConst| constant can be used to calculate how many cells it takes to produce the correct period $T$, and hence frequency $1/T$. \begin{figure}[htb] \begin{Label}{fig:circle_waves} \begin{center} \Image{circle_waves}{height=7cm}{gif} \end{center} \caption{Round trip of a wavefront in a circular sheet} \end{Label} \end{figure} The final piece of information required by all new instruments is a decay time, the time taken for vibrations to naturally die away when the instrument is excited in some way and then left to vibrate freely. The value given is used to calculate a default value for the \verb|velocityMultiplier| attribute of each cell. This initially gives the instrument uniform damping although this uniform behaviour can be subsequently altered by damping local regions of the instrument. More of this technique in section [TO DO: WRITE THIS SECTION]. \section{Access Points} \label{section:access_points} In order for \tao\ to provide an interface between instruments and devices another key object is needed: the \Term{access point}. Access points allow forces to be applied to the material and also for the physical attributes of the material to be read off at \emph{any}\/ point, not just at the discrete set of points where cells exist. This interpolation facility is one of the most important as it overcomes some of the limitations associated with the material being discrete in nature. An example might be trying to simulate a string being stopped to a particular pitch. Without the ability to interpolate the position at which the stop is applied it might not be possible to achieve the desired pitch precisely. \begin{figure}[htb] \begin{Label}{fig:instrument_coord_system} \begin{center} \Image{instrument_coord_system}{height=8cm}{gif} \end{center} \caption{The Instrument Coordinate System} \end{Label} \end{figure} In short, all interactions between \tao's cellular material and the outside world take place via access points. This is probably a good place to introduce the notion of the \emph{instrument coordinate system}\hierindex{instrument!coordinate system}. This coordinate system allows points in the range $(0..1, 0..1)$ to be specified. All instruments, regardless of their shape and size use the same normalised coordinate system as illustrated in figure \ref{fig:instrument_coord_system}. Of course for some instruments such as the circular sheet depicted some points (such as point \textbf{a}) will be invalid. If a script attempts to use such an access point nothing will happen. If the physical attributes are read off the instrument at such a point, they will all return values of zero. Note also that in the case of the string only the $x$ coordinate needs to be specified. \section{Instrument Visualisations} \label{instrument_visualisations} \hierindex{instrument!visualisation facility} \tao\ is capable of producing visualisations of the instruments constructed when a script is invoked. We have already seen one example of this is figure \ref{fig:circle_example}, but in that example the instrument only showed a single circular sheet of material. Figure \ref{fig:compound_example} shows a \Term{compound instrument} consisting of five strings attached to a rectangular sheet. Access points are marked by small red points on the image and in this case they show that the left hand sides of each string are coupled to points on the rectangular sheet. \begin{figure}[htb] \begin{Label}{fig:compound_example} \begin{center} \Image{compound_example}{height=8cm}{gif} \end{center} \caption{Screenshot of a compound instrument} \end{Label} \end{figure} It is possible to translate, zoom, and rotate the image by holding down the left, middle and right mouse buttons respectively and moving the mouse. \tao\ automatically labels instruments and devices with their names (the names they are given when they are created in a script) and it is possible to toggle both types of labels on and off in cases where the graphics window becomes too cluttered with information. This is achieved by pressing the \textbf{I} key to toggle instrument labels on and off, and the \textbf{D} key to toggle device labels. \section{Parameters} \label{section:parameters} The term \Term{parameter}\/ is used as a generic term to refer to all numerical variables in \tao. There are floating point and integer parameters and the latter are declared as either being of type \verb|Integer|, \verb|Counter| or \verb|Flag|. These types are only used to make the intended function of a particular integer variable clear to the human reader. As far as the system is concerned they are functionally identical. \section{Pitches and Frequencies} \label{section:pitches_and_frequencies} The Pitch\index{Pitch} object provides a generalised mechanism for expressing and converting between various pitch and frequency formats. The formats supported are as follows: \begin{itemize} \item \texttt{\emph{value} Hz} (cycles per second, analogous to Csound's cps notation); \item \texttt{\emph{octave}.\emph{semitone}} (analogous to Csound's pch notation); \item \texttt{\emph{octave}.\emph{decimal}} (analogous to Csound's oct notation); \item note name notation (the pitch is represented as a character string). \end{itemize} In the last case the pitch names \verb|C-G| can be used followed by an optional \verb|b| for flat or \verb|#| for sharp. The basic pitch name of the note is then followed by an octave number (whose value has the same meaning as the integer parts of the \verb|pch| and \verb|oct| notations). Finally an optional microtonal adjustment may be added in the form of a fraction \verb|+/| or \verb|-/| which adds/subtracts a fraction of a semitone to/from the pitch given. Some practical examples are given below: \begin{verbatim} Pitch p1 = 110.5 Hz; Pitch p2 = C#5+1/2; Pitch p3 = 8.05 pch; Pitch p4 = 6.1764 oct; \end{verbatim} Pitch methods include: \begin{description} \item[asPitch()] returns a number representing the pitch converted to pch notation; \item[asOctave()] returns a number representing the pitch converted to oct notation; \item[asFrequency()] returns a number representing the pitch converted to a frequency; \item[asName()] returns a character string representing the name of the pitch. \end{description} tao-1.0-beta-10May2006/doc/UserManual/getting_started.tex0000755000372200037200000001606707101672106017733 00000000000000\chapter{Getting Started} \label{section:getting_started} In this section we look at a typical session with \tao\ from beginning to end. I will assume that you have successfully installed the package and that the test script worked OK. \section{Writing a script} First of all open a new text file in your favourite text editor and copy the following text into it: \begin{verbatim} Audio rate: 44100; String string(200 Hz, 20 secs); Output output(stereo); Init: string.lockEnds(); ... Score 20 secs: At 0 secs for 1 msecs: string(0.2).applyForce(1.0); ... output.chL: string(0.1); output.chR: string(0.9); ... \end{verbatim} Now save the file as ``new.tao''. In plain English this script does the following: \begin{enumerate} \item declares the audio sampling rate for any output files to be 44.1 KHz \item declares a \emph{string} instrument called \verb|string| \item declares a two channel \emph{output} device called \verb|output| \item initialises the string by locking both ends (fixing them at their initial position: $z=0$) \item states that the \emph{performance} will last for 20 seconds \item applies a fixed force of magnitude 1.0 to a point on the string one fifth of the way along its length (from the left hand side) for a short time interval (0 seconds to 0.001 seconds) \item writes the movements of the string out to a stereo output file called ``new\_output.dat'' with the left and right channels following the movements of a point one tenth of the way along its length and another point nine tenths of the way along the string, respectively. \end{enumerate} In case you are wondering, the name of an output file is formed by appending the name of the output device onto the name of the script (minus the \verb|.tao| extension) and adding a \verb|.dat| extension, indicating that the file contains raw floating point data, i.e. ``new\_output.dat''. These files require further processing before they can be played back. See section \ref{section:output_files}. \section{Executing the script} To execute this script simply type the following: \begin{verbatim} tao new \end{verbatim} \tao\ should respond with the following messages in the shell window: \begin{verbatim} ======================================== | Tao (c) 1996-99 Mark Pearson | | Sound Synthesis with Physical Models | ======================================== Processing new.tao Making new.exe Executing new.exe Sample rate=44100 KHz Score duration=20 seconds \end{verbatim} You should then see the \emph{instrument visualisation window} open. It should look something like the following: \begin{figure}[h] \begin{Label}{fig:new} \begin{center} \Image{new}{height=6cm}{gif} \end{center} \caption{The instrument visualisation window generated by script new.tao} \end{Label} \end{figure} When the visualisation window opens \tao\ is initially in \Term{pause mode}. To get it out of this mode you should press the right cursor key once. You can pause the whole system again by pressing the left cursor key at any point in time. If you repeatedly press the right cursor key you will see that the animation begins to move more and more rapidly although eventually it becomes less smooth. If you now repeatedly press the left cursor key, the animation slows down again and becomes smoother. The reason for this is that it is possible to change the frequency with which the visualisation window is updated. \tao\ has a \emph{synthesis engine} which keeps track of all the instruments and devices created in a script, and carries out all the calculations involved in bringing them to life. It also has a \emph{graphics engine} which is responsible for displaying the instruments and devices in the visualisation window. Pressing the left and right cursor keys simply changes how frequently the graphics engine visualises what is going on inside the synthesis engine. Displaying the instruments and devices on every tick of the synthesis engine leads to smooth animations but at the expense of making the whole system slow down. Conversely, displaying the instruments less frequently gives a bigger slice of the processing power over to the synthesis engine at the expense of producing more jerky animations. Now supposing you want to run a performance at maximum efficiency, without the overhead of the graphics window. When executing a script for the first time you can simply hit the right cursor key to set the synthesis engine in motion, and then mimimise the graphics window. This means that all the computational resources available will be put into the synthesis itself, until the graphics window is restored. \section{The output of the `tao' command} Whenever a \tao\ script is executed a \verb|.exe| file is generated as a by-product. If you want to re-run the script at any point, instead of typing: \begin{verbatim} tao new.tao \end{verbatim} you can simply type: \begin{verbatim} ./new.exe [-g] \end{verbatim} The \verb|-g| option turns the visualisation window on. If you omit this option then \tao\ proceeds with the synthesis without opening the visualisation window. This is the most efficient way to execute a script. \section{Moving the image in the visualisation window} The image displayed in the instrument visualisation window can be rotated, translated and zoomed using the mouse. Try holding the three mouse buttons down one at a time and moving the mouse to get a better idea of how to manipulate the image. For more details on keyboard and mouse bindings refer back to section \ref{section:key_and_mouse_bindings}. \section{Quitting the synthesis before the performance finishes} If you want to quit the synthesis before the performance completes either type [Ctrl-C] in the shell window you launched \tao\ from or press the [Esc] key whilst the instrument visualisation window is the active window. \section{Post-processing the output files} \label{section:output_files} \tao's output files are written in raw-floating point format. This means that they are not immediately playable, but require a further post-processing step to convert them into a more usable format. This is achieved with the \verb|taosf| command. The general syntax of this command is: \begin{verbatim} taosf \end{verbatim} Where \verb|output_filename| is the name of the output file minus the \verb|.dat| extension. This reads the floating point sample data stored in the output file, normalises it to fit the maximum sample range available, and adds an appropriate WAV header to the file describing the number of channels and sample data format. The reason for \tao's output files being written in floating point format is that it is difficult, if not impossible, to know in advance the amplitudes of the waves in the instruments, especially in cases where some sort of feedback is present in the system. It is therefore easier to write the output samples in a format which presents no danger of overflows (as often happens with CSound) and then normalise these samples once the performance is finished. tao-1.0-beta-10May2006/doc/UserManual/installation.tex0000755000372200037200000004503307103114250017231 00000000000000\chapter{Building and Installing \tao} \label{section:installation} \tao\ was initially developed on SGI Irix 5.3 but was ported in 1998 to Red Hat Linux 5.0. Since then it has been developed primarily on Red Hat 6.0. It has not been tested with other \index{Unix}Unix systems but since it only uses widely available Unix tools and platform independent libraries it is highly probable that it would work just as well on other systems. \section{What else do you need to have installed?} \label{section:whatdoyouneed} \tao\ requires a handful of other programs and libraries to be installed before it will work properly. The main packages which you absolutely need are listed first in this section. Towards the end of the section more details are given of tools which are only required if you want to build the documentation from the sources. The essential packages to have installed are \begin{itemize} \item The GNU C++ compiler; \item \Prog{OpenGL} (or \Prog{Mesa}) libraries and header files; \item GL Utility Toolkit (\Prog{GLUT}) libraries and headers; \item The \Prog{lex} and \Prog{yacc} compiler tools (or \Prog{flex} and \Prog{bison} if you are using GNU versions). \item Michael Pruett's port of the SGI audiofile library. \end{itemize} The GLUT libraries and headers come packaged with Mesa in the most recent versions so you don't have to search for them separately if you choose to use Mesa as your OpenGL replacement, but otherwise you may have to download and install them separately. Similarly the audiofile libraries and headers should be available on SGI machines, and Red Hat 6.0 comes as standard with Michael Pruetts implementation of this API (although one of the header files had a syntax error which I have temporarily fixed by including the corrected headers with this distribution). But if you can't find any \Lib{libaudiofile.*} files on your system then you need to download this package too. Source packages for the above are available at the following URLs: \begin{itemize} \item\xlink{http://www.mesa3d.org}{http://www.mesa3d.org} \item\xlink{http://reality.sgi.com/opengl/glut3}{http://reality.sgi.com/opengl/glut3} \item\xlink{http://www.68k.org/~michael/audiofile/}{http://www.68k.org/~michael/audiofile/} \end{itemize} Follow the installation instructions provided with each package. In practice this should be quite a simple process. NOTE: One thing to bear in mind is that if you choose instead to download and install RPM packages for the above you must install the associated development packages also. For example the audiofile RPMs installed on my system include the following: \begin{itemize} \item\Rpm{audiofile-0.1.6-5} \item\Rpm{audiofile-devel-0.1.6-5} \end{itemize} If you don't have the latter \emph{development} package then none of the header files for the library will be installed, and in addition some essential symbolic links will be missing in the library directory. For Mesa and GLUT the RPMs you need are: \begin{itemize} \item\Rpm{Mesa-3.0.*} \item\Rpm{Mesa-devel-3.0.*} \item\Rpm{Mesa-glut-3.0.*} \item\Rpm{Mesa-glut-devel-3.0.*} \end{itemize} Later versions should work just as well but if you have any problems please let me know so that I can try to sort them out. \section{Configuring, making and installing \tao} As with most GNU-style software there are three easy steps to installing \tao\ assuming everything goes to plan. First change to the directory where you have unpacked the distribution and type the following commands one by one, waiting for any intervening output from each command to finish before typing the next. \begin{verbatim} ./configure make make install \end{verbatim} The default path for installation of the binaries, library files and shell scripts is \Path{/usr/local} so you will need root access in order to use the default. If you do not have root access then change the above to: \begin{verbatim} ./configure --prefix= \end{verbatim} where \verb|| is the full path to wherever you want to install Tao. The configure script checks to see if you have the necessary programs headers and libraries installed. If you do not the configuration will abort with a message telling you what is missing. \subsection{Troubleshooting the configuration process} If the configure script fails it should give you some feedback about what it can't find on your system. One of the most common problems is not being able to find library files. Two common things to check for are: \begin{enumerate} \item Check the value of the \EnvVar{LD\_LIBRARY\_PATH} environment variable. This is used to tell your system where to look for libraries which are not installed in \Path{/usr/lib}. Quite often packages which you install yourself will put library files in \Path{/usr/local/lib} by default. If \EnvVar{LD\_LIBRARY\_PATH} doesn't point to this directory (or wherever else the library files are installed) then programs which depend on these libraries at run time will not be able to find them. To find out the value type: \begin{verbatim} echo $LD_LIBRARY_PATH \end{verbatim} If the value is empty or doesn't contain \Path{/usr/local/lib} or any of the paths where your libraries are located in its colon separated list of paths then you must amend it so that it does. To do this first find out which shell you use by typing: \begin{verbatim} echo $SHELL \end{verbatim} If you're using the \Prog{bash} shell see section \ref{section:bash_shell} below for details of how to amend the value. If you're using the \Prog{tcsh} shell see section \ref{section:tcsh_shell}. \item If you install Mesa, GLUT or audiofile via RPM binary distributions check that you have the appropriate \emph{development} packages installed also. These include: \begin{itemize} \item\Rpm{audiofile-devel-0.1.6-*} \item\Rpm{Mesa-devel-3.0.*} \item\Rpm{Mesa-glut-devel-3.0.*} \end{itemize} These packages provide header files and symbolic links to the libraries (e.g. \Lib{libaudiofile.so} linked to \Lib{libaudiofile.so.0.0}). Without these packages the libraries themselves may be installed but you still won't be able to compile and link programs with them. \end{enumerate} If, after reading this section you are still baffled then take a look at the next section too, since there is a further tool you can use to help diagnose problems. \subsection{If you are still stuck with configuration problems} \label{section:stillstuck} After receiving a emails from some \tao\ users who had run into problems with the configure script I decided to write a shell script as and aid to testing for installed libraries, their locations, and whether or not the executables dependent on those libraries would be able to find them. This shell script is located in the top level directory of the distribution and is called \Prog{diagnose-lib}. Typing \verb|diagnose-lib| without any arguments prints out the following usage message: \begin{verbatim} Usage: diagnose-lib Diagnose problems in finding shared libraries during configuration of Tao can be one of the following: 'gl', 'GL', 'glu', 'GLU', 'glut' or 'audiofile'. \end{verbatim} So, for example, if the configure script claims that you don't have any OpenGL libraries installed but you are convinced that you do, type: \begin{verbatim} ./diagnose-lib gl \end{verbatim} to check for the GL library or \begin{verbatim} ./diagnose-lib glu \end{verbatim} for the GLU library. The \verb|diagnose-lib| script will respond with information about whether it can find a library of the right name, where that library is installed and whether the executables which depend on that library will be able to find it. It does so by searching obvious locations such as \verb|/usr/lib|, \verb|/usr/local/lib| first and then searches the directory tree rooted at your home directory. If it fails to find the library it will abort and let you know. If on the other hand it does find a suitable candidate it then checks to see whether either the file \Filename{/etc/ld.so.conf} or the environment variable \EnvVar{LD\_LIBRARY\_PATH} contain the appropriate path to find this file. These are the two principal mechanisms by which your system locates \emph{shared objects} or \emph{dynamic link libraries} at run time. If neither contain the path to this file a suitable message is printed out and suggestions for solving the problem are given. If you find that you are still having problems after following any advice given by the \verb|diagnose-lib| script then please feel free to email me at \xlink{m.pearson@ukonline.co.uk}{mailto:m.pearson@ukonline.co.uk}. I will try to help out where I can. \subsection{Continuing with the build process} Assuming the configuration part worked you can continue with the build process, i.e. \verb|make| and \verb|make install|. After this you should have the following files installed (assuming that \Path{prefix=/usr/local}): \begin{verbatim} /usr/local/ lib/ libtao.so* libtao.a bin/ tao tao-config taosf taoparse tao2wav \end{verbatim} The install process leaves \tao's header files where they are but provides a shell script \Prog{tao-config} which can be used to find out where both these headers and the various libraries are installed. This is particularly useful if you want to write your own C++ programs and link them against the \tao\ library. It is used in the following way: \begin{verbatim} tao-config --prefix => location for installed files tao-config --cflags => command line flags for the compiler to find Tao's header files tao-config --libs => command line flags for the compiler to find Tao's libraries \end{verbatim} The next step is important. In order for your system to locate the binary executables, shell scripts and libraries you have to set two environment variables: \EnvVar{PATH} and \EnvVar{LD\_LIBRARY\_PATH}. This process is described step by step in the following sections. The first thing you need to do though is find out which UNIX shell you use. To do this type: \begin{verbatim} echo $SHELL \end{verbatim} \subsubsection{Setting PATH and LD\_LIBRARY\_PATH for the bash shell} \label{section:bash_shell} Type the following to see if \Path{/usr/local/bin} is already in your path: \begin{verbatim} echo $PATH \end{verbatim} If not then open the \Filename{.bash\_profile} file in your home directory and add the following lines: \begin{verbatim} PATH=$PATH:/usr/local/bin export PATH \end{verbatim} Then type the following to see if \Path{/usr/local/lib} is in your library loading path: \begin{verbatim} echo $LD_LIBRARY_PATH \end{verbatim} If not then add the following lines to the \Filename{.bash\_profile} file in your home directory: \begin{verbatim} LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib export LD_LIBRARY_PATH \end{verbatim} \subsubsection{Setting PATH and LD\_LIBRARY\_PATH for the tcsh shell} \label{section:tcsh_shell} Type the following to see if \Path{/usr/local/bin} is in your path: \begin{verbatim} echo $PATH \end{verbatim} If not then add the following line to the \Filename{.tcshrc} file in your home directory: \begin{verbatim} setenv PATH $PATH:/usr/local/bin \end{verbatim} Then type the following to see if \Path{/usr/local/lib} is in your library loading path: \begin{verbatim} echo $LD_LIBRARY_PATH \end{verbatim} If not then add the following line to the \Filename{.tcshrc} file in your home directory: \begin{verbatim} setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:/usr/local/lib \end{verbatim} \section{What the distribution contains} This distribution has the following directory structure: \begin{verbatim} libtao/ tao2wav/ tao2aiff/ taoparse/ include/ user-scripts/ examples/ doc/ UserManual/ html/ ClassReference/ latex/ html/ Dependencies/ html/ \end{verbatim} These directories contain the following: \begin{description} \item[libtao/] -- source code for the C++ library which \tao\ is built upon. \item[tao2wav/] -- source code for the program which converts \tao's raw floating point output files in \verb|.wav|\index{WAV output files} format ready for playback. \item[taoparse/] -- lex and yacc source code for \tao's synthesis language parser. \item[include/] -- header files for C++ classes. \item[user-scripts/] -- a set of user shell scripts including the following: \begin{description} \item[tao] -- shell script for compiling and executing a \tao\ script. \item[tao-config] -- shell script which is useful when compiling and linking C++ programs with the \tao\ library \Lib{libtao}. \item[taosf] -- shell script for converting \tao's output files to WAV format. \end{description} \item[examples/] -- a set of examples illustrating the main elements of \tao's synthesis language. \item[doc/] -- documentation of various kinds. This includes the following: \begin{description} \item[UserManual/] -- \Prog{Hyperlatex} sources for this manual which can be used to produce DVI and PostScript versions using \LaTeX\ and \Prog{dvips}, and the HTML version using \Prog{hyperlatex}. The HTML formatted version comes ready made with this distribution so you don't need \Prog{hyperlatex}, although the \emph{Dependencies} document describes where to get it. \item[ClassReference/] -- \LaTeX\ and HTML documentation for the C++ library API. Both versions of this document are produced automatically from the C++ sources using a third party program called \Prog{Doxygen}. See the \emph{Dependencies} document for details of where to get \Prog{Doxygen}. [Actually I haven't got around to this yet as I am concentrating on making the distribution as robust as possible and finishing the user manual, but it will happen eventually]. \item[Dependencies/] -- \Prog{hyperlatex} sources for the document describing the external programs upon which \tao\ depends. Once again these sources can be used to produce HTML, DVI and PostScript formatted versions and the HTML version comes ready built with the distribution. \end{description} \end{description} The installation step described in the previous section installs the following files on your system (assuming \Path{prefix=/usr/local}): \begin{verbatim} /usr/local/bin tao taosf tao2wav taoparse /usr/local/lib libtao.so.* libtao.a \end{verbatim} \section{Testing \tao} To test that everything is working once the installation is complete open a new shell window. Change to the top level directory in the \tao\ distribution copy the script \Path{examples/test.tao} to your home directory. This test script contains the following text although you don't need to understand how it works for the moment. \begin{verbatim} Audio rate: 44100; Circle c(800 Hz, 20 secs); String strings[4]= { (800 Hz, 20 secs), (810 Hz, 20 secs), (820 Hz, 20 secs), (830 Hz, 20 secs) }; Rectangle r(800 Hz, 900 Hz, 20 secs); Triangle t(800 Hz, 900 Hz, 20 secs); Connector conn1, conn2, conn3, conn4; Counter s; Init: For s = 0 to 3: strings[s].lockEnds(); ... c.lockPerimeter(); r.lockCorners(); t.lockLeft().lockRight(); strings[0](0.1) -- conn1 -- strings[1](0.1); strings[1](0.9) -- conn2 -- strings[2](0.9); strings[2](0.1) -- conn3 -- strings[3](0.1); r(0.6,0.2) -- conn4 -- 0.0; r.placeRightOf(c,20); t.placeAbove(r); ... Score 20 secs: At start for 0.1 msecs: strings[0](0.1).applyForce(1.0); strings[1](0.1).applyForce(1.0); strings[2](0.1).applyForce(1.0); strings[3](0.1).applyForce(1.0); c(0.1,0.5).applyForce(10.0); r(0.7,0.8).applyForce(10.0); t(0.8,0.6).applyForce(10.0); ... ... \end{verbatim} Change directory in the shell window to your home directory and type: \begin{verbatim} tao test \end{verbatim} If everything is working OK \tao\ should respond firstly by printing the following messages in the shell window: \begin{verbatim} ======================================== | Tao (c) 1996-99 Mark Pearson | | Sound Synthesis with Physical Models | ======================================== Processing test.tao Making test.exe Executing test.exe Sample rate=44100 KHz Score duration=1 seconds \end{verbatim} It should then open a window like the one shown in figure \ref{fig:instrvis}. This is \tao's \emph{instrument visualisation window}\index{instrument!visualisation window}, which presents a 3-D animated representation of the instruments described in the script \Filename{test.tao}. In the current implementation this window is meant for visualisation only, it is not possible to edit the instruments graphically. \begin{figure}[htb] \begin{Label}{fig:instrvis} \begin{center} \Image{instrvis}{height=7cm}{gif} \end{center} \caption{\tao's instrument visualisation window} \end{Label} \end{figure} This is a good opportunity to try some of the key and mouse bindings which affect the behaviour of the instrument visualisation window. These are listed below but there is one thing you have to do first to set the synthesis engine in motion. \textbf{IMPORTANT:} When the visualisation window opens initially the instrument animation is paused. This gives you time to move/resize/rotate the image to get the view you want before setting everything in motion. So the first thing you need to do is press the \textbf{right-arrow} key. After doing this you should see the instruments spring to life, showing the propagating waves. You can now try out some of the key and mouse bindings. \subsection*{Key bindings} \label{section:key_and_mouse_bindings} \index{key bindings} \begin{description} \item[Down-arrow] Reduce the visible amplitude of the vibrations. \item[Up-arrow] Increase the visible amplitude of the vibrations. \item[Left-arrow] Decrease the number of ticks between displayed frames i.e. make the animation slower but smoother. \item[Right-arrow] Increase the number of ticks between displayed frames i.e. make the animation faster but more jerky. \item[Esc] Exit and close the graphics window. \end{description} \subsection*{Mouse bindings} \index{mouse bindings} In addition there are a number of mouse functions which work when the appropriate button is held down and the mouse is moved: \begin{description} \item[Left-mouse] Translate the image. \item[Middle-mouse] Zoom in/out. \item[Right-mouse] Rotate the image. \end{description} tao-1.0-beta-10May2006/doc/UserManual/introduction.tex0000644000372200037200000001227210430370107017247 00000000000000\chapter{Introduction} Welcome to the \tao\ user manual. This manual is for version 1.0-beta-10May2006 built on Wed May 10 15:26:37 BST 2006. \tao\ is a software package for sound synthesis using physical modelling techniques. It is written in C++ and provides a kind of virtual material consisting of masses and springs, which can be used to construct a wide variety of virtual musical instruments. New instruments are described using a text-based synthesis language (contained in what is referred to as a \tao\ \index{script} script). When a script is invoked \tao\ carries out the synthesis described and automatically produces 3-D animated visualisations of the instruments. The animations show the actual acoustic waves propagating through the instruments and play a central role in \tao's user interface. In particular they make it much easier to think of the instruments as tangible physical objects rather than abstract synthesis algorithms. \tao\ will eventually come with full documentation for the C++ class library API (application programming interface) so that it can also be used by those who wish to write their own C++ applications incorporating \tao's capabilities. This is not complete at the present time. \section{Where to find \tao} \tao\ is available from the download section of \TaoWebSite This user manual is also available for separate download either as a tar'd gzip'd archive of HTML files or a gzip'd postscript file. \section{Who was it designed for?} \tao\ was conceived as a compositional tool for electroacoustic and computer music. Therefore more emphasis has been placed on its ability to produce a wide range of interesting and complex sounds than on catering for traditional music based on scales, rhythms, harmony etc. From a personal perspective I wanted to design a synthesis program which would allow me to deal with tangible physical instruments rather than abstract synthesis algorithms. I wanted to be able to construct virtual musical instruments with very complex behaviours and experiment with them in an intuitive physical manner. \section{How \tao\ is structured} \tao\ consists of a library of C++ classes for building synthesis scenarios. The classes provide the means for creating primitive acoustic building blocks, coupling these building blocks together into more complex instruments, applying external excitations, and generating sound output from the instruments. \tao's synthesis language provides the same functionality as the C++ API but is easier to use. In addition to providing a language for creating virtual instruments it also provides an algorithmic score language for playing them. From the user's perspective the synthesis language appears to be interpreted rather than compiled since a script may be invoked with a simple one-line command. In reality though this process involves translating the \tao\ script into C++ first, linking it with the C++ \tao\ library \Filename{libtao.so} and then invoking the executable produced. You shouldn't have to worry about the details of this process when using the synthesis language interface though. \section{What this manual contains} This user manual is divided into eight chapters as follows: \begin{description} \item[1. Introduction] This introductory chapter. \item[2. Building and Installing \tao] Instructions on where to obtain the \tao\ distribution and how to build and install it. \item[3. Conceptual Overview] Introduces the main concepts which should be understood before attempting to use \tao. \item[4. Getting Started] Skips the details and goes straight to a practical example session using \tao. \item[5. Tao's User Interface] Self-explanatory. \item[5. \tao's Synthesis Language in Detail] Gives a detailed description of the synthesis language provided. \item[6. Object Method Reference] A detailed reference for all of \tao's classes which are available within the synthesis language. \item[7. Tutorial] Gives lots of example scripts describing what they do and how. \item[8. Closing Comments] General comments about the current state of \tao\ and areas for future development. \end{description} \section{Typographic conventions used} This manual adopts a number of typographic conventions \index{typographic conventions} which are described below. The \texttt{monospace} font indicates shell window output, filenames and names of environment variables; keywords, functions and operators in \tao's synthesis language; and finally verbatim examples which should be typed exactly as shown. The \textbf{\texttt{monospace bold}} font is used in the index to highlight entries for keywords, functions and operators in \tao's synthesis language. The \emph{italic} font indicates important terminology being introduced for the first time. In addition to the above conventions sometimes it is necessary to indicate where the user needs to supply some values in a \tao\ script. For example in the following script fragment \verb|| and \verb|| would need to be replaced with appropriate values by the user: \begin{verbatim} String myString(, ); \end{verbatim} Finally \tao\ refers to the entire software package whereas \verb|tao| refers to the name of the shell command used for executing a \tao\ script. tao-1.0-beta-10May2006/doc/UserManual/script_language.tex0000755000372200037200000013435107101672372017715 00000000000000\chapter{\tao's Synthesis Language in Detail} \tao's main user interface elements are its \Term{synthesis language} and \emph{instrument visualisation window}\hierindex{instrument!visualisation window}. The synthesis language provides the means for describing new instruments and `playing' them and the instrument visualisation window provides graphical animations of the instruments showing their behaviour as the acoustic waves propagate through them. At present there is no GUI (Graphical User Interface) for constructing instruments but this feature is planned for a future release. This section focusses on the synthesis language in some detail. It begins by describing the main conceptual parts of a \tao\ script and then goes on to cover each individual element of the language in more detail. \section{Overview of a Script} A \tao\ script, although contained within one text file, is conceptually split into three main sections: the \Term{declarations} section; the \Term{init} section; and the \Term{score} section. The \hierindex{script!sections} \emph{declarations} section contains instructions for creating instruments, devices, pitches, arrays, parameters and access points etc. The \emph{init} section contains instructions for initialising the instruments, devices, parameters and other objects. It may optionally contain instructions for applying devices to instruments, coupling instruments together, and specifying the initial locations of any access points. Finally the \emph{score} section contains instructions for playing the instruments and generating output audio files during the \Term{performance}. The term performance is used here to refer to the run-time execution of the synthesis scenario described in the script. The score provides a means for the user to apply time-varying excitations to the instruments and control any instrument or device attributes via the use of parameters. The score consists of nested \Term{control structures} which allow events to be scheduled throughout the performance. These control structures contain either further nested control structures or \Term{statements}. Statements are the mechanism by which parameters are assigned values, mathematical expressions are evaluated, instrument and device attributes are controlled etc. For a more detailed description of the statement types available see section \ref{section:statements}. Statements are also used to specify the sound samples which are to be written out to an Output device. \section{The Declarations Section} This section of the script may contain Instrument, Device, Parameter, Access Point and Pitch declarations, each of which is described in the following sections. However the very first declaration which must appear in a script determines the audio sample rate of the output files. This declaration takes the form: \begin{verbatim} Audio rate: 44100; \end{verbatim} In the present release the sample rate must be set to 44.1kHz as above. \subsection{Instrument Declarations} \label{section:instrument_declarations} \hierindex{declaration!instrument} \tao\ provides a set of classes for creating pieces of the material described in section \ref{section:cellular_material}. Each class deals with a creating a piece of material of a particular geometrical shape, so for example the user can create strings, circular sheets, rectangular sheets and elliptical sheets. The way in which \tao's cellular material is actually implementated provides for future support of irregularly shaped components but in the present version the user is limited to these geometrical primitives. In practice though this is not a serious limitation since there are many other techniques available for designing interesting instruments. These include damping and locking parts of an instrument and constructing \Term{compound instruments} by coupling several pieces of material together using Connector devices. All of these techniques provide ample room for experimentation. In order to create a \emph{primitive} instrument \hierindex{instrument!creating} several pieces of information are required. These include the instrument type, the name by which it will be referred to in the script, its $x$ and $y$ frequencies, and its decay time. The general form of an instrument declaration is illustrated by the following string declaration: \begin{verbatim} String string(, ); \end{verbatim} where \verb|String| is the name of the instrument class; \verb|string| is the name of the particular instrument being created; \verb|| defines (indirectly) how long the string will be (the tension in \tao's material cannot be altered so the length of a string is related to its pitch or frequency alone and vice versa); and \verb|| determines the amplitude decay time of the instrument. In the next example the placeholders \verb|| and \verb|| are replaced with typical values which might occur in a script: \begin{verbatim} String string(C#5+1/2, 4.5 secs); \end{verbatim} In this example the length of the string is set such that its pitch is C sharp plus a quarter-tone (1/2 a semitone) in octave 5, and its decay time is four and a half seconds. The \verb|| argument can be specified in a number of different formats, some of which are directly analogous to those provided in Csound. The other formats are introduced throughout this section by way of example. The format used in the example above is referred to as \Term{note name format} format\hierindex{pitch formats!note name}. The \verb|| argument consists of a numerical constant followed by the units of time, i.e. \verb|sec|, \verb|secs|, \verb|min|, \verb|mins| or \verb|msecs|, representing seconds, minutes and milliseconds respectively. A second practical example is given below, this time creating a rectangular sheet called \verb|rect|: \begin{verbatim} Rectangle rect(200 Hz, 500 Hz, 60 secs); \end{verbatim} In this example two pitch arguments are specified, and both are given in \Term{frequency format}\hierindex{pitch formats!frequency}. The first determines the size of the instrument in the $x$ direction and the second, the size in the $y$ direction. It may seem slightly unintuitive at first to be specifying the size of a rectangular sheet in units of Hertz rather than physical dimensions such as metres or millimetres, but this practice is adopted for a number of good reasons: \begin{enumerate} \item It makes creating precisely pitched instruments a simpler matter; \item \tao's material is not based upon any real-world material so it would be meaningless to talk about a sheet of cellular material 5m by 3.5m; \item The instrument is described in units which are of more perceptual relevance to a musician than physical units of size (open to debate). \end{enumerate} Another advantage of specifying dimensions by pitch or frequency is that it becomes a simple matter to construct an instrument which has an array of similar components but with different pitches for each. For example the following code fragment creates a set of rectangular components with uniform $y$ dimension but pitches tuned to fractions of an octave for the $x$ dimension. This kind of instrument might be the starting point for some sort of pitched percussion instrument for example: \begin{verbatim} Rectangle rect1(8.0 oct, 500 Hz, 60 secs); Rectangle rect2(8.2 oct, 500 Hz, 60 secs); Rectangle rect3(8.4 oct, 500 Hz, 60 secs); Rectangle rect4(8.6 oct, 500 Hz, 60 secs); Rectangle rect5(8.8 oct, 500 Hz, 60 secs); Rectangle rect6(9.0 oct, 500 Hz, 60 secs); \end{verbatim} This example shows yet another form of the pitch argument, i.e. \Term{octave/fraction format}\hierindex{pitch formats!octave/fraction} or \Kwd{oct} format for short. In this format the integer part specifies the octave and the fractional part after the decimal point specifies a fraction of an octave. The previous example opens the way for describing another important technique often used when creating instruments with arrays of similar components. \tao\ provides an \Term{array} facility for grouping together such components and giving them a common name. For example the following script code has much the same effect as the previous example but logically groups the six rectangular components together into an array with a single name \verb|rect_array|: \begin{verbatim} Rectangle rect_array[6]= { (8.0 oct, 500 Hz, 60 secs), (8.2 oct, 500 Hz, 60 secs), (8.4 oct, 500 Hz, 60 secs), (8.6 oct, 500 Hz, 60 secs), (8.8 oct, 500 Hz, 60 secs), (9.0 oct, 500 Hz, 60 secs) }; \end{verbatim} The individual components can be accessed using syntax which will be very familiar to C and C++ programmers: \begin{verbatim} rect_array[0], rect_array[1] .. rect_array[5] \end{verbatim} The declarations for circular, elliptical and triangular sheets of material follow a similar format to the examples presented in this section, with elliptical and triangular sheets requiring two pitch values and circular sheets requiring only one (determining the diameter). Examples are given below: \begin{verbatim} Circle circle(5.03 pch, 20 secs) Ellipse ellipse(6.00 pch, 50 Hz, 1 min + 20 secs) Triangle triangle(100 Hz, 6.5 oct, 600 msecs) \end{verbatim} These declarations introduce the final pitch notation, \Term{octave/semitone format}\hierindex{pitch formats!octave/semitone} or \Kwd{pch} format for short. In this format the fractional part after the decimal point is interpreted as semitones. For example \verb|5.03 pch| means the third semitone above C in octave 5. Note that fractions of semitones are also possible. For example \verb|5.035 pch| means 3.5 semitones above C in octave 5. Note also that the different pitch formats can be used side by side in an instrument declaration requiring more than one pitch. \subsection{Device Declarations} \hierindex{declarations!device}\index{device declaration} Device declarations are similar to other declarations in that they consist of a type name followed by a comma-separated list of either individual device names or device array names. For example, all the following are valid device declarations: \begin{verbatim} Bow bow; Hammer hammer; Connector connector; Stop stop; Output output(1); Bow bow1, bow2, bowArray[10]; Hammer hammerArray1[5], hammerArray2[5]; Output out1(stereo), out2(mono), outArray(stereo)[10]; \end{verbatim} Note that the syntax used for Output device declarations differs from that used for the other devices. This is because an Output declaration must specify the number of channels for the single output or array of outputs being created. Also note the use of keywords \verb|mono| and \verb|stereo| as alternatives to putting the numerical constants 1 and 2 respectively. \subsection{Access Point Declarations} \hierindex{declaration!access point}\index{access point declaration} Some examples of access point declarations are given below: \begin{verbatim} AccessPoint a1=instr1(0.1,0.5), a2=instr2(centre); AccessPoint a3=instr3(left,bottom), a4; \end{verbatim} If an access point is to be given an initial value then the familiar access point notation of the instrument name followed by one or two coordinates in parentheses is used. Note that an access point does not need to be initialised, although if you try to apply a device via an access point before it has been initialised nothing will happen. \subsection{Pitch Declarations} \label{section:pitch_declarations} We have already come across the use of \Term{pitch literals} in section \ref{section:instrument_declarations} but it is also possible to declare pitches as seperate objects in a script. Pitch declarations take the following form: \begin{verbatim} Pitch p1=C#7+1/2, p2=8.3 oct, p3=8.01 pch, p4=50 Hz; \end{verbatim} This example illustrates the four pitch formats supported, i.e. \emph{note name}, \emph{octave/fraction}, \emph{octave/semitone} and \emph{frequency}. \subsection{Parameter Declarations} \label{section:parameter_declarations} The term \Term{parameter} is a blanket term which is applied to both floating point and integer variables. There are four keywords available for denoting different types of parameters: \Type{Param}, \Type{Integer}, \Type{Counter} and \Type{Flag}. The latter three all lead to the creation of integer variables and the only reason for having three different keywords for the same parameter type is so that the semantic function of a particular integer variable is made more clear in a script. The following are examples of valid parameter declarations: \begin{verbatim} Param p1, p2, p3=10.0; Integer i1=10, i2=30; Counter count=0; Flag flag1=false, flag2=true; \end{verbatim} As with instruments and devices it is also possible to create (one-dimensional) arrays of parameters in the following ways: \begin{verbatim} Param array1[10], array2[20], array3[]={0.1,0.2,0.3,0.4,0.5}; Integer intArray[5]={1,3,5,7,9}; Flag flagArray[]={true, false, true, true, false}; \end{verbatim} Note that in the case of an initialised array (one with initial values in curly brackets) giving the size of the array is optional. However if the size is specified then it must match up with the number of intial values given. \section{The Init Section} \label{section:init_section} The declaration section of the script allows the user to create the basic building blocks for the synthesis but there are often many other tasks which must be performed just prior to the `performance' described in the score. These include: \begin{itemize} \item locking parts of the instruments; \item damping parts of the instruments; \item initialising various parameter values; \item initialising the devices; \item specifying the points at which the various devices will interact with the instruments. \end{itemize} This is the purpose of the Init section of a \tao\ script. A typical Init section is shown below: \begin{verbatim} Init: string1.lockEnds(); rectangle1.lockCorners(); param1=0; paramArray[0]=10; flag1=true; ... \end{verbatim} \section{The Score Section} \label{section:score_section} \tao's score language provides the means for controlling the instruments and devices declared and initialised in the previous two sections of the script. Unlike the score language used by Csound \tao's script language is not a set of time-stamped numerical data to be fed into the inputs of the instruments as the performance progresses. Instead it is an algorithmic language which allows user specified pieces of code to be executed under certain conditions or at specified times. The score language is hierarchical in nature and consists of nested \Term{control structures} and \Term{statements}. The available control structures are described in the next section. \section{Control Structures} \label{section:control_structures} \tao's score language provide a set of constructs for scheduling events in a performance. These are referred to as \Term{control structures} and include the following: \begin{verbatim} At : ... At for : ... From to : ... Before : ... After : ... ControlRate : ... Every : ... \end{verbatim} In each case \verb|| is the code which is to be executed at the scheduled time. In the case of \CtrlIndex{At} the code is executed once at the given time \verb||. For \CtrlIndex{At..for} and \CtrlIndex{From..to} the \verb|| is executed on every tick in the interval defined by \verb|| and \verb||. \CtrlIndex{Before} and \CtrlIndex{After} also define time intervals during which the \verb|| is executed on every tick but the behaviour is slightly more context dependent as we will see later in this section. For \CtrlIndex{ControlRate} the code is executed on every \verb||'th tick and finally, for \CtrlIndex{Every} the code is executed repeatedly once every \verb|| seconds (other units can be specified). In each of the control structures introduced above there is a \Term{head} part which determines when the \Term{body} will be executed. For most of the control structures the head consists of some sort of test to see what the value of the system variable \verb|Time| is compared to the given values. This variable keeps track of the amount of sound synthesised so far -- i.e. \Term{performance-time} -- not real-time. If the particular condition specified is met then the body of the control structure is executed. What follows is a more detailed look at the syntax and behaviour of the various control structures. \subsection{At} This control structure takes the following form: \begin{verbatim} At : ... \end{verbatim} The \verb|| is executed if the value of \verb|Time| is equal to the value \verb||. \subsection{At..for} This control structure repeatedly executes the instructions contained in the body on every tick from time \verb|| to \verb|+| inclusively: \begin{verbatim} At for : ... \end{verbatim} \subsection{From..to} This control structure repeatedly executes the body on every tick from \verb|| to \verb|| inclusively: \begin{verbatim} From for : ... \end{verbatim} \subsection{Every} This control structure repeatedly executes the body every \verb|| seconds starting at 0.0 seconds: \begin{verbatim} Every : ... \end{verbatim} \subsection{ControlRate} This control structure repeatedly executes the body once every \verb|| ticks starting at tick zero: \begin{verbatim} ControlRate : ... \end{verbatim} \section{Conditional and looping control structures} Looping and conditional control structures are also provided in the form of \CtrlIndex{For..to}, \CtrlIndex{If}, \CtrlIndex{If..Else}, \CtrlIndex{If..ElseIf..Else}. These are described in more detail in the next section. \subsection{If, If..Else, If..ElseIf..Else} Unlike the control structures introduced above, the next three are not concerned with the \Var{Time} variable, but allow the user to specify conditional execution by providing Boolean expressions. They do not require much explanation really so all that is included here is the syntax: \begin{verbatim} If : ... \end{verbatim} \begin{verbatim} If ... Else ... \end{verbatim} \begin{verbatim} If ... ElseIf ... ElseIf ... . . Else ... \end{verbatim} Note that the block terminating symbol \verb|...| must appear after the end of every \verb|| section. Also note that conditional expressions do not need to be surrounded by brackets as they do in C and C++. \subsection{For Loops} The \verb|For| control structure provides a simple mechanism for iteration with integer variables and takes the form: \begin{verbatim} For = to : ... \end{verbatim} The \verb|| must be an integer parameter, i.e. declared as one of the following: \begin{verbatim} Integer ; Counter ; Flag ; \end{verbatim} There is no difference between these three integer parameter types incidentally, they are only included to make it clear to a human reader of a \tao\ script whether a particular integer variable is a counter a Boolean flag etc. It therefore makes little stylistic sense to use a \verb|Flag| as the loop variable in a \Ctrl{For} statement or a \Type{Counter} in an \Ctrl{If} statement. \section{Statements} \label{section:statements} Whilst control structures allow various events to be scheduled throughout a performance \Term{statements} provide the actual means by which individual events are described. Examples events might include striking an instrument, assigning a parameter a new value, changing a device's attributes etc. The individual statement types supported are descibed in the following sections. \subsection{Assignment Statement} \label{section:assignment_statement} Assignment statements are used to assign values to parameters much as in any standard programming language such as C or C++. The operators used are inherited from these languages (\verb|=, +=, -=, *=, /=|). An assignment statement takes the following general form: \begin{verbatim} = += -= *= /= \end{verbatim} The last four assignment operators alter the parameter's current value by adding/subtracting to/from or multiplying/dividing by the value of the \verb|| on the right of the operator and then reassigning the parameter with the result of the calculation. For more about expressions see section \ref{section:expressions}. \subsection{Print Statement} \label{section:print_statement} The \Statement{Print} statement is used to output text and parameter values to the shell window from which \tao\ is invoked. This is useful for getting ongoing feedback about how a score is proceeding. The following script fragment illustrates its use: \begin{verbatim} . . Parameter p1,p2,p3; Init: p1=10; p2=20; p3=30; ... Score 1 secs: At 0 secs: Print "p1=", p1, "p2=", p2, "p3=", p3, newline; ... Every 0.2 secs: Print "Elapsed Time=", Time, newline; ... ... \end{verbatim} In this example we see four different types of item being `printed'. The first is a character string, no surprises there, the second is a user defined parameter, the third is a system variable \verb|Time|, and the fourth is the special item \verb|newline| which causes printing to continue on the next line. \subsection{For Statement} \label{section:for_statement} The For statement provides a rudimentary looping and iteration facility. It is fairly basic as it only supports integer counting from some initial value to some final value in steps of 1. An example is given below: \begin{verbatim} String stringArray[4]= { (50 Hz, 60 secs), (100 Hz, 60 secs), (150 Hz, 60 secs), (200 Hz, 60 secs) }; Counter c; Init: For c=0 to 3: stringArray[c].lockEnds(); ... ... \end{verbatim} \subsection{Label Statement} \label{section:label_statement} The Label statement allows the user to display text captions in the instrument visualisation window. These \Term{labels} can be anchored to points on instruments so that they move as the instrument moves. This is sometimes useful to clarify visually precisely what is going on in the script. Label statements take the following generic form: \begin{verbatim} Label (, , , , , , , ); \end{verbatim} This statement is rather ugly in its present form because of the large number of arguments but it does the job on the few occasions the user really needs to add to the automatic labeling produced by \tao. The example below is a Label statement with real arguments: \begin{verbatim} Label (s[4], 1.0, 0.0, 0.0, "String four", 1.0, 1.0, 1.0); \end{verbatim} \subsection{Method Statement} \label{section:method_statement} There are a number of object methods for each class which return no value but are usually associated with setting the attributes of an object such as an instrument or device. These methods are not listed here since they are covered in detail in section \ref{section:object_method_reference}. Briefly though examples of the kind of things which we might do with object methods include setting the amount of damping for a region of an instrument; setting the height from which a hammer should be dropped; and setting the velocity and downward force for a bow. The example below shows how these tasks would be implemented in practice in a script: \begin{verbatim} Rectangle rect(100 Hz, 200 Hz, 20 secs); Bow bow; Hammer hammer; Init: // Damp the bottom left hand corner of the rectangular // sheet with a value of 0.5 rect.setDamping(left, 0.1, bottom, 0.2, 0.5); // Set the drop height of the hammer hammer.setHeight(10.0).reset(); // Set the initial velocity and downward force of the // bow bow.setVelocity(0.0).setForce(1.5); ... \end{verbatim} \subsection{Connection Statement} \label{section:connection_statement} The connection statement is the means by which the end points of a Connector object are specified in a script. Each end of a Connector object can be assigned either an access point or a numerical value representing a fixed \Term{anchor point}. The following script fragment illustrates the use of the connection statement in its various forms: \begin{verbatim} String string1(100 Hz, 20 secs); String string2(100 Hz, 20 secs); String string3(100 Hz, 20 secs); Connector conn1, conn2, conn3; Init: string1(0.5) -- conn1 -- string2(0.5); string2(0.1) -- conn2 -- 0.0; string2(right) -- conn3 -- string3(left) strength 0.5; ... \end{verbatim} There are several features about the connection statement to note. Firstly it is possible for both ends of a Connector to be assigned access points, for one end to be assigned an access point whilst the other is assigned an anchor point. However it is meaningless for both ends of a Connector to be assigned anchor points since this would have no effect on any instruments and the Connector would thus be rendered useless. The second thing to note is that regardless of whether access or anchor points are used the connection statement has an optional \verb|strength| clause which allows the strength of the spring to be set. If the strength value is specified in the range [0..1] then the model's behaviour is guaranteed to remain stable. However some values higher than 1 may be useful at times but can also make the whole instrument model unstable to the point where it induces exponentially growing noisy vibrations. Unfortunately this is an limitation inherent in the discrete model used by \tao. \subsection{Output Statement} \label{section:output_statement} The \Term{output statement} is used to feed floating point samples to an Output device. The samples can be generated by arbitrary mathematical expressions but are usually derived from expressions involving access points. \begin{verbatim} Output out1(stereo), out2(mono); . . Score 10 secs: out1.chL: string1(0.1); out1.chR: string1(0.9); out2.ch1: string1(0.5); ... \end{verbatim} As the previous example shows, the output statement consists of the name of an Output object followed by one of the methods \verb|ch1|, \verb|ch2|, \verb|chL|, \verb|chR|. This is then followed by a colon and then the expression representing the floating point value to be written out to the Output's associated file as an audio sample. Note that when an access point expression appeears in an output statement, e.g. \verb|string(0.1)|, it evaluates to a floating point value representing the displacement of the instrument along the $z$ axis at that point. It is as if the expression \verb|string(0.1).getPosition()| had been typed. This short-hand notation makes it easier to read where the output samples are coming from. Of course if you want to use the velocity of the string at that point you could write instead: \begin{verbatim} . . out1.chL: string(0.1).getVelocity(); out1.chR: string(0.9).getVelocity(); \end{verbatim} For a more detailed description of \tao's expression syntax see section \ref{section:expressions}. \subsection{Join Statement} \label{section:join_statement} The \Term{join statement} provides another means for coupling together two components. It only works for rectangular components and does so by lining up to adjacent edges and `stitching' them together with new springs. After having been joined in this way, two rectangular components will behave as a single, continuous piece of material. In figure \ref{fig:joining} two rectabgular components are shown being joined together. Two Join statements are shown underneath the instruments. Either one of the Join statements could be used in a script to lead to the same end result. \begin{figure}[h] \begin{Label}{fig:joining} \begin{center} \Image{joining}{height=8cm}{gif} \end{center} \caption{Joining two rectangular components together with the Join statement} \end{Label} \end{figure} \subsection{Apply Statement} \label{section:apply_statement} The \Term{apply statement} provides the means for the user to specify the access point via which a device will interact with an instrument. It is similar in syntax to the \Term{connection statement} (section \ref{section:connection_statement}) in that it makes use of the \verb|--| operator as shown in the next example: \begin{verbatim} String string(C#5+1/2, 55 secs); Bow bow; Parameter bowPosition=0.5; . . string(bowPosition) -- bow; \end{verbatim} If you wish to disengage the device from the specified access point you use the device method \verb|remove()|. So for example: \begin{verbatim} bow.remove(); \end{verbatim} \section{Describing Musical Events} Having introduced the various elements which comprise \tao's synthesis language we now take a look at how to describe musical \Term{events} using the score language provided. The term \emph{event} needs some clarification before we start though. In \tao\ the term is used to signify \emph{anything} which occurs during a performance, either at a particular instant in time or over some time interval. Events come in all shapes and sizes from low-level events such as setting the value of a parameter, to high-level events such as playing a bowed note on a stringed instrument. Many events, especially the higher level musical events are hierarchical in nature. For example in order to describe an event such as bowing a note on a string the event will be broken down into sub-events such as the following: \begin{itemize} \item Apply the bow to the string; \item Increase the velocity of the bow over some short time interval to create an attack, at the same time as controlling the downward force of the bow; \item Hold the velocity steady for some time interval; \item Decrease the velocity steadily for some time interval; \item Remove the bow from the instrument. \end{itemize} Such high-level events are referred to as \Term{compound events}. All compound events no matter how complex eventually reduce down to low-level events, examples of which are given below: \begin{itemize} \item Evaluating expressions and assigning values to parameters; \item Changing the attributes of an instrument; \item Changing the attributes of a device; \item Applying a device to an instrument or removing it again; \item Coupling instruments together; \item Displaying text output in the shell window to give feedback about how a performance is progressing; \item Specifying output sources; \item Writing audio samples to output files. \end{itemize} The rest of this section takes a closer look at the various techniques which are commonly used to implement compound events. \subsection{Nested control structures and the special variables start and end} The way in which compound events are describedin a score is by nesting control structures representing low-level events within higher level ones. The following (trivial) script illustrates this technique, at the same time as introducing two special variables called \verb|start| and \verb|end|, which play a central role in describing compound events: \begin{verbatim} Audio rate: 44100; Init: ... Score 2 secs: From 0 secs to 1 secs: At start: Print "For interval 0-1 seconds start=", Time, newline; ... At end: Print "For interval 0-1 seconds end=", Time, newline; ... ... From 1 secs to 2 secs: At start: Print "For interval 1-2 seconds start=", Time, newline; ... At end: Print "For interval 1-2 seconds end=", Time, newline; ... ... ... \end{verbatim} When invoked this script produces the following output: \begin{verbatim} Sample rate=44100 Hz Score duration=2 seconds For interval 0-1 seconds start=0 For interval 0-1 seconds end=1 For interval 1-2 seconds start=1 For interval 1-2 seconds end=2 \end{verbatim} The four \Kwd{Print} statements in this example print out the values of the \VarIndex{start} and \VarIndex{end} variables at various points during the performance. Note that the values change depending on where the variables are actually accessed. This is due to the concept of \Term{scope}. Each control structure which defines a time interval during the performance -- i.e. each instance of \Ctrl{At..for}, \Ctrl{From..to}, \Ctrl{Before} or \Ctrl{After} -- has its own scope. Within that scope the values of \Var{start} and \Var{end} are set to refer to the start and end times of that particular time interval. This is useful for defining sub-events in terms of the higher-level event in which they are enclosed. Another example is given below to clarify this point: \begin{verbatim} Audio rate: 44100; Init: ... Score 5 secs: At start: Print "For score, start=", Time, newline; ... At end: Print "For score, end=", Time, newline; ... From 1 secs to 4 secs: At start: Print "For interval 1-4 seconds, start=", Time, newline; ... At end: Print "For interval 1-4 seconds, end=", Time, newline; ... ... ... \end{verbatim} In this example the first pair of \Ctrl{At} structures are enclosed within the scope of the top-level \Ctrl{Score} structure, whilst the second pair of \Ctrl{At} structures are enclosed or nested within the \Ctrl{From..to} structure. As you can see from the output from this script, the values of \Var{start} and \Var{end} are altered accordingly depending on their scope: \begin{verbatim} Sample rate=44100 KHz Score duration=5 seconds For score, start=0 For interval 1-4 seconds, start=1 For interval 1-4 seconds, end=4 For score, end=5 \end{verbatim} Note also that it doesn't matter in which textual order events are given in a score, the only thing which matters is the instant in time, or time interval defined by the values in the head of the control structure. The ability to nest events and define the start and end times of a sub-event in relative rather than absolute terms provides a rudimentary mechanism for describing compound events \footnote{This scheme is far from perfect since there is no \Term{encapsulation} facility as yet. By encapsulation we refer to the ability of most general purpose programming languages to break a problem down into manageable modules (e.g. functions or procedures) which can be named and parameterised. This feature would greatly enhance \tao's ability to deal with complex musical events. See section \ref{section:script_deficiencies} for a more in-depth discussion on this topic.}. \subsection{Streams of Events and Iteration} Often it is necessary to repeat some simple event iteratively in order to form a stream of similar events. One example of this might be repeatedly striking an object at short (random) intervals in order to create a dense granular texture. This section describes a common technique for implementing such streams of events \footnote{Acknowledgements are due to Prof. David Worrall of the Australian Centre for the Arts and Technology for many fruitful discussions on the subject of events and streams. At the time these were aimed at extending David's algorithmic composition software \emph{Streamer}, but the discussions were of much wider interest as events and streams are so fundamental to music.}. In order to describe an iterated event we will use the technique of nested control structures described in the previous section, but in a particular way, which allows an event to reschedule itself once its time is up. The following example script schedules a series of events to occur at one second intervals. Each individual event is trivial in nature, simply printing a message to the shell window showing the time at which it occurs (performance-time, not real-time). \begin{verbatim} Audio rate: 44100; Param eventStart=0.0, eventDur=0.01, interval=1.0; Init: ... Score 10 secs: At eventStart for eventDur: At start: Print "Time=", Time, newline; ... At end: eventStart += interval; ... ... ... \end{verbatim} The first thing to note about this script is that it contains a hierarchy of nested control structures. The outermost \verb|Score| control structure contains a single \verb|At..for| structure, which in turn contains two further \verb|At| structures. The rest of the script is quite straightforward to understand. The parameters \verb|eventStart| and \verb|eventDur| are used to define the start time and duration of each event and the parameter \verb|interval| is used to define the interval between successive events. The key element is the use of the \verb|At end:| control structure. Every time the event occurs the body of the \verb|At end:| structure is executed just once at the very end of the event, and when it is a new start time is calculated for the next event. The script produces the following output: \begin{verbatim} Sample rate=44100 KHz Score duration=10 seconds Time=0 Time=1 Time=2 Time=3 Time=4 Time=5 Time=6 Time=7 Time=8 Time=9 Time=10 \end{verbatim} Of course the time interval between events does not have to be fixed. The value by which the \verb|eventStart| parameter is incremented can be derived from an arbitrary mathematical expression (see section \ref{section:expressions} for details of expression syntax). Since expressions can include numerical values derived from physical attributes read off the various instruments and devices, this technique opens the way for quite complex self-evolving events to be described. This is one of \tao's strengths: any physical attribute, such as the velocity of a point on an instrument or the current height of a hammer device can potentially be used as input to an algorithm which is playing the very same instruments and devices. \subsection{Comparison with Csound} You may ask why iteration has to be implemented by events rescheduling themselves, rather than by being able to pre-compose a series of even part of the answer is that it just evolved in this way. One specific reason though relates to my own personal interest in describing complex musical events which are self-evolving and depend upon lots of factors including feedback from the various physical objects in the synthesis, i.e. the instruments and devices. If you want to have stricter control over precomposing events then the best approach is to put all the start times, durations etc. into arrays and then set up iterated events which step through the arrays reading the appropriate values out for each successive event in a stream. [TO DO: Write more on this subject and provide examples] \section{Expressions} \label{section:expressions} This section describes \tao's expression syntax. If you have experience of a programming language such as C or C++ then there should be no surprises here. \subsection{Operators} \index{operators} The following is a list of operators which are understood by \tao: \begin{itemize} \item Arithmetic operators: \begin{verbatim} + addition - subtraction * multiplication / division % modulus \end{verbatim} \begin{iftex} \Operator{\~} \Operator{<<} \Operator{>>} \Operator{\&} \Operator{\^} \Operator{"|} \end{iftex} \item Bitwise operators: \begin{verbatim} ~ not << shift left >> shift right & bitwise AND ^ bitwise XOR | bitwise OR \end{verbatim} \begin{iftex} \Operator{\~} \Operator{<<} \Operator{>>} \Operator{\&} \Operator{\^} \Operator{"|} \end{iftex} \item Relational operators: \begin{verbatim} == equal != not equal < less than > greater than <= less than or equal to >= greater than or equal to \end{verbatim} \begin{iftex} \Operator{==} \Operator{!=} \Operator{<} \Operator{>} \Operator{<=} \Operator{>=} \end{iftex} \item Assignment operators: \begin{verbatim} += -= *= %= <<= >>= &= ^= \end{verbatim} \begin{iftex} \Operator{+=} \Operator{-=} \Operator{*=} \Operator{\%=} \Operator{<<=} \Operator{>>=} \Operator{\&=} \Operator{"|=} \end{iftex} \item Logical operators: \begin{verbatim} and or not \end{verbatim} \Operator{and} \Operator{or} \Operator{not} Note that the \verb|and| operator has higher precedence than the \verb|or| operator. This means that the expression \verb|a and b or c and d| evaluates to \verb|(a and b) or (c and d)|. \end{itemize} \subsection{Mathematical Functions} \label{section:math_functions} \index{math functions} Mathematical functions available from within \tao's synthesis language are inhereted directly from the gnu C++ math library. These include: \MathFunction{acos} \MathFunction{acosh} \MathFunction{asin} \MathFunction{atan} \MathFunction{atanh} \MathFunction{atan2} \MathFunction{cbrt} \MathFunction{cos} \MathFunction{cosh} \MathFunction{drem} \MathFunction{exp} \MathFunction{fabs} \MathFunction{ceil} \MathFunction{floor} \MathFunction{hypot} \MathFunction{log} \MathFunction{log10} \MathFunction{log1p} \MathFunction{pow} \MathFunction{rint} \MathFunction{sin} \MathFunction{sinh} \MathFunction{sqrt} \MathFunction{tan} \MathFunction{tanh} \begin{verbatim} acos(x) arc cosine. acosh(x) inverse hyperbolic cosine. asin(x) arc sine. atan(x) arc tangent. atanh(x) inverse hyperbolic tangent. atan2(x,y) arc tangent of two variables. cbrt(x) cube root. cos(x) cosine. cosh(x) hyperbolic cosine. drem(x,y) floating point remainder. exp(x) exponential. fabs(x) absolute value of floating point number. ceil(x) smallest integral number not less than x. floor(x) largest integral number not greater than x. hypot(x,y) Euclidean distance function. log(x) natural logarithm. log10(x) base-10 logarithm. log1p(x) logarithm of 1+x. pow(x,y) value of x raised to the power of y. rint(x) round to closest integer. sin(x) sine. sinh(x) hyperbolic sine. sqrt(x) square root. tan(x) tangent. tanh(x) hyperbolic tangent. \end{verbatim} The set of functions which are available is currently governed by what \tao's script parser has been told to expect. If \tao\ is ported to an OS other than Linux in the future this strategy will have to be rethought, since different math libraries often vary in the names and availability of functions. In addition to the standard math library functions two random number functions are also provided. These are \verb|randomi(x,y)| \MathFunction{randomi}, which returns a random integer in the range \verb|[x..y]|; and \verb|randomf(x,y)| \MathFunction{randomf}, which returns a random floating point number in the range \verb|[x..y]| inclusive. \subsection{The time-varying functions \emph{linear} and \emph{expon}} \label{section:linear_and_expon} Two simple time varying functions are provided for use in a score: \begin{verbatim} linear(,) expon(,) \end{verbatim} The time interval over which they change is determined by the scope in which they appear in the score. In other words they take their start and end times from the \Var{start} and \Var{end} variables. An example of their use is given in the following script: \begin{verbatim} Audio rate: 44100; Init: ... Score 1 sec: Every 0.1 secs: Print "At time ", Time, " linear value=", linear(0,1), " expon value=", expon(0.001,1), newline; ... ... \end{verbatim} When invoked this script produces the following output: \begin{verbatim} At time 0 linear value=0 expon value=0.001 At time 0.1 linear value=0.1 expon value=0.00199526 At time 0.2 linear value=0.2 expon value=0.00398107 At time 0.3 linear value=0.3 expon value=0.00794328 At time 0.4 linear value=0.4 expon value=0.0158489 At time 0.5 linear value=0.5 expon value=0.0316228 At time 0.6 linear value=0.6 expon value=0.0630957 At time 0.7 linear value=0.7 expon value=0.125893 At time 0.8 linear value=0.8 expon value=0.251189 At time 0.9 linear value=0.9 expon value=0.501187 At time 1 linear value=1 expon value=1 \end{verbatim} It should be noted that in the current version of \tao\ the tools provided for generating time varying functions are somewhat lacking when compared to Csound and its plethora of function table generators and its ability to create multi-segment linear or exponential curves. This deficiency will be addressed in a future version, probably with the introduction of a completely new set of table-based objects for use within a script. \section{Compiling and Executing a \tao\ Script} A \tao\ script is executed using the \Prog{tao} command, which takes as its only argument the name of the script with a \verb|.tao| suffix. Although from the user's point of view the language seems to be interpreted, since this one command interprets \emph{and} executes the script, in reality a \tao\ script is compiled into an executable file, which is then invoked automatically. The executable produced is stored in a file with the same name as the original script but with a \verb|.exe| suffix. Once a script has been compiled with the \Prog{tao} command, it can be executed several times without having to recompiled, provided the script isn't altered in the meantime. A \verb|.exe| executable has a number of command line options which are described below: \begin{description} \item[\texttt{-g}] Enables the \emph{instrument visualisation window} \hierindex{instrument!visualisation window}. if this option is omitted the synthesis will proceed without any graphics at all. This is useful for background batch processing of \tao\ scripts. \end{description} tao-1.0-beta-10May2006/doc/UserManual/script_reference.tex0000755000372200037200000004713707101706042020065 00000000000000\chapter{Object Method Reference} \label{section:object_method_reference} \index{methods} What follows in this section is a detailed description of all the methods which are provided by the various object classes. The syntax of each method is given, together with a description of its arguments, purpose and function. The vast majority of methods occur with the following generic syntax: \begin{verbatim} object.method(, .. ); \end{verbatim} where \verb|object| would be the name of an actual instrument, device or other object and \verb|method| the name of an actual method. However some of the most commonly accessed methods such as generating an access point from an instrument name and a pair of coordinates have a simpler syntax where the arguments are placed in parentheses immediately after the object name, i.e. there is no method name as such. For example: \begin{verbatim} instrument(,) \end{verbatim} In the following reference to all the object methods such methods are described merely by the arguments which are placed in between the brackets, e.g. \begin{verbatim} (,) \end{verbatim} \section{Instrument Methods grouped by Function} \hierindex{instrument!methods} All instrument methods are listed here grouped together by function. \subsection{Locking Parts of an Instrument} \index{locking} A number of instrument methods are available for locking parts of an instrument. These include: \begin{verbatim} lock(,) lockLeft() lockRight() lockTop() lockBottom() lockEnds() lockCorners() lockPerimeter() \end{verbatim} The \MethodIndex{lock} method locks the single cell which is nearest to the \verb|(,)| position specified in instrument coordinates (see section \ref{section:access_points}). The \MethodIndex{lockLeft}, \MethodIndex{lockRight}, \MethodIndex{lockTop} and \MethodIndex{lockBottom} methods each lock the cells at one extremity of an instrument. For rectangular sheets the behaviour is obvious, but for other instruments some clarification is needed. For strings, only the \Method{lockLeft} and \Method{lockright} methods are appropriate. For circular and elliptical sheets only a few cells at the edges of the sheet will be locked by each method. The \Method{lockEnds} method is equivalent to issuing a \Method{lockLeft} and \Method{lockRight} together and is used mostly with strings. Finally the \MethodIndex{lockCorners} is only appropriate for rectangular sheets and the \MethodIndex{lockPerimeter} is appropriate for all instruments except strings. \subsection{Damping Parts of an Instrument} \index{damping methods} \hierindex{methods!damping} A number of methods are provided for damping parts of an instrument. These include: \begin{verbatim} setDamping() setDamping(,) setDamping(,,) setDamping(,,,,) resetDamping() resetDamping() resetDamping(,) resetDamping(,,,) \end{verbatim} In each case the argument \verb|| is a floating point value in the range [0..1], where 0 represents no damping at all and 1 means that the portion of material affected will be locked rigidly in a fixed position. The progression from the former state to the latter as \verb|| changes from 0 to 1 is logarithmic rather than linear for reasons which are explained below. The damping value \verb|| is converted via the following formula into the appropriate \Attr{velocityMultiplier} attribute (see section \ref{section:cell_attributes}): \[ v_{m} = 1 - \frac{10000^{d}}{10000} \] where $v_{m}$ and $d$ correspond to \Attr{velocityMultiplier} and \verb|| respectively. You may remember that the \Attr{velocityMultiplier} value also lies in the range [0..1] and on each tick of the synthesis engine the velocity of each cell is multiplied by this value. The \MethodIndex{resetDamping} family of methods set the damping back to what it was when the instrument was created. This is useful for situations where it is desirable to temporarily damp a region. An example application might be playing a harmonic on a string. Any guitarist will know that in order to do so a finger is placed momentarily in contact with one of the strings, over a node, whilst (or after) the string is plucked. Once the harmonic begins to clearly ring out the players finger is removed again leaving the string to continue vibrating in its modified pattern. \subsection{Graphically Placing Instruments} \label{graphical_placement} \hierindex{instrument!graphical placement} \hierindex{methods!graphical placement of instruments} These methods allow the user to override \tao's default graphical placement scheme. The default scheme is not very intelligent in the current version and simply places each new instrument above the previous one (`above' meaning in the +ve $y$ direction). The \MethodIndex{placeAt} method allows the position of the bottom left hand corner of the bounding box surrounding the instrument to be set explicitly. The \MethodIndex{placeAbove}, \MethodIndex{placeBelow}, \MethodIndex{placeRightOf} and \MethodIndex{placeLeftOf} methods allow an instrument to be placed relative to another instrument. In the case of the methods which expect an additional argument \verb||, this argument specifies an additional offset measured in world coordinates from the reference instrument (the default is to seperate each instrument by 5 units in world coordinates). This is somtimes necessary to prevent the instrument visualisation window from becoming too cluttered. \begin{verbatim} placeAt() placeAbove() placeBelow() placeRightOf() placeLeftOf() placeAbove(, ) placeBelow(, ) placeRightOf(, ) placeLeftOf(, ) \end{verbatim} \subsection{Accessing the Internal Attributes of an Instrument} \hierindex{instrument!attributes!accessing} \hierindex{methods!instrument attribute} This set of methods allow the internal attributes of an instrument to be inspected. Please note that some of these methods are only listed for completeness. In practice they are not of much use in the average \tao\ script. \begin{verbatim} getName() getMagnification() getWorldX() getWorldY() getXMax() getYMax() getXFrequency() getYFrequency() \end{verbatim} The \MethodIndex{getName} method returns a string containing the name of the instrument. The \MethodIndex{getMagnification} method returns the current factor by which the visual amplitude of the waves in the instrument are being magnified. The two methods \MethodIndex{getWorldX} and \MethodIndex{getWorldY} return the world coordinates of the bottom left hand corner of the bounding box around the instrument (i.e. the position in the $xy$ plane). The \MethodIndex{getXMax} and \MethodIndex{getXMax} methods return the $N-1$ where $N$ is the width or height of the instrument in cells respectively. The only two methods which should be of any use in the average \tao\ script are \MethodIndex{getXFrequency} and \MethodIndex{getYFrequency}. These return the pitch values which were passed in when the instrument was created, but converted to Hertz, regardless of the initial pitch format used. \subsection{Setting the Internal Attributes of an Instrument} \hierindex{instrument!attributes!setting} The only instrument attribute which can be set by a user is the factor by which the amplitude of vibrations in the component are exaggerated in the visualisation window. This is useful for evening out differences between components within an instrument, for the purposes of visualisation only. This attribute has no effect on sound output. \begin{verbatim} setMagnification() \end{verbatim} \subsection{Automatically Generating Access Points} \hierindex{access points!generating} \hierindex{methods!access point generation} Each of the following set of methods generates a single access point on an instrument given $x$ and $y$ coordinates. The \MethodIndex{point(...)} methods only differ from the other two in that they do not lead to the automatic generation of graphical markers in the instrument visualisation window. \begin{verbatim} (, ) () point(, ) point() e.g. rect(left,0.5) string(0.7) ellipse.point(0.1,centre) \end{verbatim} \subsection{Accessing Individual Cells} \hierindex{methods!accessing cells} The following method allows access to the nearest cell to the position on the instrument specified. Once the cell has been selected its internal attributes can be examined. You should never really need to use this method as it was really designed for \tao's internal use. Also access points provide a much more flexible mechanism for interacting with instruments. \begin{verbatim} at(, ) \end{verbatim} \section{Device Methods} \hierindex{Device methods} \hierindex{methods!Device} This section describes all the methods available to the different devices. It begins by listing generic methods which are applicable to any device. \subsection{Generic Device Methods} The following methods are available with any device. \begin{verbatim} getName() getX() getY() apply() remove() \end{verbatim} The \MethodIndex{getName} method returns a string containing the name of the device. The \MethodIndex{getX} and \MethodIndex{getY} methods return the current position in instrument coordinates of the device if it has actually been applied to an instrument. Otherwise they return zero. The return values are also zero if the device has been applied to an instrument and removed again. \subsection{Bow Methods} \index{Bow methods} \hierindex{methods!Bow} The main attributes of a Bow device are the force with which it is applied to the instrument (which has a marked effect on the bow's ability to sustain the frictional forces needed to move the instrument), and its velocity. The following methods are available with a bow. \begin{verbatim} setForce() setVelocity() getForce() getVelocity() () (, ) (, , ) \end{verbatim} The last three methods provide three different ways to apply a bow to an instrument. The first specifies an access point, the second an instrument and a single $x$ coordinate (for a string), and the third an instrument and both $x$ \& $y$ coordinates. Although these methods are available in a script an alternative syntax is usually used for applying a bow to an instrument at a specific point. This consists of the access point specification (the instrument name followed by the instrument coordinates enclosed in parentheses) followed by the \emph{apply} operator: \verb|--|, followed by the name of the bow. For example in the following code fragments the left and right hand sides are exactly equivalent: \begin{verbatim} Bow bow; Init: bow(string(0.1)); <==> string(0.1) -- bow; bow(rect(0.5,0.7)); <==> rect(0.5,0.7) -- bow; ... \end{verbatim} \subsection{Hammer Methods} \index{Hammer methods} \hierindex{methods!Hammer} For a description of the Hammer device see section \ref{section:hammer_device}. The following methods are available with a hammer. \begin{verbatim} reset() drop() () (, ) (, , ) setMass() setPosition(

) setInitVelocity() setGravity() setHeight() setDamping() setHardness() setMaxImpacts() getMass() getPosition() getVelocity() getInitVelocity() getGravity() getHeight() getDamping() getHardness() numberOfImpacts() getMaxImpacts() \end{verbatim} The \MethodIndex{reset} method resets the hammer to its initial height and causes it to wait for a subsequent call to the \MethodIndex{drop} method before the hammer will start falling and interacting with the instrument. As with the bow device there are three unnamed methods for specifying the access point with which the hammer will interact. The first expects an access point, the second an instrument name and a single $x$ coordinate and the third an instrument name followed by an $x$ and $y$ coordinate. The \verb|set...| family of methods are used to set the various attributes of the hammer. Note that the \verb|setHeight| method sets the height from which the hammer is dropped whereas the \verb|setPosition| method sets the instantaneous height of the hammer. The \verb|setInitVelocity| method sets the initial velocity of the hammer immediately after the \verb|drop| method has been called. The \verb|setHardness| method sets the strength of the spring which is used to simulate the elastic connection with the instrument. This is usually a value in the range [0..1] where 0 means the spring has no effect and 1 means that the spring has the same strength as the springs used in \tao's material. Values greater than 1 can also be used although this can lead to the model becoming unstable, due to the inherent limitations in modeling a continuous physical system using discrete time steps or ticks. \subsection{Connector Methods} \index{Connector methods} \hierindex{methods!Connector} The Connector methods listed below allow any combination of access and anchor points to be coupled together. To recap, an \Term{anchor point} is a fixed numerical value (usually 0.0) and a spring is connected between the access point specified and this anchor point, effectively restricting the vibrations of the instrument at that point. \begin{verbatim} (, ) (, , ) (, ) (, , ) (, ) (, , ) \end{verbatim} The \verb||\index{spring strength} argument expected by some of the methods sets the strength of the spring used to connect the two points. It is usually a value in the range [0..1] but higher values may sometimes work. You should be aware though that if you use a value higher than 1 \tao's cellular model may become unstable, leading to exponentially increasing noisy vibrations. This is limitation inherent the kind of discrete time step modelling used by \tao. \subsection{Stop Methods} \index{Stop methods} \hierindex{methods!Stop} The following stop device methods are available: \begin{verbatim} dampModeOn() dampModeOff() setAmount() setDamping() () (, ) (, , ) (, ) \end{verbatim} To briefly recap, the Stop device provides a rudimentary mechanism for stopping strings in order to obtain specific pitches from them. The \verb|| attribute is a value in the range [0..1], with 0 meaning that the string is not stopped at all and 1 meaning that it is fully stopped. The \verb|| attribute determines how highly damped the left hand side of the string will be (the right hand side is given the appropriate length to achieve the specified pitch). The unnamed \verb|(...)| methods are used to apply the stop to an instrument. Much like the bow and hammer devices there are three standard versions available, expecting either an access point, an instrument and single $x$ coordinate, or an instrument and both $x$ and $y$ coordinates. However for the Stop device there is a fourth method \verb|(, )| available. This method, given a string instrument and a pitch as arguments will automatically calculate at what point the Stop device should be applied to the string in order to produce the desired pitch. Note that it is always the portion of the string to the right of the applied Stop device which has the correct pitch. This should be borne in mind if connecting the string to other components. If you build your instrument with the left hand sides of each string attached to some sort of resonator you will get all the wrong pitches when you start to play the instrument! Note also that as with the Bow and Hammer devices the preferred syntax to use in a script when applying the device to an instrument is as follows: \begin{verbatim} string(0.1) -- stop; \end{verbatim} which is exactly equivalent to: \begin{verbatim} stop(string(0.1)); \end{verbatim} The first format is more commonly used since it is more clearly legible when quickly scanning a script to see what it does. Wherever the \verb|--| operator appears in a script, you know that there is some kind of interfacing between access points and devices taking place. \subsection{Output Methods} \index{Output methods} \hierindex{methods!Output} The Output device provides methods for writing sound samples out to the various channels of its associated output file. The \MethodIndex{ch1} and \MethodIndex{chL} methods are equivalent, as are the \MethodIndex{ch2} and \MethodIndex{chR} methods. Obviously \Method{chL} and \Method{chR} are designed for use with two channel stereo output. In each case \verb|| is an arbitrary mathematical expression yielding a floating point value. There is no need to ensure that the output samples stay within a predefined range, since all \tao\ output files are normalised as a post-processing stage before conversion into a more conventional integer-based format such as WAV. This is achieved with the \Prog{taosf} shell command (see section \ref{section:output_files}). \begin{verbatim} ch1() ch2() ch3() ch4() chL() chR() \end{verbatim} \section{Access Point Methods} These methods are some of the most important since they are the ones which allow simulated physical interaction with \tao's cellular material. \begin{verbatim} getPosition() getVelocity() getForce() getInstrument() applyForce() clear() \end{verbatim} The \MethodIndex{getPosition}, \MethodIndex{getForce} and \MethodIndex{getVelocity} methods return the physical attributes of the material at the access point. All three values returned are with respect to the $z$ axis of the material. The \MethodIndex{getInstrument} method returns the instrument on which the access point is operating. The \MethodIndex{applyForce} method applies the given force at the position of the access point, not surprisingly! Note that in the same way that an access point can be used to read the physical attributes of the material at any point, forces can be applied at any point too. This means that you could for example generate a moving access point whose instrument coordinates were governed by some time varying value generated by an arbitrary expression, and apply a time varying force at that moving point. The following example illustrates the use of the access point methods (although I don't know whether it would produce interesting sounds or not). \begin{verbatim} Audio rate: 44100; String s(200 Hz, 20 secs); AccessPoint p1, p2; Param x1, x2; Init: s.lockEnds(); ... Score 10 secs: x1=0.5+0.5*cos(Time*1000.0); x2=0.5+0.5*cos(Time*1100.0); p1=s(x1); p2=s(x2); Every 0.01 secs: Print "At time ", Time, ", position=", p1.getPosition(), " velocity=", p1.getVelocity(), newline; ... If p1.getForce() < 1: p2.applyForce(1.0); ... If p2.getVelocity() > -1: p1.applyForce(-1.0); ... ... \end{verbatim} Finally, the \MethodIndex{clear} method resets the access point to be null. Attempting to read any physical attributes off of the access point will result in zero being returned. In addition, attempting to apply a force to a null access point has no effect. \section{Pitch Methods} tao-1.0-beta-10May2006/doc/UserManual/tutorial.tex0000755000372200037200000005722407101673704016414 00000000000000\chapter{Tutorial} \label{section:tutorial} This section introduces the main concepts involved in creating interesting virtual instruments using \tao. It does so in a `hands on' manner with the aid of practical script examples. All of the examples presented in this section are available in the \verb|examples| directory of the distribution. The examples start off with the most basic instrument possible -- a single string -- and work up to more and more complex instruments. The examples presented here are divided into two categories. The first set are designed to illustrate one by one the main techniques involved in contructing \tao\ instruments. Each script covers one major technique. The second set are concerned with designing synthesis scenarios which produce interesting sounds. So don't be too surprised if the first set of scripts produce either no sound at all or rather uninteresting sounds! By the end of this tutorial you should have at your disposal a useful armoury of techniques which will hopefully whet your appetite for creating your own instruments. \section{Learning the Basics} \subsection{A simple string instrument} The simplest possible instrument consists of a single string. The following script illustrates how to create such an instrument, `pluck' it and generate an output file. \begin{verbatim} Audio rate: 44100; String string(100 Hz, 20 secs); Output output(stereo); Init: string.lockEnds(); ... Score 20 secs: At 0 secs for 1 msecs: string(0.1).applyForce(1.0); ... output.chL: string(0.1); output.chR: string(0.9); Every 0.1 secs: Print Time, newline; ... ... \end{verbatim} The first line of this script declares the audio sampling rate of any output files generated (which in the current version has to be 44100). A single string with a fundamental frequency of 100Hz is created, followed by a single two-channel output device which will be used to write the movements of the string to a soundfile. The statement \verb|string.lockEnds()| is contained within the \emph{Init} block of the script. This block of statements is executed once just prior to the performance and is delimited (as with any block of statements in \tao\ with a \verb|:| just after the keyword \Kwd|Init| and a \verb|...| just after the last statement. The score is fairly self-explanatory. It has a duration of 20 seconds and for a short time interval at the beginning of the performance a fixed force of magnitude 1 is applied to a point on the string one tenth of the way along its length. The movements of two points on the string are traced throughout the performance and \subsection{Damping the ends of the string} Damping local regions of an instrument more highly than the rest of the instrument leads to the vibrations in that part of the instrument dying away more quickly. This is one of \tao's most important features as it is probably the single most significant factor in determining the character of an instrument after its basic shape and structure. For strings damping can be used to produce a more natural spectral decay by choosing to damp small regions near the ends of the string. By \emph{small regions} I mean in the order of $1/10$ to $1/20$ of the length of the string. The exact value chosen for the amount of damping depends on how quickly you want the harmonics to die away. For example: \begin{verbatim} Audio rate: 44100; String string(100 Hz, 20 secs); Output output(stereo); Init: string.lockEnds(); string.setDamping(left, 0.1, 0.1); string.setDamping(right, 0.9, 0.1); ... Score 20 secs: At 0 secs for 1 msecs: string(0.1).applyForce(1.0); ... output.chL: string(0.1); output.chR: string(0.9); Every 0.1 secs: Print Time, newline; ... ... \end{verbatim} \subsection{Producing harmonics from the string} \subsection{Coupling two strings together} \subsection{An instrument with an array of pitched strings} \subsection{Coupling the strings together} \subsection{A rectangular sheet with locked corners and local damping} \subsection{Bowed and stopped strings} \subsection{Moving access points} \subsection{Using the Connector device} \subsection{Using the Hammer device} \subsection{Using the Output device} \subsection{Output Expressions} \subsection{Controlling the graphical layout of instruments} \section{Combining the techniques to make interesting sounds} \subsection{Tips for bowing strings} \subsection{Effective uses of damping} \subsection{Using Connector devices and anchor points} \subsection{Rules of thumb for effective instrument design} \begin{itemize} \item Try to make everything dynamically evolve. It will not cost you any more computationally but will sound more interesting. \item Always damp parts of an instrument so that its spectral profile will change as the sound decays away. Instruments with uniform damping often sound the most clinical and synthetic. \item Generate lots of output file from each performance. Whether or not you generate any output, \tao\ will still have to churn its way through the intensive calculations needed to realise a performance. It will not cost you any more to see how ten different points on an instrument sound, rather than just one. \item Use lots of Connector devices. The more highly coupled an instrument is the more complex the resulting vibrations will be. Once again using lots of Connectors will not make the performance significantly more computationally expensive than using none, but it will make the resulting sounds more interesting. \item Experiment with small parts of a large instrument in isolation before coupling them together. If one of your strings goes ``clunk'' instead or ringing beautifully when you pluck it, there is not much sense in connecting 100 such strings to a resonator and coming back later only to find that the whole instrument goes ``clunk''! \end{itemize} \section{Using access points} \subsection{Example 1 - accesspoint1.tao} This example illustrates how to use access points\index{access points} to generate output from an instrument and send the resulting data via an Output device to a output file. \begin{verbatim} Audio rate: 44100; String s1(100 Hz, 20 secs); AccessPoint l=s1(0.1), r=s1(0.9); Output out(2); Init: s1.lockEnds(); ... Score 5.0 secs: At 0 secs for 0.1 msecs: s1(0.05).applyForce(1.0); ... Every 0.1 secs: Print Time, " ", l, " ", r, newline; ... out.chL: l; out.chR: r; ... \end{verbatim} \subsection{Example 2 - accesspoint2.tao} This example illustrates the use of access points\index{access points} to connect together two components to form a more interesting compound instrument. It does so by creating two strings and applying a short impulse to one of them. A Connector device is used to connect together two access points, one on each string. The access points are not fixed but move along their respective strings as the performance progresses. \begin{verbatim} // accesspoint2.tao // // Create two strings and implement a connection between them using // two moving access points. Audio rate: 44100; String string1(200 Hz, 20 secs); String string2(200 Hz, 20 secs); AccessPoint point1, point2; Connector connector; Init: string1.lockEnds(); string2.lockEnds(); ... Score 5.0 secs: At 0 secs for 0.1 msecs: string1(0.05).applyForce(1.0); ... ControlRate 100: point1=string1(linear(0,1)); point2=string2(linear(1,0)); ... point1 -- connector -- point2; ... \end{verbatim} \section{An instrument with a single string} This script creates an instrument with a single string and then applies a force to one end of it for a short time interval. \begin{verbatim} // string.tao // // Create a single string and apply a very short impulse to one // end. Audio rate: 44100; String string(200 Hz, 20 secs); Init: string.lockEnds(); ... Score 5 secs: At 0 secs for 1 msecs: string(0.1).applyForce(linear(1,0)); ... ... \end{verbatim} \section{Using the Bow device - bow.tao} \begin{verbatim} \end{verbatim} \section{Creating a circular sheet} \subsection{Example 1 - circle.tao} This script creates a single circular sheet, locks its entire perimeter, and then applies a linearly changing force at a point $(x=0.3,y=0.3)$ for an interval of 1 millisecond. \begin{verbatim} Audio rate: 44100; Circle circle(300 Hz, 20 secs); Init: circle.lockPerimeter(); ... Score 5 secs: At 0 secs for 1 msecs: circle(0.3,0.3).applyForce(linear(40,0)); ... ... \end{verbatim} \subsection{Example 2 - circle2.tao} This script is similar to the previous one except that the circle has its left and right edges locked instead of the whole perimeter. \begin{verbatim} Audio rate: 44100; Circle circle(300 Hz, 20 secs); Init: circle.lockLeft().lockRight(); ... Score 5 secs: At 0 secs for 1 msecs: circle(0.3,0.3).applyForce(linear(30,0)); ... ... \end{verbatim} \section{Using the Connector device - connector.tao} This script creates two strings and a Connector device. The Connector device is used to couple the two strings together. The access points representing the end points of the connector move during the performance. One migrates from one end of one of the strings to the other, whilst the second migrates in the opposite direction on the other string. This script also involves the \Type{Param} keyword. \begin{verbatim} Audio rate: 44100; String string1(200 Hz, 30 secs); String string2(200 Hz, 30 secs); Connector conn; Param x1,x2; Init: string1.lockEnds(); string2.lockEnds(); ... Score 1 secs: At start for 1 msecs: string1(0.1).applyForce(1.0); ... x1 = linear(0,1); x2 = linear(1,0); string1(x1) -- conn -- string2(x2); ... \end{verbatim} \section{Damping parts of an instrument - damp.tao} This script creates a set of strings and damps the same region at the left hand end of each string but to different degrees. The strings are then all plucked in unison and the subsequent wave patterns give a side by side comparison of the effects of different damping values. \begin{verbatim} Audio rate: 44100; String string1(300 Hz, 20 secs); String string2(300 Hz, 20 secs); String string3(300 Hz, 20 secs); String string4(300 Hz, 20 secs); String string5(300 Hz, 20 secs); String string6(300 Hz, 20 secs); String string7(300 Hz, 20 secs); String string8(300 Hz, 20 secs); String string9(300 Hz, 20 secs); String string10(300 Hz, 20 secs); Init: string1.lockEnds().setDamping(left,1/20,0.0); string2.lockEnds().setDamping(left,1/20,0.1); string3.lockEnds().setDamping(left,1/20,0.2); string4.lockEnds().setDamping(left,1/20,0.3); string5.lockEnds().setDamping(left,1/20,0.4); string6.lockEnds().setDamping(left,1/20,0.5); string7.lockEnds().setDamping(left,1/20,0.6); string8.lockEnds().setDamping(left,1/20,0.7); string9.lockEnds().setDamping(left,1/20,0.8); string10.lockEnds().setDamping(left,1/20,0.8); ... Score 5 secs: At 0 secs for 0.1 msecs: string1(0.1).applyForce(10); string2(0.1).applyForce(10); string3(0.1).applyForce(10); string4(0.1).applyForce(10); string5(0.1).applyForce(10); string6(0.1).applyForce(10); string7(0.1).applyForce(10); string8(0.1).applyForce(10); string9(0.1).applyForce(10); string10(0.1).applyForce(10); ... Every 0.1 secs: Print Time, newline; ... ... \end{verbatim} \section{Emergent behaviour (diffraction) - diffraction.tao} This script creates two rectangular sheets and joins them together using the \Statement{Join} statement. The boundary between the two sheets is then locked in several places leaving a few `slots' where the waves can get through. A short impulse is applied to one of the sheets named verb|source| and the resulting wave fronts interfere after having passed through the slots to form diffraction patterns. \begin{verbatim} Audio rate: 44100; Rectangle source(150 Hz, 300 Hz, 20 secs); Rectangle dest(150 Hz, 300 Hz, 20 secs); Init: source.lockCorners(); dest.lockCorners(); source.lock(0.000000, 0.050000, top, top); source.lock(0.070000, 0.120000, top, top); source.lock(0.140000, 0.190000, top, top); source.lock(0.210000, 0.260000, top, top); source.lock(0.280000, 0.330000, top, top); source.lock(0.350000, 0.400000, top, top); source.lock(0.420000, 0.470000, top, top); source.lock(0.490000, 0.540000, top, top); source.lock(0.560000, 0.610000, top, top); source.lock(0.630000, 0.680000, top, top); source.lock(0.700000, 0.750000, top, top); source.lock(0.770000, 0.820000, top, top); source.lock(0.840000, 0.890000, top, top); source.lock(0.910000, 0.960000, top, top); source.lock(0.980000, 1.000000, top, top); Join source(centre, top) to dest(centre, bottom); dest.setMagnification(5.0); ... Score 5 secs: At 0 secs for 0.1 msecs: source(0.5,bottom).applyForce(50); ... ... \end{verbatim} \section{Creating an elliptical sheet} \subsection{Example 1 - ellipse.tao} This script creates an elliptical sheet, locks the whole perimeter and then applies a short impulse to the sheet at a point $(x=0.15,y=0.5)$. \begin{verbatim} Audio rate: 44100; Ellipse ellipse(200 Hz, 400 Hz, 20 secs); Init: ellipse.lockPerimeter(); ... Score 5 secs: At 0 secs for 0.5 msecs: ellipse(0.15,0.5).applyForce(linear(30,0)); ... ... \end{verbatim} \subsection{Example 2 - ellipse2.tao} This script is similar to the previous one except that instead of locking the whole perimeter, a thin strip of the instrument is locked. \begin{verbatim} Audio rate: 44100; Ellipse ellipse2(200 Hz, 400 Hz, 20 secs); Init: ellipse2.lock(left, 0.8, centre, centre); ... Score 5 secs: At 0 secs for 0.5 msecs: ellipse2(0.3,0.2).applyForce(linear(30,0)); ... ... \end{verbatim} \section{Using the Hammer device - hammer.tao} This script illustrates the use of the Hammer device. It creates a single string and a single hammer. It then locks the ends of the string, applies the hammer to a point $x=0.7$ on the string, and sets some hammer attributes. Finally it drops the hammer at the beginning of the performance, leaving it to bounce naturally on the string. \begin{verbatim} Audio rate: 44100; String string(200 Hz, 30 secs); Hammer hammer; Init: string.lockEnds(); string(0.7) -- hammer; hammer.setGravity(0.0001).setMass(200.0); ... Score 10 secs: At 0 secs: hammer.drop(); ... ... \end{verbatim} \section{Locking parts of an instrument - lock.tao} This script illustrates the use of the various \Term{locking} instrument methods. These include \Method{lockCorners}, \Method{lockLeft}, \Method{lockRight}, \Method{lockTop}, \Method{lockPerimeter}, and \Method{lock}. It creates six rectangular instruments and locks each one in a slightly different way. It then applies short impulse to each instrument so as to allow a side by side comparison of the effects on each. \begin{verbatim} Audio rate: 44100; Rectangle rect1(500 Hz, 600 Hz, 20 secs); Rectangle rect2(500 Hz, 600 Hz, 20 secs); Rectangle rect3(500 Hz, 600 Hz, 20 secs); Rectangle rect4(500 Hz, 600 Hz, 20 secs); Rectangle rect5(500 Hz, 600 Hz, 20 secs); Rectangle rect6(500 Hz, 600 Hz, 20 secs); Init: rect1.lockCorners(); rect2.lockLeft().lockRight(); rect3.lockTop().lockBottom(); rect4.lockPerimeter(); rect5.lock(0.2,0.4); rect6.lock(0.7, right, 0.7, top); ... Score 5 secs: At 0 secs for 1 msecs: rect1(0.1,0.1).applyForce(linear(30,0)); rect2(0.1,0.1).applyForce(linear(50,0)); rect3(0.1,0.1).applyForce(linear(50,0)); rect4(0.1,0.1).applyForce(linear(50,0)); rect5(0.1,0.1).applyForce(linear(20,0)); rect6(0.1,0.1).applyForce(linear(30,0)); ... ... \end{verbatim} \section{Arrays of Output devices - outputarray.tao} This script creates a string and an array of Output devices. It then applies a short impulse to the string and writes output to each Output device in the array from different positions on the string. \begin{verbatim} Audio rate: 44100; String string(200 Hz, 30 secs); Output outputs(mono)[5]; Init: string.lockEnds(); ... Score 30 secs: At start for 0.1 secs: string(0.1).applyForce(1.0); ... outputs[0].ch1: string(0.1); outputs[1].ch1: string(0.3); outputs[2].ch1: string(0.5); outputs[3].ch1: string(0.7); outputs[4].ch1: string(0.9); ... \end{verbatim} \section{Using the Output device - outputs.tao} This script illustrates \Term{stereo} and \Term{mono} Output devices. It creates one of each and a single string and then writes output to each channel of each device from different positions on the string, after a short impulse has been applied to the string. \begin{verbatim} Audio rate: 44100; String string(100 Hz, 30 secs); Output out1(stereo), out2(mono); Init: string.lockEnds(); ... Score 30 secs: At start for 0.1 msecs: string(0.9).applyForce(1.0); ... out1.chL: string(0.1); out1.chR: string(0.9); out2.ch1: string(0.5); Every 0.1 secs: Print Time, newline; ... ... \end{verbatim} \section{Using pitches - pitches.tao} This script illustrates the various pitch formats which are supported by \tao. These include \Term{oct}, \Term{cps}, \Term{Hz} and \Term{note name} formats (see sections \ref{section:pitches_and_frequencies} and \ref{section:pitch_declarations}). \begin{verbatim} Audio rate: 44100; String array1[]= { (200 Hz, 20 secs), (220 Hz, 20 secs), (240 Hz, 20 secs), (260 Hz, 20 secs) }; String array2[]= { (8.00 pch, 20 secs), (8.04 pch, 20 secs), (8.06 pch, 20 secs), (8.08 pch, 20 secs) }; String array3[]= { (8.0 oct, 20 secs), (8.2 oct, 20 secs), (8.4 oct, 20 secs), (8.6 oct, 20 secs) }; Counter n; Init: For n = 0 to 3: array1[n].lockEnds(); array2[n].lockEnds(); array3[n].lockEnds(); ... ... Score 5 secs: Label(array1[0], 1.0, 0.0, 0.0, "LABEL", 0); At start for 0.1 msecs: For n = 0 to 3: array1[n](0.1).applyForce(1.0); array2[n](0.1).applyForce(1.0); array3[n](0.1).applyForce(1.0); ... ... ... \end{verbatim} \section{Creating a rectangular sheet} \subsection{Example 1 - rectangle.tao} This script creates a rectangular sheet, locks all four corners and then applies a short impulse at a point ($x$=0.1,$y$=0.1). This impulse consists of a force linearly changing from a value of 30 to 0 over a 1ms interval. \begin{verbatim} Audio rate: 44100; Rectangle rectangle(300 Hz, 400 Hz, 20 secs); Init: rectangle.lockCorners(); ... Score 5 secs: At 0 secs for 1 msecs: rectangle(0.1,0.1).applyForce(linear(30,0)); ... ... \end{verbatim} \subsection{Example 2 - rectangle2.tao} This script is similar to the previous one except that the left and right sides of the rectangle are locked instead of all four corners. \begin{verbatim} Audio rate: 44100; Rectangle rectangle2(150 Hz, 800 Hz, 20 secs); Init: rectangle2.lockLeft().lockRight(); ... Score 5 secs: At 0 secs for 1 msecs: rectangle2(0.1,0.1).applyForce(linear(30,0)); ... ... \end{verbatim} \section{Using the Stop device - stop.tao} This script illustrates the use of the \Device{Stop} device. \begin{verbatim} Audio rate: 44100; String string1(200 Hz, 40 secs); Stop stop; Param position, amount=0.0; Init: string1.lockEnds(); ... Score 0.3 secs: At 0 secs for 0.1 msecs: string1(0.9).applyForce(10.0); ... position=linear(0.1, 0.9); string1(position) -- stop; From 0.05 secs to 0.1 secs: amount=linear(0,1); stop.setAmount(linear(0,1)); ... From 0.20 to 0.25 secs: amount=linear(1,0); stop.setAmount(linear(1,0)); ... Every 0.005 secs: Print Time, " ", amount, newline; ... ... \end{verbatim} \section{Creating an array of strings - stringarray.tao} \begin{verbatim} Audio rate: 44100; String string[]= { (8.00 pch, 20 secs), (8.01 pch, 20 secs), (8.02 pch, 20 secs), (8.03 pch, 20 secs), (8.04 pch, 20 secs), (8.05 pch, 20 secs), (8.06 pch, 20 secs), (8.07 pch, 20 secs), (8.08 pch, 20 secs), (8.09 pch, 20 secs), (8.10 pch, 20 secs), (8.11 pch, 20 secs) }; Counter n=0; Param startPluck=0.0, pluckDuration=0.001; Init: For n = 0 to 11: string[n].lockEnds(); ... ... Score 5 secs: At start: n=0; ... At startPluck for pluckDuration: At start: Print "Plucking string ", n, " at ", startPluck, " seconds", newline; ... string[n](0.1).applyForce(linear(1,0)); At end: n+=1; If n <= 11: startPluck+=0.1; // pluck the next string in 0.1 seconds time Print "Pluck string ", n, " at ", startPluck, " seconds", newline; ... Else: startPluck=-1.0; // prevent any more plucks from occurring // by setting startPluck to a negative value. Print "No more strings to be plucked", newline; ... ... ... ... \end{verbatim} tao-1.0-beta-10May2006/doc/UserManual/user_interface.tex0000755000372200037200000001003207101671424017526 00000000000000\chapter{\tao's User Interface} \index{user interface} This section describes \tao's user interface in detail and includes shell commands, and mouse and key bindings for the visualization window. \section{Shell commands} A number of shell commands\index{shell commands} are provided for executing scripts and converting the output files to WAV format. These are described below: \renewcommand{\descriptionlabel}[1]% {\hspace{\labelsep}\texttt{#1}} \begin{description} \item[tao