
Scivi is a visualization plugin for XMMS.

This plugin uses 3D Accelerated hardware, but is not actually 3D.

=====================
Hardware requirements:

You need a FAST 3D accelerated video card with T&L support
and properly installed driver.

Scivi should work with NVidia GeForce2 MX family and
better cards nicely.

=====================
Software requirements:

	GL version 1.3 or 1.2
		1.3 is preferred.

		tested with NVIDIA GeForce2 MX hardware with
		driver version 44.96 with GLX 1.3 and 1.2
		"compatibility mode"

	XMMS-1.2 - tested with 1.2.8, GTK-1.2.10, GLIB-1.2.10

	X Server - tested with XFree86-4.3.0
	GCC - tested with gcc-3.2.3, gcc-2.95.3

============
Installation:

	./configure
	make
	su
	make install

That should work. If you want to install plugin to your ~/.xmms/Plugins/
directory, just copy src/.libs/scivi.so there. And don`f forget about
presets.

"make install" will copy *.scv files from presets/ directory to
${datadir}/scivi/presets 

============
Key Bindings:
	space       - pause/play
	PgUp/PgDn   - previous/next playlist entry
	Left/Right  - seek -/+ 5 sec

	r/R  - decrease/increase 'osc_resolution'
	o/O  - decrease/increase 'osc_type
	w/W  - show wireframe coordinate grid
	p/P  - switch to previos/next preset
	f/F  - reload presets
	s    - switch fullscreen mode (NOT AVAILABLE YET)
	v    - switch to root-window (Note: there is no way
	       to switch back, change preset, etc. yet)
	
==================
Configuration File:

This is .ini-style text file.

Section: main

Key: presets_dir - sets directory list where your presets are
     searched. This is a colon-separated list of
     directories

     ~/.scivi/presets/ and ${datadir}/scivi/presets/
    are added here automatically.

Key: fps_limit_method - method the fps will be limited
Key: max_fps - set maximum frames per second. 
     Note: this may be inaccurate. Default: 50
Key: width  - set window width. Default: 640
Key: height - set window height. Default: 480
Key: tex_width - internal resolution width.
     should be a power of 2. Default: 512
Key: tex_height - internal resolution height.
     should be a power of 2. Default: 512

Note thet there is a Scivi configuration dialog now.

============================
Additional Configure Options:

	--with-flex=FLEX
	--with-bison=BISON
		These may be necessary if you edit .l or .y files.
		Probably developers only.

======================
Preset code: Basics:

preset is a .ini style file. Empty lines or lines started with '#'
are ignored. Note that ';' is not comment char now.

Section: general
Key: name - preset's name
Key: author - preset's author
Key: email - author's e-mail address
Key: uuid - preset's unique identifier. Optional. Is used to
     restore current preset after reloading. Someday
     may be used to specify in preset code
     'next' preset. Or something else.
Key: rating - unused for now

Sections: initialization, per-frame, per-pixel, post-frame
contains raw "code" for presets. White spaces are ignored.

Note: code IS case-sensetive
WARGING: semicolon at the end of statement is required

===================
Preset code: Arrays:

Arrays must be declared first with setarray()
"virtual" function. The best place for this is
an initialization section.

setarray(name, dim1 ...) - this function interpreted
only on a compile phase and while executing does *nothing*.

"name" is a plain array name, without quotes.
Further parameters define array dimension size.

For example, setarray(myarr, 2, 2); will define
"myarr" two-dimensional array with 2 columns and
2 rows.

You may define as much dimensions as you want with
necessary positive integers. But remember: Very Large
arrays can eat up all available memory!

To set or get value stored in array, use C syntax -
name[dim1][... In example above myarr[1][1] will
address element with indices 1 and 1, and
myarr[0][0] - is a "first" element.

Please note: array indices are zero-based.

================================
Preset code: Branching and Loops:

As in C:

  if (expr)
     stmt;

  if (expr)
     stmt;
  else
     stmt;

  if (expr){
     stmt1;
     stmt2;
     ....
  }

etc.

  while (expr)
     stmt;

  do
     stmt;
  while (expr);

  for(expr1;expr2;expr3)
     stmt;

etc.

======================
Preset code: Operators:
    > < >= <= == !=
    = += -= /= *= + - / * % | & ^ || &&
    unary - ! ~ 
    ( )

As in C.

Note: there is *NO* operators like |= &= ++ -- etc.

======================
Preset code: Constants:
    PI      pi ~= 3.14159265358979323846
    E       e ~= 2.7182818284590452354
    SQRT2   sqrt(2) ~= 1.41421356237309504880

    POINTS,
    LINES,
    LINE_STRIP,
    LINE_LOOP,
    TRIANGLES,
    TRIANGLE_STRIP,
    TRIANGLE_FAN,
    QUADS,
    QUAD_STRIP,
    POLYGON - these all correspong to GL constants,
              and must be passed to Begin() function.
              They define what type of objects will
              be drawn with Vertex() function calls.
              For more info see glBegin man page.

Note: these are not constants actually, you may assign new values to them

======================
Preset code: Variables:

	starttime - time when scivi was started. may be inaccurate
	time - time in seconds since scivi start
	frame - rendered frames count

	width, height
	left, right
	top, bottom

	i_zoom	- set initial zoom value: >1 zooms in
	i_rot	- rotation >0 clockwise
	i_cx, i_cy - center of stretch/rotation.
			0:0 -- center; >0 - up/right; <0 - left/bottom
	i_dx, i_dy - constant movement
	i_sx, i_sy - stretch amount
	i_ox, i_oy - oscilloscope center
	i_decay - <1 more decay

	i_env	- background color. use i_envR, i_envG, i_envB, i_envA for R,G,B,A, range: 0.0...1.0
	i_osc	- as above but oscilloscope color
	
	zoom	- as above but sets per frame values
	rot
	cx,	cy
	dx, dy
	sx, sy
	ox, oy
	decay

	ppix_x - as above but sets per pixel values 
	ppix_y
	ppix_cx
	ppix_cy
	ppix_dx
	ppix_dy
	ppix_sx
	ppix_sy
	ppix_zoom
	ppix_rot
	ppix_rad - distance from center of screen to a point
	ppix_ang - angle

	envX	- per frame background color (X stands for R, G, B, A)
	oscX	- oscilloscope color (X stands for R, G, B, A)

	osc_type - oscilloscope type
	osc_look - 0 for point, 1 for lines
	osc_look_param1 - line width or point size
	osc_look_param2 - depends on osc_type
	osc_additive - additive waveform drawing
	osc_resolution - waveform smoothness
	osc_angle
	osc_size
	osc_amplitude

	tex_wrap - set to 1 to enable texture wrapping
	tex_invert - set to 1 to enable inverted colors mode
	
	opt_wireframe - set to 1 to see texture mapping coordinates.
		useful for preset "debugging"

	beat	- 1.0 if beat detected 0.0 otherwise
	bass	- 0.0...1.0 bass value
	mid	
	treble
	bass_max - 0.0...1.0 maximal bass value seen some frames ago
	mid_max
	treble_max
	bass_att - 0.0...1.0 attenuated bass value
	mid_att
	treble_att

	mousex,
	mousey   - mouse poiner coordinates

	mousebtn1,
	mousebtn2,
	mousebtn3 - indicates if mouse buttons 1, 2 or 3 is down

Notes:
 - in initialization section of a preset "i_" prefix is optional.
 - in per-pixel section of a preset "ppix_" prefix is optional.
 - user variables are available within current preset only

======================
Preset code: Functions:
	reset() - reset all variables to _internal_ initial values

	random() - returns random value from 0.0 to 1.0

	int(f) - convert to integer, truncate fractional part
	abs(f) - absolute value
	sin(f)
	cos(f)
	tan(f)
	asin(f)
	acos(f)
	atan(f)
	sqr(f)
	sqrt(f)
	log(f)
	log10(f)
	sign(f) - sign of 'f', values: 1.0, 0.0, -1.0

	pow(f1,f2) - raise f1 to the power of f2 

	min(f1,f2) - minimum of 2
	max(f1,f2) - maximum of 2
	vlength(x, y) - (x,y) vertex length. Same as
                        sqrt(sqr(x)+sqr(y))
	vangle(x, y) - angle between (x,y) and (1,0) vertices.

	data_osc(channel, sample),
	data_freq(channel, band) - get oscillator or frequency
                   data. sample should be between 0 and 511 inclusive,
                   and band between 0 and 255, inclusive.

	Begin(type) - start drawing of type "type".
	End() - end drawing. These calls can NOT be nested!

	Vertex(x,y) - put vertex
	Color(r,g,b,a) - set vertex color

Note: Begin(), End(), Vertex(), Color() functions available only in
post-frame section!

=====================
Preset code: Examples:

Don't forget to take a look at examples in presets directory!

============
Happy coding!
http://xmms-scivi.sourceforge.net/
http://sourceforge.net/projects/xmms-scivi/
Vitaly V. Bursov <vitalyb@mail333.com>
