Documentation
 
Basic
     Introduction
   FAQ
   Troubleshooting
   How G-Force Works
   License Agreement
   Contact

 
Advanced
     Standalone Use
   Customizing
   Scripting
   Config Programming
   Version History

  Config Programming  
        A "config" is a file that contains plain-text data intended to be read-in by G-Force. Configs contain a non-ordered list of named strings, similar to a Windows INI file and can be viewed or edited by using any text editor. Depending on the role a config file is intended to play, G-Force looks for specifically named items and uses them in accordance with the role of that config. For example, when a WaveShape config defines a string named "Pen", it's understood that the string paired to it defines how darkly lines are drawn. If you want to learn the config file syntax, it will help to have some familiarity with programming and/or script writing. Many users submit their configs so that they can be redistributed—over half of the configs that come with G-Force and WhiteCap were made by users just like you.

Syntax

      The config file syntax is straightforward and is nothing more than a flat, non-ordered, list of key-value pairs (ie, a dictionary). It's an ASCII plain-text file (ie, not any other kind of file, such as an RTF file), with 1 to 4 character case-sensitive "key" identifiers followed by an equal sign, followed by the key's value. If the value isn't a number (a leading '-' and/or '.' is ok), then it should be in quotes. All whitespace outside of quotes is ignored, and both kinds of C-style comments are processed. An example of valid syntax:
    X0=".5 + sin( .3 * t )"          // This is a comment
    Y0="123"
    Pen=.8
    Ans=-42
    ALFA="1 / exp( c1 ^ 2 )"      /*     This is another comment */
    Vers=260

Submitting Your Configs

      If you'd like a config you made yourself to permanently become part of G-Force, please contact us. From there, it'll be evaluated and checked for possible problems or faults. If you choose to redistribute your configs on your own and do something hazardous in them, you may cause other versions of G-Force to crash or have other problems. Further, sending in your configs centralizes the entire process, guaranteeing your work to appear as soon as possible.

Documented Configs

      Below is a list of configs included with G-Force that are documented (try using a file search in your OS to find them). In other words, if you open a config file in a text editor or word processor, then you'll find information that will allow you to make and edit your own configs. Try looking at them in order listed, and be aware that many other configs contain documentation/comments added by the author that created them. If you see a config in G-Force you really like, don't be afraid to open it in order to see how it's doing it.
  1. G-Force/ColorMaps/ColorWheel.txt
  2. G-Force/ColorMaps/Clear Blue Water.txt
  3. G-Force/FlowFields/Linear Spread.txt
  4. G-Force/WaveShapes/Rotating Corridor.txt
  5. G-Force/Particles/Spinners.txt
  6. G-Force/Particles (Non-Auto)/Default Sprite.txt
  7. G-Force/FlowField Unions/Birth Cone.txt

Be Patient

      The prefs file is read when G-Force starts and overwritten when G-Force exits, so any changes made to the prefs file while G-Force is running will be overwritten. Note: some media players internally do not exit G-Force even if you turn G-Force off via a media player command or control (so you must exit the media player in order to cause G-Force to exit and write its pref file).

Testing Your Configs

      When you're ready to test your config, you have to tell G-Force to load a fresh copy it from the disk. Otherwise, if you switch to a config you've been editing, G-Force won't load your changes (because it's using a cached copy). The 'U' key will reload the currently displayed configs. In other words, when you save changes to a config, press 'U' to make G-Force load a fresh copy from disk.


Config/Language Reference


Common

abs(x) absolute value
exp(x) e to the x
log(x) natural logarithm
sqr(x) square of x
sqrt(x) square root of x
sin(x) sine (x is in radians)
cos(x) cosine (x is in radians)
tan(x) tangent (x is in radians)
asin(x) arcsine (range is -PI/2 to PI/2)
acos(x) arccosine (range is 0 to PI)
atan(x) arctangent (range is -PI/2 to PI/2)
atan2(x) arctangent (range is 0 to PI)


Logical/Discrete

pos(x) x if x > 0 and 0 otherwise
sgn(x) 1 if x > 0 and -1 otherwise
clip(x) 0 when x < 0, 1 when x > 1, and x when 0 <= x <= 1
sqwv(x) 1 if abs(x) <= 1.0 and 0 otherwise


Miscellaneous

rnd(x) a random real number from 0 to x
trnc(x) everything to the right of the decimal point in x is dropped
flor(x) the largest integer that is also less than x (ex, flor(3.2) == 3, flor(-2.7) == -3 )
wrap(x) x - flor( x ) (ex: wrap( .3 ) == .3, wrap( 4.12 ) == .12, wrap( - 2.7 ) == .3 )
flip(x) sawtooth that passes thru ...(-3, -1), (-1, 1), (-1, -1), (1,1), (1, -1), ...
trwv(x) triangle-shaped wave passing through (0,0), (1,1), (2,0) and repeats in both directions along the x axis
seed(x) seeds the random number generator based on the bits of x, returns x


Operators

+ - Add/Subtract
* / Multiply/Divide
% Modulo or "the integer remainder when A is divided by B" (ex, 8 % 4 == 0, 11 % 3 == 2)
^ raised to the power


Audio Access

mag() Accesses samples of the current audio
fft() Accesses the frequency transform/spectrum of the current audio
BASS A single scalar value that approximates the overall beat


Globals

PI 3.141592653
NUM_S_STEPS The number of times the X, Y, and C expressions are evaluated per sample (ie, per frame)
NUM_FFT_BINS The number of bins/resolution composing fft()
NUM_SAMPLE_BINS The number of values composing mag()
HEIGHT, WIDTH The output frame dimensions (in pixels). Because the frame size can change at any time, these globals should be treated as time dependent when used inside a WaveShape config.
X_EXTENTS, Y_EXTENTS The four points (+/- X _EXTENTS, +/- Y_EXTENTS) always map to the corners of the output frame. Because the frame size can change at any time, these globals should be treated as time dependent when used inside a WaveShape config. When a FlowField or WaveShape does not have a forced 1:1 aspect (ie, if Aspc=0), then both these globals are therefore 1.
 
 
 
 

© 2004 SoundSpectrum, Inc.