PlayObject-questions

[thomas.friedrichsmeier at ruhr-uni-bochum.de]

Hi!

First of all, let me warn you, that I 
really don't understand much of Arts or 
how it works internally, so some of the 
things I'm asking might not make too much 
sense.

For a game I'm writing, I was in need of a 
PlayObject that I can both loop and play 
at different rates. After spending 
literally days stumbling from stupid 
mistake to inexplicable (to me) error, I 
finally managed to create my own 
PlayObject inheriting for WavPlayObject, 
which has both mentioned capabilities. The 
coding itself was as simple as can be, 
really, but getting to understand what 
exactly had to be done and how was rather 
difficult.

Anyway, now I'm happy with what my 
PlayObject does, except for that it can 
only handle wavs. Ideally I would want to 
be able to treat all common audio formats 
the same - but don't feel like extending 
every single type of PlayObject one by 
one. What would be the place to implement 
a certain capability for all types of 
PlayObjects (except of course 
StreamObjects, where e.g. looping does not 
make any sense) and how would I go about 
it?
Do you think, it would make sense to have 
the ability to modify the playback-rate 
and to make sounds loop in "official" Arts?
I saw that there exists a 
PitchablePlayObject, but I failed to find 
out how to use it. How do you? And would 
it be possible to additionally have a 
LoopablePlayObject? How?


Let me add to this mail a few critical 
comments on the documentations-pratice of 
Arts, that I hope you will not understand 
as an insult, but rather as useful 
feedback:

I'm not exactly a programming genius and 
being a self-tought programmer with little 
experience, I'm aware that I sometimes 
wonder about stuff that is totally clear 
for most other programmers. However, I 
don't exactly feel like I'm all that slow 
at understanding, either. Trying to add 
sound to my game, however, was definitely 
one of the most frustrating experiences I 
ever had with programming.
Everything is fine as long as you can use 
the simple functions of KPlayObject and 
the like, I those won't do, however, 
useful documentation is rather rare. Ok, 
there is this introductory chapter in the 
programming KDE 2.0-book, which gives you 
a basic idea of how to approach the 
problem (but e.g. fails to tell you that 
for KDE-Applications you probably don't 
want to use a plain Arts::Dispatcher and 
call run () on it...), but when it comes 
to programming-references, there just 
doesn't exist anything useful.
On arts-project.org there's a header 
reference and an unfinished handbook for 
Arts 0.6.0 (especially the API-chapter has 
little more in it than a few sub-
headings), in the header-reference there 
is hardly a single line of explanation.
Well, many functions like play () might 
not need a lot of elaboration, but a 
simple reassuring "yes, this function 
really does what you think it does" or a 
"however despaired you are, don't mess 
with this" would have saved me a lot of 
trial-and-error, when things were not 
working the way I expected. Or what about 
a short description in each main class, 
what's it's supposed to be used for and 
ideally also how (I admit the idl-
reference is slightly better, but not 
exactly wordy, either).
I'm aware, that this documentation is 
generated from headers which in turn in 
turn are generated via mcopidl. But maybe 
then mcopidl should be given a mechanism 
that enables it to write comments into the 
headers? It would also help a lot to have 
the online-documentation up-to-date.
Perhaps I'm being a bit too negative here, 
perhaps I have not always looked in the 
right places, but I really do feel that 
the documentation is being rather 
neglected in Arts. I have more and more 
come to see that Arts really is a very 
powerful piece of software that if used 
correctly can do about anything you could 
dream of sound-wise. But also I have 
gained the (incorrect, perhaps) 
impression, that only some few persons 
(most of which are active developers of 
Arts) really know what it can do for you 
and how you get it to do that. Of course, 
a software of this complexity is not easy 
to document thoroughly, and we could all 
use some more time - but please realize 
that for some programmer from outside, who 
simply  wants to get this or that nice 
effect done, without having to dig too 
deep into the internals of Arts, it's 
really a very complex piece of software, 
too. Please realize that the same 
programmer will wonder about the use of 
functions, which may seem plain obvious, 
if you were the one to implement them (or 
even if you've simply used them once 
before). And please do give documentation 
a higher priority.

Again, I hope you'll understand this as a 
possibly not well grounded, possibly too 
harsh or unfriendly, but neither entirely 
inadequate critic.

Thanks for your time.

Thomas