CAUGui documentation

1.0

Safari proof

intro

CAUGui - CoreGraphics AudioUnit Graphical User Interface

The source code documented here is a graphics framework / SDK intended to assist building AudioUnit view components. They are based on Carbon APIs and make it quite easy to create fancy user interfaces for audio effects and MusicDevices.

To make use of them, it's recommended to know what an AudioUnit is (see Audio on MacOS X), what C/C++ is and how creating audio plugins in general works.

If you find mistakes in the documentation or bugs in the code, please let me know.

To obtain the latest version, go to u-he CAUGui page

concept

The concept behind CAUGui isn't easily explained but offers a lot of ease.

First of all, it extends the Apple provided example code, namely the AudioUnit View base classes, without need to modify them. CAUGui just adds on a way of handling customizable CarbonControls. You can decide how much of it you'd like to add, like occasionaly using just one control or two, or if you want to build your whole user interface upon CAUGui. To some extend, CAUGui Controls can be mixed with Aqua CarbonControls.

Secondly, CAUGui is designed to keep away stress from the developer. It offers functionality to take care for its objects by itself so the developer can add more and more controls to the GUI without having to change the code in many places. There is no need to track controls over their lifetime, like maintaining pointers, observing control value changes and the like. CAUGui manager objects (CAUGuiMan) and Carbon notification schemes built in CoreAudio do this for you.

Third, to a very convenient extend, visual value representation and user interaction are independent beings. CAUGuiGraphic objects encapsulate functionality of how to paint and what to draw from a given parameter value while CAUGuiControl objects (CAUGuiCtrl) manage the translation from user input (mousing) to value changes. A set of different Graphics types and Controls can be freely combined to avoid redundancy and enforce reusability.

Last but not least, everything profits from the convenient AudioUnit parameter scheme: Values are visualized in their correct ranges, indexed parameters with strings attached automatically end up in PopUpMenues etc.

Another goodie of all this is, since you can forget about every object as an individual, you can build little factory classes that create groups of controls.

install

• Make sure you have the latest Apple Developer Tools installed. Dec 02 Dev Tools are minimum

• copy folder CAUGuiSDK to /Developer/Examples/CoreAudio/AudioUnits/

• double click CAUGuiDemo.pbproj (ProjectBuilder launches) and build example AudioUnit

use

Basically what you need to do for a CAUGui driven AU View is this:

1.) make sure an object of type CAUGuiMan is member of your view class

2.) edit CAUGuiConfig.h to make tell it about some things like your Component's Bundle Identifier

3.) During instantiation of the view, inside CreateUI():

• Create your CAUGuiMan

• Create CAUGuiPane objects and add them to the CAUGuiMan

• Create CAUGuiGraphic objects and add them to the CAUGuiMan

• Create AUVParameters

• Create CAUGuiControl objects (CAUGuiCtrl) with CAUGuiGraphics and AUVParameters attached and add them to the CAUGuiMan

• In between, make use of eRects and their little layout helpmatic

4.) On view destruction, destroy the CAUGuiMan

For an example, look at the CAUGuiDemo project inside the SDK

doxygen

This documentation has been generated automatically using doxygen. There are several ways to tweak this documentation (download and install doxygen for that).

• modify the file CAUGuiSDK/docfiles/stylesheet.css (i.e. set body background to #FFFFFF for printable version)

• edit the configuration file (CAUGuiSDK/docfiles/doxyconfig)

• open the Terminal

• type "cd /Developer/Examples/CoreAudio/AudioUnits/CAUGuiSDK/docfiles/", (as always, without quotes...) press Enter

• type "doxygen doxyconfig" to rebuild the docs

• use "doxygen doxy_complete_config" to add documentation of all base classes in AUPublic, which is comfortable because then you have links for every know class definition, inheritance diagrams etc. (and it looks nice!)

license

You can use CAUGui as an example for whatever you want and extend it by any modification you find useful. If you use it or parts of it in one of your incredible products, give me credits in the liner notes and - if that's not asked too much for - send me a fully licensed copy of it.

If you insist on giving back more, send me an email (urs@u-he.com).

Now to the worse part of the license: If you find bugs, you have to report them or you shall not use this software.

The worst part: If you modify this software to work with compositing windows, you have to publish or send in the changes that exactly had been necessary to do this.

You may under no circumstances ever pretend that any code from within CAUGui as published by me has been done by you, unless it really is contributed by you. You may furtherly not sell this SDK or parts of it (which doesn't mean your products inherit from this, this is not intended to be a profit killer license). In other words, the copyright remains mine while you are allowed to use the stuff in your own software (which however may be a commercial product) under the terms of this license.

acknowledgements

Many people had been very helpful during creation of this stuff, to name just a few:

Marc Poirier, Airy Andre, Chris Reed, Art Gillespie, Robert Grant, Franck Stauffer, Bill Stewart, Michael Hopkins, Eric Schlegel, Niko Gerteis, Sascha Kujawa and probably a dozen more to whom I apologize for having neglected here.

Thanks, boys!

;) Urs

(c) 2002 - 2003 by Urs Heckmann www.u-he.com