Mocha Help

Mocha

Installation

Quick Tour

Benes (Expressions)

Features

Advanced Features

Keyboard and Mouse Shortcuts

Misc

Mocha

from Technosis

by Wes Cherry (wesc@technosis.com)

Mocha allows you to generate nifty shifting images.. Starting with simple mathematical expression (called a bene, a mix of gene and bean, pronounced "bean"), you can investigate the visual impact of variable time, the inflence of sounds, colors, and seed images to the images created by Mocha. Evolve your visualizations purposfully, exploring th effects of various changes to the bene.. Watch as images evolve organically, both by your explicit changes or on your behalf by Mocha in breed mode

Mocha is Freeware. It may not be resold for profit without my consent.  It may be used for performance use in clubs, raves or parties.  I'd appreciate it if you would let me know if you do so.

I welcome email with suggestions and bugs.  And of course, if you find cool benes, please send them to me.  I may include them in future releases.

Installation

Run MochaSetup.exe.  Specify a directory to install Mocha.  If you install to the WinAmp plugin directory, then you may use Choose the Mocha within WinAmp by pressing Ctrl-K in WinAmp. Start it by pressing Ctrl-Shift-K.

If you wish to run WinAmp in standalone mode, just run Mocha.exe. Depending upon your soundcard, audio CDs played in your CDROM may or may not work. 

If you don't already have WinAmp get it from www.winamp.com

Quick Tour

Mocha makes it easy to generate interesting images which react to sound as either a WinAmp plugin or as a standalone program. 

main.jpg

This is the main Mocha window -- currently it is displaying the bene "Unstable Energy", one of the built-in benes submitted by a Mocha user.   Benes, a play on the words Gene and Bean and are merely mathematical expressions which get evaluated for each pixel in the window.  Don't worry, you don't need to know anything about math to use Mocha. 

From here you can breed new bene based upon this bene by clicking in the mocha window.   This causes the bene to mutate.  Most of the time the mutations aren't interesting, but sometimes they are.  If you don't like the mutation, just Undo with Ctrl-Z.  If you wish to breed a bene, you can also use Breed Mode. 

breed.jpg

Breed Mode gives you multiple children that are mutations surrounding the current bene.   If you like one, just click on it and it becomes the new parent.

Mocha also comes with a number of built-in benes, many (and most of the interesting ones) of them were submitted to Technosis by Mocha users.  

browser.jpg

From the Bene Browser window, you can select a built in bene.  By right-clicking on the bene browser window you can also change the sort order of  the benes or   change what is displayed in the bene browser.  Also you can associate songs with a particular bene (WinAmp plugin only).  This will make Mocha chose a particular bene when a song plays in WinAmp.

So what are benes?  Benes are mathematical expressions.  Here's the expression for the Unstable Energy bene shown above.

 fmla.gif (3656 bytes)

You can edit the bene expression here and make changes directly.  Most of   the best built-in benes were created by directly editing the mathematical expression, though some good ones have been found thru breeding.

Benes (Expressions) Syntax

Benes are mathematical expressions which are evaluated for each pixel in the image. These expressions may involve the x or y coordinate of the image, the current frame or even the current mouse position. Benes may also use built in functions and best of all, respond to sound.

Starting with the simple bene:

y

will generate a vertical wash of grays going from black at the top to white at the bottom. (by default 0=black and 255=white). To enter this bene, open up the Bene Input Window with Ctrl-F, type in y (or select it from the variables dropdown) and press Ok.

Benes can also involve the variable t. In this case the image is evaluated successively creating an animated "movie". For example, the bene

y+t

will cause the wash of grays to scroll upwards.

Now throw in a function. The bene

sin(y+t)

will sinusoid of grays to scroll upwards.

Don't worry about generating benes by hand. Mocha comes with many good built in Benes and it's Breed Mode makes it easy to evolve good benes (in fact many of the built in benes were bred rather than designed).

Since Mocha has to evaluate the bene for each pixel in the image Mocha is very computationally intensive. To run well it should be run on at least a 486 or better computer. Benes involving t in particular look much better on a fast 486 or a Pentium computer.  Mocha takes advantage of multi-processor machines for greatly improved performance (a 2 CPU machine yield approx 80% faster frame rates)

Variables

x x position of current pixel
y y position of current pixel
t the current frame number
xm the current mouse x position
ym the current mouse y position

Constants

X The X extent of the image
Y The Y extent of the image

User Defined Variables

You may define your own variables which act like functions (they get re-evaluated for each pixel).  User defined variables must be defined preceding their use in the bene.  They must be separated with commas.  For example

foo=3*x+4/sin(y),
foo+8

is equivelent to the bene

3*x+4/sin(y)+8

Operators

The following operaters are supported by Mocha.

+ Plus
- Minus (binary & unary)
* Multiplication
/ Division
% Modulo
< Less Than
<= Less Than or Equal
> Greater Than
>= Greater Than or Equal
<> Not Equal
== Equal
&& Logical And
|| Logical Or
& Binary And
| Binary Or
^ Binary Xor
! Unary Logical Not
~ Unary Binary Negation
<< Binary Shift Left
>> Binary Shift Right
? : Ternary operator -- (x ? 44 : 33) evaluates to 44 if x <> is nonzero else evaluates to 33)
[,] Array operator -- indexes into the source bitmap at pixel [x,y]. 
{,} Previous image operator -- indexes into the previously generated frame at pixel x,y
Note, for the first frame:  If the bene uses the [,] operator the previous frame is initialized to the source image.  
If not, then the previous frame is initialized to all zeros.

Functions

sin(x) period =256, range = 0..255
cos(x) period =256, range = 0..255
tan(x) period =256, range = 0..255^2
asin(x) inverse sin of x
acos(x) inverse cos of x
atan(x) inverse tan of x
dsin(x) decayed sinusoidal
theta(x,y) returns angle (0..255) of vector from center of image to x,y
rad(x,y) returns radius of vector from center of image to x,y
saw(x) sawtooth function, period = 128, range = 0..255
tri(x) triangle function, period = 256, range = 0..255
decay(x) decay function = int(exp(-i/64)*255)
decay2(x) steeper decay ~= decay(255-decay(x))
decay3(x) even steeper decay ~= decay(256-decay(255-decay(x)))
exp(x) exp(x/10)
abs(x) abs value of x
rand(x) range = 0..x
sqrt(x) square root of x
peg(x) pegs x to 0..255 (best applied to the result of an bene)
snd(x) sound waveform at x (0..255)
xrot(x,y,theta) computes x position for point x,y rotated about the center theta degrees (tip: use user defined variables to define xr=xrot(x,y,t) and then use xr where you would normally use x in a bene)
yrot(x,y,theta) computes y position for point x,y rotated about the center theta degrees.  (tip: use user defined variables to define yr=yrot(x,y,t) and then use yr where you would normally use y in a bene)
sndl(x) left channel of sound waveform at x (0..255)
sndr(x) right channel of soudn waveform at x (0..255)
vol(x) sound volume at x (0..255)
bass(x) bass - low pass filter of sound waveform at x (0..255)
lopass(x,o) lopass - low pass filter of sound waveform at x (0..255) where o is approximately the cut-off frequency (0..32)
fft(x) fast fourier transform of sound waveform (0..255)
pal(x,offs) specifies which built in palette to use, rotated by offs.   offs is an optional argument.  See palette documentation.

Any of these functions may be plotted by using an bene of the form:

fn(x)==255-y ? 255 : 0 

thus to plot a sine wave you would use the bene:

sin(x)==255-y ? 255 : 0

Palettes

You can also specify the palette that is used for displaying the image. The pixel value computed with the benes described above specifies an index of 0 to 255 into the palette. The Red, Green and Blue components of the palette are specified separately using assignments to the variables r,g and b. When palette benes are evaluated x is used to indicate the current palette index being computed. Thus the default palette of a gray wash is specified via

r=x
g=x
b=x

If you wanted a blue wash you would specify the palette with

r=0
g=0
b=x

You may also use the Hue, Saturation, Lightness (HSL) color model to specify color. It is often much easier to create a good palette using HSL. H specifies the hue (0..255 map to Red-Yellow-Green-Cyan-Blue-Magenta). S is color saturation (0..255) and L is lightness (0..255 map to black-white). A nice rainbow swash can be specified by:

h=x
s=255
l=128

Palettes may also be specified using assignments to p. Use the pal(x, offs) function when using p. The first argument to pal specifies the index into an array of predefined palettes (currently about 30). offs specifies the offset whithin the palette (0..255). Thus

p=pal(13,t)

will rotate palette 13.

The second argument (offs) is optional. 

p=pal(13)

will display just palette 13 with no rotation.

Bene Browser

The Bene Browser window allows you to view the built-in benes.  Select File/Open Bene... or press Ctrl-O. 

To select a bene in the Bene Browser window, click on it.  You may also bring up a context menu by right clicking with the mouse.   From that menu you may delete unwanted benes.

Bene Input Window

The Bene Input window is invoked via File/Enter Bene Expresion... or Ctrl-F. See the Benes Topic for more information of Bene expression syntax.

Breed Mode

Breed Mode allows you to generate multiple mutations of the current bene. These mutations, also called children are displayed around the parent bene. Clicking on one of the children makes it the new parent.

You can change the mutation rate by selecting one of the 3 mutation rates available in the options menu.

Saving Images

Mocha can save the current image out as a bitmap or GIF. Choose File/Save Image... and set the file format in the save dialog.

Mocha can also save animated GIFs or AVIs.  Choose File/Save Animated AVI/GIF...   You will be prompted for a filename, number of seconds, frame rate as well as compression format.

Viewing Options

Mocha has a number of options to customize its display.

Increase Scale (Up) Increases the image size (more detail, slower bene evalutation)
Decrease Scale (Down) Decreases the image size (less detail, faster bene evalutation)
Stretch to Window (Ctrl-W) Stretches the current image to the size of the window.
Kaleidoscope (Ctrl-K) Mirror images so it looks like a kaleidoscope. (Turn off Stretch to window).
Full Screen (Ctrl-U) Sizes the Mocha window to full screen.
Direct Draw (Ctrl-D) Sets Mocha to use Direct Draw full screen.  Performance may be dramatically increased in DirectDraw mode.

 

DirectDraw

Mocha now supports Direct Draw.   Performance may be dramatically increased in DirectDraw mode.  Select the desired DirectDraw resolution from the View/Direct Draw Settings menu item.  Since Mocha evaluates benes assuming a 256x256 bitmap there is no advantage to using higher resolution settings unless you have Stretch to Window turned off.

You can select whether or not Mocha blends bene transitions in DirectDraw mode.  Selecting this option may  slow down DirectDraw rendering.

Bene Database

Mocha comes with a built-in database of cool benes, many of the submitted by Mocha users. Open the bene browser window by selecting File/Open Bene...

You can save your own benes by selecting File/Save Bene...

If you find a cool bene, be sure to send it to me by clicking the Send button in the Save Bene dialog

AutoMutate

AutoMutate, when enabled will automatically mutate the current bene at specified intervals.  It also allows you to reset the bene to a built-in bene.  Also, when running as a WinAmp plugin it can reset to a built in bene when a song begins. Additionally mocha can load a random source image from the same directory as the currently loaded source image. To set this up, choose File/Load Source Image and pick a file from a directory.

Bene-Song Associations

Mocha allows you to associate a bene with one or more songs in a WinAmp playlist.   Whenever WinAmp plays that song Mocha will switch to the associated bene.  To assoicate a bene select File/Song Associations/Associate Bene with current Song.   Note that you have to Save the bene for the association to "stick".   To delete an association, select it from the same dropdown.

You may also add associations from within the Bene Browser by right clicking on a bene and selecting Song Associations/Associate Bene with current Song.

If more than one bene is associated with a particular bene then Mocha will randomly choose a bene when the song begins.

Auto Load of Images

Mocha will auto load images when a bene changes or WinAmp moves to a new song.   Upon song change in WinAmp, mocha will search for the following files in the same directory as the song playing:  cover256.jpg, cover256.bmp, cover.jpg and cover.bmp.   If Mocha finds any of these files it will load them automatically.  Note that your bene must involve an image for you to see it.  TIP:  Right click in the bene browser and select Sort Ascending/By Type to see all the built in benes which use images.

Master/Slave Mode

Master/Slave mode allows you to control Mocha on a remote machine. It could be useful in performance environments where you could compose an expression on one machine (Master) and then shoot it over to a display only machine (Slave).

To set it up, you must have both computers networked.   Select Options/Master Slave Settings on both machines.  On the master machine, enter the machine name and click master.  Just click Slave on the slave machine.

Press Ctrl-Enter on the Master machine to shoot the expression over to the Slave machine.

Display Frame Rate

Choose View/Display Frame Rate to display the number of frames per second evaluated by Mocha.

Disassembly

Choose File/Disassemble write the assembly code of the current bene. Mocha will tell you the filename it generates. Since this is primarly a debugging feature for me it doesn't prompt for a filename.

Keyboard Shortcuts

Ctrl-C Copy current bene and image to the clipboard
Ctrl-V Paste bene
Ctrl-F Toggle bene expression window
Ctrl-Z Undo
Return Reset current bene to a random good parent
BackSpace Undo
Space Mutate bene
Ctrl-B Toggle Breed Mode.
Ctrl-W Stretches the current image to the size of the window.
Ctrl-K Kaleidoscope mode.
Ctrl-U Sizes the Mocha window to full screen.
Ctrl-D Toggles DirectDraw (fullscreen)
Ctrl-M Toggles Menu Bar display.
Ctrl-1 Toggle display of  frame rate
Right Arrow Increase Scale
Left Arrow Decrease Scale
Ctrl-O Open Bene Database
Ctrl-S Save Bene in Database
Ctrl-Enter Send image to Slave machine (Master/Slave mode)
< Play previous song in Winamp
> Play next song in WinAmp
/ Pause song in WinAmp
Up Arrow Increase volume in WinAmp
Down Arrow Decrease volume in WinAmp

Note that except for Ctrl-Enter, shortcuts may be entered without the Ctrl key depressed.

Mouse Shortcuts

Left Click Mutates current bene
Right Click Resets to a random good parent
Mouse Wheel Towards User Mutate current bene
Mouse Wheel Away From User Undo
Middle Click Toggle Direct Draw Mode

Revision History

3.991 - 22 Jun 2K1   

3.99 - 07 Dec 2K   

3.98 -  9 Feb 2K

3.97 -  9 Feb 2K

3.96 -  10 Jan 2K

3.95 - 5 Dec 1999

3.9 - 25 Oct 1999

3.8 - 14 Sep 1999

3.7 - 20 Aug 1999

3.6 - Released only in beta

3.5 - 22 Jun 1999

3.4 - 18 Jun 1999

3.3 - 8 Jun 1999

3.2a - 4 Jun 1999

3.2 - 1 Jun 1999

3.1 - 5/5/99

3.0a - 4/18/99

3.0 - 4/18/99

Ver 2.2 ?? Jan 99

Ver 2.1 - 2 Dec 98

Ver 2.0a - 10 Nov 98

Ver 2.0: - 1 Oct 98

ToDo list

List of possible future features.  I welcome suggestions    

Version 3.x

Version 4.0