Copy of aRts for Trinity modifications

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/dependencies/arts@1070145 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

4 files changed, 279 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..a4c137b
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1 @@
+EXTRA_DIST = NEWS README TODO
diff --git a/doc/NEWS b/doc/NEWS
new file mode 100644
index 0000000..0b68fe4
--- /dev/null
+++ b/doc/NEWS
@@ -0,0 +1,58 @@
+aRts-1.2.0:
+- added EsounD support
+- fixed autosuspend in conjunction with full duplex
+
+aRts-1.1.0:
+- added functions to StdSynthModule to find if/how many other modules are
+  connected to the inputs and outputs of yourself
+
+aRts-1.0.0:
+- full duplex fixed
+
+aRts-0.7.0:
+- recording in the C API
+- new interface for video embedding (Arts::VideoPlayObject) via X11 embedding
+- threaded oss audio i/o (-a toss) which works better with some kernel drivers
+- irix audio i/o method (-a sgi)
+- ALSA-0.9.0 support
+- Preference=N lines in .mcopclass files make it possible to to choose one
+  implementation over another if they both implement the same interface
+
+aRts-0.6.1:
+- new artsdsp -s (single threaded) option for compatibility to more programs
+  (for instance netscape)
+- ALSA-0.9.0 support
+- bugfixes: artsdsp/artsc rpath fix, alsa crash without soundcard fixed, md5
+  cookie loading, oss driver endianess issue, compile fixes
+
+aRts-0.6.0:
+- new interfaces (Arts::InputStream, Arts::StreamPlayObject) for decoding
+  streams of data with PlayObjects (rather than just files)
+- new Arts::PitchablePlayObject for changing playing speed/pitch
+- support for streaming of data from kioslaves into PlayObjects
+- dynamic implementation of classes/attributes (Arts::DynamicSkeleton)
+
+(some of the items that are listed in aRts-0.6.0 have been done somewhere
+ between 0.4 and 0.6 and only now found its way into this)
+
+aRts-0.5.4:
+- fix random segfaults on solaris
+
+aRts-0.5.3:
+- performance improvement for aRts midi instruments (bus code rewritten)
+- structures designed by artsbuilder can be used modules in structures again
+  (and elsewhere), via generic Arts::Loader's
+
+aRts-0.5.2:
+- threading support (libmcop_mt)
+- glib-2.0 mainloop integration (libgmcop)
+- KArtsWidget makes it easy to use Arts::Widget implementations in conjunction
+  with qt widgets (i.e. no extra window), this also removes the annoying extra
+  window in artscontrol
+- generic gui factory used by noatun and artscontrol to create effect guis
+
+================================================================================
+This file starts in the middle of nowhere, because it hasn't always been
+here. But please update this if you do bigger changes (fixing a spelling
+error in a comment probably doesn't count, doing one of the TODO items
+most certainly does).
diff --git a/doc/README b/doc/README
new file mode 100644
index 0000000..60a3beb
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,5 @@
+All of the aRts documentation is now in "The aRts Handbook" which is
+in KDE DocBook format, part of kdemultimedia. It should be found on a
+KDE system in $KDEDIR/share/doc/HTML/default/artsbuilder/index.html.
+
+An on-line version can be found at http://www.arts-project.org/doc/handbook
diff --git a/doc/TODO b/doc/TODO
new file mode 100644
index 0000000..37f856e
--- /dev/null
+++ b/doc/TODO
@@ -0,0 +1,215 @@
+- fix problems with REGISTER_IMPLEMENTATION:
+  => sometimes, global constructors don't work, so we'd better get rid
+     of them entierly ; instead, an init function needs to be added to
+     dynamically loaded modules
+- get rid of all error handling done by assert ; thus, one by one review
+  each assert if it can happen under any circumstances if yes, it needs
+  to be replaced by some other mechanism
+- report errors properly if some component could not be loaded ; right
+  now, it fails within assert(skel) in generated code, which doesn't
+  help users much to debug the problem
+- VERSION-INFO for modules?
+- md5auth isn't initialized properly in conjunction with ARTS_SERVER
+- make it possible to use C API and C++ API together
+- FIXME: what to do about apps which are not threaded but nevertheless
+  want to use the engine?
+- gsl: rounding should be used even for unsigned conversions
+
+## MCOP Core Infrastructure
+
+- offer sampleprecise timing
+- resource management (i.e. locate resources like "samples" or "structures"
+  in a similar uniform way KDE does with KStandardDirs)
+- check why adding thousand non-running objects degrades scheduling
+  performance quite a lot
+- recursive scheduling again (with loops & cycles)
+- obsoleting: use V2 implementations even if user requests a normal
+  implementation, since they have a newer version
+- error notification for connection breaks - this would enable intelligent
+  clients to immediately know when something goes wrong, so they can terminate
+  sanely instead of crashing
+- mcopidl: use unsigned char arrays instead of strings for inline marshalled
+  data in idl files - this will fix the "maximum string length" warnings and
+  while doing this improve space and speed
+- try to clean up notification manager, code generation and _copy() _release()
+  style referencing across functions in notification and Dispatcher - the
+  alternatives seem to be even more automatic referencing magic, or freeing
+  objects only if the stack is empty (idle freeing)
+- fix generated code for struct Foo { object bar; }
+- fix fallback into higher namespaces, the following idl file should be accepted
+  module A { interface Z; module B { interface Y : Z { }; }; };
+
+- debugging: if two alternating messages are emitted, the message compression
+  doesn't work, and the user will be flooded with debugging message, the X
+  server will crash, and so on - a possible strategy would be:
+   * make an always present MCOP object which can receive confirmations from
+     artsmessage
+   * start artsmessage as usual, but tell it about the MCOP object, so that
+     artsmessage can
+	   - tell the MCOP object if it is done
+	   - query the MCOP object for the repetition count of the message
+   * queue repeated messages as long as they are still visible on screen
+
+## aRts SoundServer
+
+- export configuration interfaces from the soundserver (so that
+  you can see and change the autosuspend timeout for instance)
+- support multiple artsd instances on one computer (like multiple displays),
+  and think of a clever way to register them
+- more support for different audio input/output methods (i.e. SDL)
+- support channels != 2
+- expand capabilities of shell utils (making them eventually as powerful as
+  artscontrol, or better ;)
+- make it possible to share a cookie between multiple hosts (like storing it
+  in nfs mounted home directory)
+- make it possible for artsd to cascade audio input/output to another artsd
+- ARTS_COOKIE, OSS_DEVICE
+
+## C API / artsdsp
+
+- implement an arts_stream_flush for writing half-written data packets
+  (useful for implementing SNDCTL_DSP_POST in artsdsp)
+- move to CSL (CSL a new common sound layer, especially intended to be
+  compatible between Gnome and KDE)
+- pkgconfig file
+- it might be useful to allow clients on big endian systems to pass their
+  16bit data with their native byte order - for compatibility with older API
+  versions, its required to make this an extra parameter 
+  as an efficiency bonus, one could also make the wire representation then
+  16bit big endian, which requires support from the sound server though; its
+  not required to implement the feature, though (which is probably useful
+  for application writers on 16bit big endian machines)
+
+## GUI Support
+
+- port visual objects (beginnings are in kdemultimedia/arts/gui)
+- hbox, vbox
+- gui generation
+- hints via mcopidl
+
+## aRts Modules / Signal processing
+
+- midi recording for Brahms
+- StereoEffectStack should support reordering (and probably listing) effects
+  (maybe backport noatuns version)
+- hard disc recording
+- allow progressive loading for wave files
+- write blockwise caching (not requiring whole samples to be held in memory)
+- akai support
+- better interpolation / resampling
+- the Resampler class should do big endian and float as inputs
+- LADSPA support
+- provide a GUI for stereo_pitch_shift
+
+## kcmarts
+
+- add restart option to the control panel, so that you can restart artsd easier
+  if it crashed (it never crashes, does it ;) - close #38417 when done
+
+## artsbuilder (and runtime)
+
+- allow to give additional parameters (like names for sample files to play)
+  through .arts-map files
+- more examples (instruments, songs and such)
+- gui editing (or should is it better to write a new editor for that)
+- live editing of running structures
+- component bar where you can choose components without going through all
+  these submenus
+- property editor (like in delphi)
+- support pressing "return" in the various dialogs and close them on doing
+  that (rather than always having to click "ok" with the mouse)
+- i18n fixes
+
+## artscontrol
+
+- be able to remove midi ports                                          *KDE2.2*
+- add a mixer
+- persistent state (Arts::Environment), so that the environment
+  can be restored on next login (or per song or something like that)
+- edit .arts-map files visually
+
+## Optimization (this section contains various optimization ideas)
+
+- use no floats for adressing the fractional part in resampling but integers
+  (that will be MUCH faster)
+- use short int for i16le resampling, instead of using a long and adding
+  sign manually (faster at least on athlon)
+- tune the MCOP transfer protocol
+  * rewrite Buffer not to use vector<char> to store data, but malloc'd blocks
+  * try to write "zero allocation" invocations, that means, try not to allocate
+    memory on performing an invocation. For instance Buffers could be kept in
+	pools, and be reused for further invocations, without the need to realloc
+	another memory block
+  * try to minimize the amount of copies of data, possibly even using something
+    like sharedmem to share data between the sending and receiving buffer
+  * hardcode frequently used calls in the Arts::Object interface
+
+## Documentation / Web
+
+- improve kdoc comments everywhere
+- write incomplete sections in The aRts Handbook; improve formatting
+
+## Misc
+
+- put streamwise blocking into MCOP, see artscat.cc to read really ugly
+  source which lives without that feature
+- implement plugins that transfer non-standard datatypes such as midi events,
+  video frames, fft packets, oscilloscope views, ... (which was impossible
+  with aRts on CORBA)
+- make aRts run inside Brahms, KWave or your-favorite-other-app, to do
+  signal processing where it is needed (similar to AudioLogic Environment,
+  for instance)
+- convince other people to use aRts, so that the usefulness of universal
+  plugins written for the API increases
+- when being crazy, implement gatewaying from MCOP to DCOP, CORBA, XMLRPC
+  or whatever else might be useful
+
+## Interoperability (GNOME/C)
+
+- write a gartscontrol (in C) as native Gnome/Gtk app
+- further work on CSL
+- C language binding, based on glib
+- mcopidl code generation for C
+
+## FlowSystem changes:
+
+It would be nice if the flowsystem became more "detached" from the normal
+operation, making it ideally runnable in one or more thread dedicated for
+audio processing.
+
+Flowsystem transactions:
+
+   these group operation like: starting, stopping, connecting, disconnecting,
+   ... to transactions which will later (asynchronously) executed by the
+   flowsystem
+
+Example: problematic assertion
+
+   assert(done[i] <= samples);    /* synthschedule.cc:998 */
+
+   the problem with the assertion here is this - suppose some object reacts
+   in a way on some signal that will lead to the creation of new objects,
+   then those will get into the flowsystem, and we can't ultimately say
+   anything about how far these have been calculated so far
+
+   extremely problematic in this context are so-called call-ins, that is
+   you do calculateBlock, and during this, the dispatcher mainloop gets
+   called for some reason (I hope that this does not happen currently) -
+   if that would hypothetically happen, then there the whole flowsystem
+   could get restructured (because i.e. ordinary midi events could be
+   processed)
+
+## libartskde
+
+ * ensure that there is a pair of classes, like KAudioPlayStream and
+   KAudioRecordStream (or whatever they should be called) that can do
+   approximately what the C API can do
+
+ * don't export implementation details in the API - for instance
+   KAudio(Play|Record)Stream should probably only inherit from QObject, and
+   only "use" some aRts objects to do the actual work - that way, they can
+   be changed/modified more easily afterwards
+
+ * use Qt signals/slots as callbacks (at least as one possibility) for
+   "please produce new audio data" / "here is new audio data" - that way,
+   polling isn't necessary any longer