HACKING info for you machine developers

[David O'Toole]

This is the HACKING file that should have come with the tarball earlier
this week.
When I was falling asleep last night I realized that the reason someone
knew that 
mc_get_type_by_name() could return NULL is that someone was trying to
use core.c 
to create machines! You don't have to do that... it should be creating a
menu for you.

Of course I can't blame anyone for not seeing it, because I forgot to
release any 
documentation on how to use 0.92.2 to actually test your machines. Some
info is below.

In other news, Luka Frelih, who has for some time expressed interest in
helping out
coordinate machine developers' efforts, will be doing that as admin of  
octalmachines.sourceforge.net. If you're writing a machine and you're
interested in 
using Octalmachines CVS repository, Luka will be the man to talk to
(once it is fully 
set up.)

--------------- HACKING -----------
The 0.92.2 release is mostly for testing out any new machines and
experimenting with 
them. Here's how:

1. Write or copy-and-tweak a new machine, using the OX_API as described
in
the manual (/doc in the tarball, or the html doc link at the octal
homepage.)

Let's call the new machine's source "mytest.c".

If you have any questions about the API after reading the docs, feel
free to 
post them to the mailing list. 

2. Compile it into a shared library like this: 

    $ gcc -Wall -shared mytest.c -o mytest.so

Make sure the resulting *.SO file goes into the octal directory for now.

3. Start up Octal with the release dir as working directory. 

    $ cd release
    $ octal

Look for messages in the terminal about the machines it found. Make sure
yours is in there. If you are running esd you will have to either kill
it
or wait till it lets go of /dev/dsp. 

4. Create your machine. If you right-click on the background of the
machine window,
you should get a pop up menu with each machine type displayed in it.
Click to create
a new machine. (It will be right on top of another one for now, make
sure to move 
it with the mouse.) 

GENERATORS:
Once the mytest machine is created, you need to route its output signal
to hear what 
it does. Use shift-drag to form connections between machines. (Hold down
shift, left
click on signal source, drag to signal sink, release mouse button,
release shift.) 
Do the same again to disconnect (that'll be improved later.) Connect
your machine to
[master] which is the output.  

EFFECTS:
The same, except you'll need to connect the output of a generator to
your own machine's
input as well. If all else fails, use the squaregen machine (it sucks
but it does make
sound!!) 

5. Play with parameters. Right click on your machine to get the context
menu; then 
click on "control box". You should get a little window with some slider
widgets in it.
The sliders are set up to send parameter changes to your machine
instance, and also
to request text feedback from your ox_desc(). You can open multiple
control boxes
at once if you would like to fool with multiple machines.

6. Report bugs, make suggestions, have fun!  

CURRENT ISSUES BEING FIXED:

- only sliders work. more widgets are coming out this weekend.
- only mono signals work (!) because some of the mixer is test code.
that is being
fixed real soon (it's easy.) 
- there are minor sound glitches in the mixer... occasionally I've been
able to get weird buzzing sounds even when there are no machines. I
think this is a problem with somebody's frame counter falling behind the
main mixer's frame counter... won't be hard to fix. 

Look for 0.92.3 this weekend. Please speak up if you have any problems
(or successes :-) with
testing a machine. 

--
@@@ david o'toole
@@@ address@hidden
@@@ www.gnu.org/software/octal