Re: CoreAudio Documentation
Re: CoreAudio Documentation
- Subject: Re: CoreAudio Documentation
- From: Marc Poirier <email@hidden>
- Date: Wed, 10 Sep 2003 12:38:47 -0500 (CDT)
Hi Christian. Another message from me with ideas for the AU docs...
I'm also CCing this to the CoreAudio API listserv because I'd be curious
if anyone else might have ideas to improve my suggestions, or add to them,
or subtract from them, etc.
Someone was just reminding me about the main things that seem to be
confusing at first for most AU developer newbie, so here's a (probably not
comprehensive, but hopefully still useful) list:
The meaning of element and scope in every context:
This I would say is the #1 major source of confusion. Actually, before
defining this in every context, there needs to be a good general
description of the function and purpose of scopes and elements somewhere
in the AU docs. As it is, these are things that show up everywhere, but
the purposes are very nebulous.
Once a good general conceptual explanation is there, I think that you need
to go through the entire set of docs and, in every case where scope and
element are used for something (every property, every parameter handling
thing, etc.), explain what the scope and the element mean in that context.
Or, if it's a property where those are not used, specify clearly that they
are ignored in that context. Or, in cases where there are specific scope
or element requirements (e.g. cases where Global is the only valid scope,
0 is the only valid element, etc., that sort of thing), specify that
clearly.
Speaking as someone who has studied the AU API and SDK pretty carefully
since a while now, made many AUs, read the listserv for a long time, etc.,
I can tell you that I still feel like I don't understand what the purpose
of the scope and especially the element serve 90% of the time. I think
that I understand everything else about AU pretty well, but the
element/scope stuff is still a pretty big question mark.
Moreoever, there needs to be some decent explanation of the various
ScopeElement classes in the SDK. (ScopeElement? That's 2 confusing
things as one!). I've tried to understand them personally, but I never
really succeed... And I think that that's where some might look for
clarification on scope and element issues, but instead I think that it
only brings more confusion.
Busses, elements, channels:
Needs straight-forward overview clarification badly! Some folks think
that they need a bus for each channel. Are elements the same as busses in
these contexts? I think so, but I'm not sure. All this sort of stuff
needs clarification very much.
AUResources.r:
Please add something to the SDK docs about this helper file. Right now
there's nothing about it, only a couple of example .r files that use it,
with very minimal and cryptic comments. Almost everyone sees these
examples and gets confused about how you could be #defining RES_ID,
COMP_TYPE, VERSION, NAME, etc. repeatedly in the same file (it's because
AUResources.r #undefs them, but with no explanation of that, most folks
are simply confused). This is a simple task, but there really just needs
to be some item in the SDK docs that says:
"AUResources.r is your friend. It makes it easy to generate the required
resources for your Audio Units. By simply #defining a few values and then
#including AUResources.r after that, you will be able to get the necessary
'thng', 'dlle', and 'STR ' resources easily. And AUResources.r also will
#undef all of those macros that it relies on, so that then you can #define
them again right after an #include "AUResources.r" line because they are
now #undefed, so you can #define them again and #include AUResources.r
again in order to generate another set of AU resources, since you may have
more than one AU in your Component (like an audio and GUI AU together, for
example)."
Something like that, it would ease so much newbie confusion.
AUResources.r is a very handy convenience, but as it is now, it is
probably doing more harm then good just by being completely cryptic and
undocumented.
The audio and GUI are separate AUs:
Lots of newbies don't realize this basic fact, so I think it probably
needs more emphasis in the docs.
CoreFoundation for AU developers:
Finally, I think that it would be really great if there was a little
"CoreFoundation Primer For AU" or some such thing. There are a lot of
people whose only programming work is plugins, and some folks coming from
Windows trying to just port to Mac, and they are completely unfamiliar
with CoreFoundation, and diving into the whole world of that is just as
big a deal as the task of diving into the world of AU. I think that it's
a good idea for anyone using CF to read the docs personally, but it still
would do a world of good if there was just a little primer of
what-you-need-to-know-for-AU for CF stuff in the docs. I think that it
can turn away a number of folks coming from other plugin API, because they
get C strings and C arrays in those other APIs, but CoreFoundation is
alien to them.
Marc
_______________________________________________
coreaudio-api mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/coreaudio-api
Do not post admin requests to the list. They will be ignored.