spurtg - v0.4.2, 2001.12.31 - http://prj.softpixel.com/spurtg/ softpixel's ``ultimate'' realtime graphics generation software -------------------------------------------------------------- ----------------- Table of Contents ----------------- 1.0 Introduction to spurtg 1.1 Long-term goals 1.2 This release 1.3 History 1.4 Authors / contact information 2.0 Using spurtg 2.1 System requirements 2.2 How to compile spurtg 2.3 How to run spurtg 2.4 How to create show configurations for spurtg 2.5 How to write effects for spurtg and maintain main spurtg source 3.0 Usage tips 3.1 Profiling 4.0 Glossary --------------------------- 1.0 Introduction to spurtg --------------------------- spurtg is an opensource (GPL) software package that renders realtime graphics based on input streamed from the soundcard. It has been used in the past in a live musical performance environment (see 1.3: History). -------------------- 1.1 Long-term goals -------------------- * High speed * Low latency * Many effects, mostly of the demoscene variety * Realtime effect switching and parameter adjustment * Crossplatform support (linux fb, linux x11, windows directx) ----------------- 1.2 This Release ----------------- Numerous usability improvements (config syntax checking, more proper error handling), additional effects modules, as well as refinements and optimizations of existing ones. More modularizaion in preparation for future enhancements. Additional documentation, especially regarding effects module programming. ------------ 1.3 History ------------ This program was written originally to draw graphics in realtime on a stage-wide projection screen, to music being played by the group ``pragmatic illusion'' (http://pi.softpixel.com/) for the Hilliard Davidson High School Variety Show 2000 and later completely rewritten for the 2001 show, then prepared for release as version 0.3.0. ---------------------------------- 1.4 Authors / contact information ---------------------------------- * Chris Wright (cwright@softpixel.com) * Steve Mokris (smokris@softpixel.com) * There is a general discussion / support mailinglist: * http://softpixel.com/mojo/ ----------------- 2.0 Using spurtg ----------------- ------------------------ 2.1 System requirements ------------------------ * linux, kernel 2.2.x or newer (anything with framebuffer support) * framebuffer support enabled in the kernel * see http://www.linuxdoc.org/HOWTO/Framebuffer-HOWTO.html * dot.conf - a configuration file parser * available at http://www.azzit.de/dotconf/ * tested with version 1.0.2 -------------------------- 2.2 How to compile spurtg -------------------------- * compile and install dot.conf * edit Makefile.config * make * please contact us if you have difficulties (or success... :^) ) ---------------------- 2.3 How to run spurtg ---------------------- * set graphics mode (using fbset, unless you're using vesafb). currently 16/24/32bit modes work. for example: * fbset 320x240 -depth 16 * ./spurtg ------------------------------------------------- 2.4 How to create show configurations for spurtg ------------------------------------------------- * Look at the included show.conf for an example of what a conf file looks like. * In the beginning, load all relevant modules with the AddModEffects command * AddModEffects general * Define the presets, which are strings of any length. use the keyword Presets, followed with all the presets used. * Presets preset1 preset2 * Tell it which preset to start on with PresetInitial * PresetInitial preset2 * Define the number of virtual surfaces to allocate with the NumSurfaces keyword * NumSurfaces 2 * Then, define the presets. Open each preset with a , and end it with a , like HTML / XML. * * * Inside a preset, you may want a Key keyword to activate it, or a Jump keyword to exit it. Key is followed with the keyboard letter used to activate it (currently only supports alphanumeric and punctuation). Jump is followed by the number of frames to wait until the jump, and the destination preset. * Key x * Jump 16 preset2 * Inside a preset, you will specify effects as well. Effects start with the Effect keyword, and have several parameters. The first two are the input and output surface numbers, the third is the effect to perform, and anything after that is passed as a parameter to the effect plugin. Surface 0 is the surface that is displayed. * Effect 0 0 starfield * Effect 0 0 fade --rate 3 * Effects are executed sequentially for each frame, moving down the list. It therefore is useful to create different `rendering pipelines' by inputting from and outputting to differing surfaces. For example: * Effect 1 1 fade --rate 3 * Effect 1 1 starfield * Effect 1 0 copy * Effect 0 0 scope This should display a scope (with no trails) on top of a starfield with trails. -------------------------------------------------------------------- 2.5 How to write effects for spurtg and maintain main spurtg source -------------------------------------------------------------------- Please see the file doc/programmingOverview --------------- 3.0 Usage tips --------------- -------------- 3.1 Profiling -------------- We have included a show file called profile.conf. This will iterate through the effects modules and report their speed. Run it like this: ./spurtg -s profile.conf -d After you see static for about 5 seconds, press q. It would be very helpful to us if you could email the entire resulting spurtg.debug file to prj-spurtg@softpixel.com If you have the time, trying this at a few different resolutions and color depths would be great :^) . Graphics resolution/depth is output to the spurtg.debug file, so you would just need to make sure to rename them as you go. ------------- 4.0 Glossary ------------- * effect * a function that takes sound and/or graphics data as input, and produces graphics data as output. * effect instance * every time an effect is referenced in a preset, a new instance of that effect is created. instances can maintain their own independent data. therefore, for example, you could run two starfields simultaneously within the same preset, without the data being confused. * a reference to the same effect in two different presets will generate two instances. * eventually there will be a method for allowing insances to share data. * effect module * a shared object (.so) containing one or more effects, placed in the modules/lib/effects directory. * fini * destructor routine, present in all subsystems and modules * in trying to figure out whether to call it 'deinitialize' or 'uninitialize', i found that 'fini' is used internally by GCC (and others?), and, hey, it's a catchy name. * pronounced 'phineas', like the character in 'a separate peace' :^) * see also 'init' * init * constructor routine, present in all subsystems and modules * see also 'fini' * module * a shared object, built in the modules/ tree. * see also 'effect module' * preset * a 'pipeline' describing how effects are linked together. found in the show config file. * show config file * contains several presets. these should be fairly system-independent. * system config file * contains information describing parameters of the current system. this would eventually be placed in /etc or the like.