pixelTANGO visual performance software suite Release 0.1.1 January 2005
<ben@ekran.org>, <franz@sat.qc.ca>
Copyright (c) 2004 SAT
http://www.tot.sat.qc.ca

developed and/or packaged by the SAT Video Group
for the SAT Software Development Kit


LICENSE: See COPYING


TABLE OF CONTENTS

1.0 About pixelTANGO
  1.1 What is pixelTANGO ?
  1.2 Technical Information
  1.3 Hardware Specifications
  1.4 Software Specifications

2.0 Installing pixelTANGO
  2.0 Downloads
  2.2 Mac OS X
  2.3 Linux
  2.4 Microsoft Windows

3.0 Using pixelTANGO
  3.1 pixelTANGO Abstractions
  3.2 Utilization
  3.3 Optimizing performance

4.0 Troubleshooting
  4.1 Contact Us
  4.2 pixelTANGO
  4.3 pure data, GEM
  4.4 Known Bugs



1.0 ABOUT pixelTANGO

1.1 What is pixelTANGO ?

  pixelTANGO is on open-source software for real-time visual
  performance. pixelTANGO can be used by VJs, artists for example to
  create dynamic visuals for shows, artistic performance, and so on.
  The core of the suite is using pure data (pd) and GEM. Pd is
  a real-time graphical programming environment for audio and
  graphical processing. It resembles the Max/MSP system but is much
  simpler and more portable; both pd and Max/MSP have been programmed
  by Miller Puckette. Using Mark Dank's GEM package, Pd can be used
  for simultaneous computer animation and computer audio.
  pixelTANGO consist of some externals for pd, added functionality
  for GEM and patches (and sub patches) for pd.
  pixelTANGO is a multi-layer compositing software, each layer can
  display images coming from different input : static image, live
  input or movies. Special effects (FX) can be applied to these
  images. Different layers are available like 3D objects, text,
  feedback and so on.
  Using the graphical environment of pd, pixelTANGO can be
  customized to suit the artist needs, the number of layers
  is only limited by your CPU and/or GPU (GPU stands for Graphic
  Processing Unit, in other words a 3D card).
  pixelTANGO is cross-platform, as is pd and GEM, the development
  platform is Mac OS X, thanks to the Altivec unit on the Power PC,
  but it should run on Linux and Windows. The Linux version needs
  some tweaking and development before being ready to be used, and
  the windows version is untested at this moment. 
  
  
  
1.1 Technical information for pixelTANGO


1.2 Hardware specifications

	* Mac OS X
		- G4 1 Ghz or more, G5 is recommended
		- 256 MB of RAM, 512 is highly recommended
		
	* PC : Linux or MS Windows
		- P4, Pentium M, Athlon XP or Athlon 64
		- 256 MB of RAM, 512 is highly recommended
		

1.3 Software specifications

	* pure data 0.37
		- http://www-crca.ucsd.edu/~msp/software.html
		- pd installer for Mac OS X and MS Windows :
		  http://at.or.at/hans/pd/installers.html

	* Tcl/Tk

	* GEM 0.90
	  - http://gem.iem.at/
	  - Gem for Mac OS X : http://taproot.dyndns.org/~cgc/ and
      http://taproot.dyndns.org/~cgc/downloads/index.html

	* pixelTANGO 0.1
		- http://www.tot.sat.qc.ca/eng/pixeltango.html
		
2.0 INSTALLING pixelTANGO

	pixelTANGO includes a number of subfolders :
	  pixelTANGO/
	    abstractions
            externals
      	    fonts
            help
            Example-Patches

	In the future pT will be available as an installer, but currently
	it can only be installed manually.

	Requirements:
	You must have a working installation of PD.

	First you must decompress the archive on your hard drive, then follow
	the following instructions to install and run pixelTANGO.
	
2.1 Downloads

	Download, according to your plateform, pixelTANGO, Gem 0.90 and the latest
	pd version 0.37.1, 0.38 should work fine but it is still a beta version.
	Follow the links on the pixelTANGO web page to find the appropriate versions.

2.2 Mac OS X

	Installation :

	Install pure data using PureData-0.37.1_MacOSX-(0.2.5)-TclTk8.4dmg, double click
	the package installer once the image is mounted. pd will install in /usr/local/bin
	and all the extra and the documentation will be installed in /usr/local/lib/pd.

	Decompress gem-bin-0.90.0_G?.tgz (where ? is 3, 4 or 5 corresponding to the G3, G4
	or G5, so download the version corresponding to your CPU, G4 will work for the G5),
	then copy Gem.pd_darwin to /usr/local/lib/pd/extra/, overwrite the existing version
	if needed.	

	Decompress the pixeTANGO archive, copy the pixelTANGO directory to your pd
	installation folder, rename the folder to pixelTANGO if necessary as the name could
	be pixelTANGO-0.1.1. Usually the pd directory is /usr/local/lib/pd


	Launching pixelTANGO :

	In terminal start pd with appropriate options. Something like:
	   pd -rt -path /usr/local/lib/pd/pixelTANGO/abstractions -path
     /usr/local/lib/pd/pixelTANGO/externals -helppath
     /usr/local/lib/pd/pixelTANGO/help -lib Gem:zexy:popup -noaudio

	Then open an example patch located in /usr/local/lib/pd/pixelTANGO/Example-Patches.

2.3 Linux version

	Installation :

	Compile and install pure data 0.37.1 or superior, compile Gem 0.90 and copy the
	Gem.pd_linux file to the extra folder of your pure data installation, overwrite
	previous version if needed.

	Decompress pixelTANGO archive. Copy the pixelTANGO directory to your pd installation
	folder. Usually /usr/local/lib/pd


	Launching pixelTANGO :

	In terminal start pd with appropriate options. Something like:
	   pd -rt -path /usr/local/lib/pd/pixelTANGO/abstractions -path
     /usr/local/lib/pd/pixelTANGO/externals -helppath
     /usr/local/lib/pd/pixelTANGO/help -lib Gem

	Then open an example patch located in /usr/local/lib/pd/pixelTANGO/Example-Patches.

2.4 Microsoft Windows

	Installation :

	Install pure data 0.37.1, an installer is available, follow the link on the
	pixelTANGO website.

	Decompress gem-bin-doc-0.90.0.zip, and copy Gem.dll to the extra folder in
	your Pure Data directory, usually C:\Program Files\Pure Data\extra

	Decompress pixelTANGO.zip in the Pure Data folder, rename it to pixelTANGO if
	necessary (it could be pixelTANGOv0.1 or pixelTANGOv0.1.x).

	Copy the pixelTANGO externals (in the folder pixelTANGO/externals)
	entry.dll and popup.dll to the pd extra folder, usually
	"C:\Program Files\Pure Data\extra".
	
	Create a file named pixelTANGO.bat in the Pure Data folder, and type the following 
	"bin\pd.exe" -font 10 -path "pixelTANGO\abstractions" -helppath
	"pixelTANGO\help" -lib iem_t3_lib -lib zexy -lib iemlib1 -lib iemlib2
	-lib Gem -lib cyclone -listdev %1 %2 %3 %4 %5 %6 %7 %8 %9


	Launching pixelTANGO :

	Launch pure data using thepixelTANGO.bat, then open a pixelTANGO
	example patch from the "C:\Program Files\Pure Data\pixelTANGO/Example-Patches" folder.
	

3.0 USING pixelTANGO

3.1 pixelTANGO Abstractions

  pixelTANGO is a set of abstractions and patches that make use of pd/Gem for
  creating visuals in a live performance setting. Of course it can be used
  for many other things and provides an interface to use the power of pd/Gem
  with a less-steep learning curve.


  General abstractions that affects all layers.
  * pt.window : windows creation, resolution selection, ...
    - Fullscreen : Expand render window to full-screen on primary display.
      Only has effect before creating render window
    - FSAA(6): Turn on Full-Scene Anti-Aliasing. Only has effect before
      creating render window.
    -	Window : Create the render window and start rendering
    - Light : Turn on lighting
    - X_offset & Y_offset : distance from upper-left corner of primary display
      to upper-left corner of render window. This function only has an effect
      before the render window has been created.
    - Resolution (in pixels) of render window
    - Red/Green/Blue sliders : select background color

	* pt.light : lighting control
	  - White sliders : X, Y and Z position of light
	  - Red/Green/Blue : Amount of R/G/B in light
	  - White : Overall brightness of light (changes R, G & B)
	  - Reset : Reset all controls to defaults w/ interpolation.

    You must turn lighting on in the pt.window controls. You can have up to 8
    lights in a patch, but the rendering will suffer a lot. The light limitations
    comes from your graphic card, this will improve in future GPU.


	* pt.interp : interpolation control, affects all interpolated controls in a
    patch :
		-	None : Use no interpolation. Controls pass through.
		- Linear : Use normal linear interpolation (default value)
		- Low-Pass : Use DSP lop~ to smooth out linear interpolation
		- Smoothness : Controls how smooth the controls are. Left for faster/rougher
		  and right for slower/smoother

  A pt layer is defined by three aspects. First a layer has a header (pt.layer)
  and a footer (pt.video or pt.model etc..). The footer defines the type of layer.
  The second characteristic of a pt layer is that there are two sets of connections
  that go from module to module. We can call these connections buses. The left bus
  is the graphics bus, it passes Gem data for drawing graphics. The right bus is
  the control bus, it bases control data which allows the various pt modules to
  communicate. 

	Layer Header, every layer needs this abstractions at the top of every pt layer.
	The creation argument (render order) starts in the back with 1 and goes forward
	up to 100. The back-most layer , render order == 1 , is turned on by default.
	All other layers are off by default.

	Every layer in pixelTANGO needs a header (Modules at the top of layers) :
		- pt.video : Defines a 2D video layer
	  - pt.text  : Defines a text layer
		- pt.model : Defines a 3D model (OBJ) layer

	Every layer in pixelTANGO needs a footer (Modules at the bottom of layers),
	it associate the texture and the geometry using all the modifiers used in
	the layer.

	Modifiers, they go between the header and the footers, they are used to scale,
	squeeze, rotate, inputting text, selecting media files and so on.
	* Entry modifiers :
	  - pt.entry : Text entry for text layers
	      + Size  : Use size to adjust text size
	      + Clear : Clear input box
	      + Send  : Validate text
	  
	  - pt.file  : File selection for movies, models etc...
	  
	  - pt.live  : live DV/firewire video input
	      + live : you can select capture dimensions
	  
	* Other modifiers
	  - pt.source : texture source switcher (image, movie, network stream)
	  
	  - pt.loop   : looper for movie files
	  		+ reset     : reset settings
	  		+ in_point  : select in range
	  		+ out_point : select out range
	  		+ play_rate : select play rate
	  		+ loop      : select loop mode (forward, reverse, ping-pong)
	  
  * Pixel modifiers
	  - pt.fader   : RGBA color fading for layer
	      + white slider : control alpha transparency
	      + Red/Green/Blue slider : control R/G/B color
	      
	  - pt.layerfx : Pixel effects for layer textures
	  		+ fx_amount : control FX force
	  		+ fx : select FX (None, edge, emboss, gain, motion blur, negative,
	  		       normalize, posterize, random dot, roll, scanline.

	* Geometry modifiers
	  - pt.translate : Control 3D translation of layer
	  - pt.rotate    : control 3D rotation of layer
	  - pt.scale     : control scale of layer
	  - pt.squeeze   : control independent XYZ scale of layer;


3.2 Utilization

3.2.1 Customization
	First, we invite you to see the example provided : Two-Layer-Example.pd or
	Typical-Example.pd. So you can see how the differents abstractions are tied
	together.
	
	Now you can custom pixelTANGO to your own needs, for example if you need 
	more lights, you just need to add a new pt.light to the patch or copy
	an existing one.
	
	If you want to use another video layer, copy an existing one.

3.2.2 Utilizaztion

	Utilization is pretty straightforward, slider control size, color and so on,
	file selection permit you to select the file you want to use, drop-down boxes
	are used to select the FX used or the loop mode that you need.
	

3.3 Optimizing performance

3.3.1 Mac version
	- for movies use YUV codec
	- use DV encoded movies
	- reduce size of movies


3.3.2 Linux version
	- reduce size of movies

3.3.3 Linux version
	- reduce size of movies


4.0 TROUBLESHOOTING

4.1 Contact Us

  Please report any difficulties, comments and suggestions you have on the
  video@tot.sat.qc.ca mailing list :
	http://listes.sat.qc.ca/mailman/listinfo/video

4.2 pixelTANGO


4.3 pure data, GEM


4.4 Known Bugs

  In some cases changing the "name" of popup via the "name" message will
  mess up your patch.  :( 
  Solution : Don't change the name of "popup" dynamically, use the
  creation argument only!

  Entry does not filter out special characters, including "," ";" etc
  that have special meaning in PD. This means you can type "; hello man"
  in entry and it will send "man" to the "hello" receive!!
  Solution: Escape ";" and "," like so: "you can type this\, it is ok\;"

  A bug in tcl/tk may cause PD to crash if you select text too quickly.
  Solution: Use the "clear" button to clear contents of entry box.

  On Mac OS X, if you install pure data 0.37.1 with TclTk 8.5, pd is broken, you cannot
  open or create any patches, install pure data again with TclTK 8.4.

  error: counter: no method for 'reset'
	On Windows the Gem library must be loaded before the cyclone library,
	they both implement a counter object, the one included in the cyclone
	library is not compatible with pixelTANGO