|
You can customize G-Force by editing its preferences file, editing its "boot" file, or by writing your own scripts. The preferences file, the boot file, and all script files are plain-text files and end with ".txt". If you edit these files, then you must resave them as plain-text. Otherwise, G-Force can crash while trying to processing them. For example, Mac OS X's TextEdit saves files as Rich Text Format (.rtf) by default—instead, designate your file as plain-text (in the Format menu), and save it as a .txt file (alternatively, just use any good shareware text editor). On Windows, Notepad is an effective and convenient plain-text editor. Whatever text editor you do use, it's recommended that you disable line wrapping for readability and in order to prevent mistaking wrapped lines for new lines.
In general, you should avoid editing the pref file and boot file when possible. You can instead change commonly altered settings via key commands (assuming your media player supports keystrokes for plugins, press 'H' to display an on-screen list of key commands). An example of when you would edit the prefs file would be if you media player didn't support keystrokes (ex, Sonique), or if you wanted to edit a setting not accessible via key commands. Finally, if you have the option to edit either the pref file or the boot file in order to achieve your goal, it's always preferable to edit the prefs file rather than the boot file. A mistake in the prefs file can always be corrected by deleting the prefs file (and a factory prefs file will be written in its place), but a mistake in the boot file can only be corrected by replacing it with the original boot file (ie. reinstallation).
- The Boot File
The "boot" file is read-in and executed when G-Force first starts-up (to find it, you can search for "boot.txt"). This file is a sequence of commands that initialize (or "bootstraps") G-Force and prepares it for normal operation (the term "boot" originates from the phrase "to pull up from the bootstraps", from the earliest days of computers, reflecting that computers start with absolutely nothing when they're turned on). Unlike the preferences file, the boot file is never altered or rewritten by G-Force—it's only read-in (and executed) when G-Force first starts-up. The boot file is like a boot disk for your computer—without it, G-Force cannot operate normally. It's recommended that you study the boot file because it contains detailed comments and serves as a good example of the G-Force script/command language.
- The Preferences File
The G-Force preferences file is a "config" file, meaning it's a plain-text file containing a simple list of values (in no particular order). Its file format is intended to be learned extremely quickly and edited easily using any text editor—the format is described in the config programming section. The purpose of the prefs file is to allow various user variables (ex, window position, full screen resolution, visual reactivity settings) to persist from each time G-Force is run to the next. Since G-Force only writes/updates the prefs file when it exits, you will have to run and exit G-Force at least once before you'll be able find a G-Force prefs file—search for "G-Force Prefs" on your system to see where G-Force stores its prefs file (it's location varies depending on your media player, OS, and user permissions). If you edit the prefs file while G-Force is running, your changes will be overwritten when G-Force exits (so you should save your changes when G-Force is not running). Finally, if G-Force behaves strangely after you edit the prefs file, it's likely you inadvertently inserted an error. You can simply delete the prefs file (when G-Force isn't running) and a new "factory" prefs file will be created the next time G-Force runs. The following is a list of all the parameters found in the G-Force prefs file:
G-Force and WhiteCap Common Prefs |
FSrt |
PREF_FFT_BIN_START |
When G-Force is operating as a plugin for a media player, the media player repeatedly passes an array of values corresponding to a fft (fourier transform) of the "current" audio. For cosmetic purposes, this FSrt defines how many values or "bins" of this array to throw away from the low-frequency side (the first several values are usually erratic since the lowest frequencies become increasingly more difficult to analyze). Hence, increasing FSrt will cause the frequency window of fft(0..1) to shift to the right (towards the high frequency end of the fft).
Note: this parameter is not used in stand-alone or engine/export mode because G-Force uses its own built-in fourier transformer and uses the parameters set by SetFFTParams() (see the boot.txt file). |
FRge |
PREF_FFT_BIN_RANGE |
When G-Force is operating as a plugin for a media player, the media player repeatedly passes an array of values corresponding to a fft (fourier transform) of the "current" audio. For cosmetic purposes multiple adjacent elements (or "bins") are averaged into one G-Force bin. This parameter specifies just how many media player fft bins are averaged per G-Force bin.
Therefore, this affects how wide of a frequency band the elements of fft(0..1) span. As FRge increases, the frequency band fft(0..1) increases. For example, if FRge is large then fft(0) may be the magnitude of the frequencies from 100 to 500 Hz, while if FRge is smaller then fft(0) may be the magnitude of the frequencies from 100 to 200 Hz.
Note: this parameter is not used in stand-alone or engine/export mode because G-Force uses its own built-in fourier transformer and uses the parameters set by SetFFTParams() (see the boot.txt file). |
FFde |
PREF_FFT_FADE_AWAY |
The higher this value, the slower each fft element (or "bin") will fall/drift back to zero after it's been excited. Likewise, as this number approaches zero, the faster fft bins will fall to zero. Slower music tends to look better if this value is 30-50% higher than the factory value because frequency "tonals" will accumulate more and will form more defined peaks. |
FSmo |
PREF_FFT_SMOOTH |
As this value increases, the smoothing of fft(0..1) increases proportionally (ie, peaks and valleys will be less jagged). Approximately doubling/halving this number will double/half the amount of smoothing. |
FNum |
PREF_FFT_NUM_BINS |
This defines how many values/elements are in fft(0..1). As FNum increases, the frequency spectrum will be divided up into more "bins" (a "bin" is defined as the average value of a small sub-section of a frequency spectrum--just like how a bin or pail collects a footprint of rain and never a point). In a config file, you can access 'FNum' by using NUM_FFT_BINS. See the documentation in the example configs, especially the documentation of the Stps parameter in "Rotating Corridor". |
FMap |
PREF_FFT_MAP_FCN |
This is a function that maps the input/raw fft array (from either a media player or from the built-in fourier transformer while in stand-alone or engine/export mode) to the array that is accessed by fft(0..1). An "array" here simply means a sequence of values. The purpose of this function is to provide an arbitrary means to change the fft spectrum ultimately seen by the user such that it's as visually appealing and responsive as possible. The fft spectrum that comes from media players or G-Force's built-in fourier transformer is "raw", meaning that it would be very visually unappealing if was used directly.
There are two values accessible from inside the function, w and x. The value w can be thought of a vector that goes from 0 to 1, the 0 corresponding to the low-frequency side of the fft array, 1 corresponding to the high-frequency side of the fft array. The value x can be thought of the raw/input fft array. For example, a proportional mapping of the raw fft array with a 100% increasing to 200% weighting on the higher frequencies would be:
".1 * x * ( w + 1 )" |
PSmo |
PREF_PCM_SMOOTH |
As this value increases, the more mag(0..1) is smoothed (ie, peaks and valleys will be less jagged). Approximately doubling/halving this number will double/half the amount of smoothing. |
PNum |
PREF_PCM_NUM_BINS |
Similar to FNum, this parameter specifies how many elements are in each sound sample (that is, how many elements make up mag(0..1)). PCM stands for "pulse code modulation" which just means a sequence of amplitude values that correspond to the position of a recording membrane. A "sample" is slang for a sequence of amplitude values that form a short clip of audio—in other words a "sample" is slang for a recorded audio segment. 'PNum' defines how many steps is in mag(0..1). In a config file, you can access PNum with the global variable NUM_SAMPLE_BINS. |
PScl |
PREF_PCM_SCALE |
This sets the scale factor to the PCM level (ie. the oscilloscope-looking output of WaveShapes). You would adjust the PCM scale if the PCM level (and only the PCM level) was too large or too small, and adjusting this value will have no effect on the FFT level whatsoever (ie, PScl will scale mag() and only mag()). Normally, you should scale the FFT level in tandem with the PCM level (by changing the response scale (below), not the PCM scale). |
RScl |
PREF_RESPONSE_SCALE |
The "response scale" will scale the *output* of the FFT map function (ie, it scales the output of PREF_FFT_MAP_FCN) as well as the PCM input. An analogy would be a "line" source connected to a preamp, going to an equalizer, going to another amplifier. The preamp scale turns up/down the pre-amp, PREF_FFT_MAP_FCN specifies the equalizer's settings, and the response scale turns up/down the second amp. In general, you'll only want to adjust the preamp scale if line-in level is abnormally high or low (ex, you have a poor mic that only gives your a fraction of the signal). Most of the time, you'll want to adjust the response scale to suit your personal visual tastes. For the PCM data (ie. the oscilloscope-looking output accessed by mag(0..1)), since there is no FFT mapping function (in the analogy, no equalizer), the preamp and the response scale are interchangeable (because having no FFT remapper makes them communitive).
In summary:
- mag(0..1) = RScl * SScl * PScl * mag_raw(0..1)
- fft(0..1) = RScl * PREF_FFT_MAP_FCN( w = 0..1, x = SScl * fft_raw(0..1) )
|
SScl |
PREF_PREAMP_SCALE |
The "preamp scale" will scale the *input* of the FFT map function (ie, it scales the raw FFT input before it's transformed by PREF_FFT_MAP_FCN) as well as the PCM input—see above. In general, you should only adjust the preamp scale if line-in level is abnormally high or low (ex, you have a poor mic that only gives your a fraction of the signal). |
FS_M |
PREF_FULLSCREEN_DEVICE |
This specifies the display device that G-Force will attempt to use for full screen mode. The value is such that the main/primary device is 0, the next is 1, the next is 2, and so on. If this value is -1 (ie, SS_HOST_DISPLAY_DEVICE), then the display device that G-Force will attempt to use for full screen mode will be whatever the display device currently hosting the G-Force window. Note: this is not available for all media players (because most media players don't allow a plugin to request a specific display device for full scree mode). |
FS_D |
PREF_FULLSCREEN_DEPTH |
This is the color depth mode G-Force will use when it attempts to enter full screen mode (it can only be 8, 16, or 32). In G-Force, 8 and 32 bit mode will produce the same color-quality frames, but 32 will be slower because 4 times the pixel data is moved around (ie, 1 byte per pixel vs. 4 bytes per pixel). The only time you should use 32 for FS_D in G-Force is if your OS improperly supports 8 bit mode (which, sadly, is common). To discover which fullscreen mode is best for your setup, try comparing the average frame rate under different fullscreen depth modes in order. Pressing SHIFT M will step through the available full screen depth modes. Note: because G-Force tries to maintain a specified frame rate (see the 'FPS' pref), to conduct a frame rate comparison you should set the 'FPS' pref to a value G-Force won't be able to achieve (ex. 100). |
FS_X
FS_Y |
PREF_FULLSCREEN_X
PREF_FULLSCREEN_Y |
This determines the display resolution mode G-Force will use when it attempts to enter fullscreen mode. You can step through the available the fullscreen modes by repeatedly pressing the "Switch full screen mode" key (the 'M' key). Because G-Force's frame rate is proportional to how many pixels it must draw, frame rate is low as the total number of pixels increases (ie, as the product of these two values increases). You can use the MaxX and MaxY prefs to restrict G-Force's active frame size, allowing you to increase frame rate for any particular fullscreen resolution. |
MaxX
MaxY |
PREF_MAX_SIZE_X
PREF_MAX_SIZE_Y |
These set a limit on the pixel dimensions of the "active" output frame size. For example, by restricting MaxY to, say, 600, you will see G-Force "letterbox" once its vertical height exceeds 600. Or, suppose 1024x768 fullscreen mode causes unacceptably low frame rates on your setup. You could set MaxY to, say, 500, and you will have higher frame rates in that same fullscreen mode (because G-Force has fewer pixels to render). |
PDbl |
PREF_PIXEL_DOUBLING |
If non-zero, G-Force will internally render frames half the size of the current output frame size and double them when they're drawn to the screen. The end result is that G-Force only has to render one quarter of the pixels (decreasing CPU load), but the graphic output will look granular or "pixelated". The performance increase from using pixel doubling will vary based on your setup's OS and graphics hardware. |
MBlt |
PREF_FORCE_MULTIBLT |
When the output device is in 16 or 32 bit color mode and an overlay is present (ex, album cover art or floating white text), the overlay must ultimately be combined with each G-Force [8 bit] output frame (note that all overlays are 32 bit color). G-Force has two options: (a) copy the G-Force frame to the 16/32 bit OS frame buffer and then copy (or "blt") the overlay over it, or (b) copy the G-Force frame into a temp 16/32 bit buffer, blt the overlay over it, and then blt the temp buffer to the OS frame buffer. Option (a) is obviously preferable, but unless the OS frame buffer is triple buffered, frame "tearing" or flickering can occur (where only part of the frame appears). By default, if G-Force detects an environment such that option (a) will cause frame tearing or flickering, then G-Force will employ option (b) instead (typically resulting in a noticeable performance penalty).
Currently, only Mac OS X implements triple buffering in non-fullscreen mode (in other words, G-Force uses option (a) only if you're running under Mac OS X and running in non-fullscreen mode). If, however, you don't mind frame tearing or have reason to suspect you have hardware that performs triple buffering, then set PREF_FORCE_MULTIBLT to a non-zero value. Doing this will force G-Force to always use option (a), regardless of the detected environment. |
NoBo |
PREF_BORDERLESS_WINDOW |
If non-zero, G-Force will try to make its window borderless. Note: this is not supported for all media players and/or OSes. |
FWin |
PREF_FLOATING_WINDOW |
If non-zero, G-Force will try to "float" its window above other windows. Note: this is not supported for all media players and/or OSes. |
ArtX
ArtY |
PREF_MAX_COVER_ART_X
PREF_MAX_COVER_ART_Y |
If album cover art is available, these parameters limit the cover art's image dimensions to a specific pixel size. If one (or both) of the cover art's dimensions exceeds these limits, the cover art is scaled down such that the new size is inside these limits. |
FPS |
PREF_DESIRED_FRAME_RATE |
G-Force will attempt to maintain a frame rate that matches the value specified in this pref. If G-Force has a frame rate below what you specify, it's because (a) your system isn't fast enough to achieve the desired frame rate for the current frame dimensions, or (b) the host media player is electing not to have G-Force draw as often as possible. At this point, only decreasing the frame size, exiting other applications, or switching media players can increase frame rate.
Note that some media players only call a visual plugin a maximum number of times per second (and nothing can be done to change that other than abandon that media player). Also note that it takes a few seconds for G-Force to stabilize on the desired frame rate when a step-change in CPU load occurs (ex, window size change, multiple overlays added at once). |
LBst |
PREF_LINE_BOOST |
This value of this parameter is added to the line thickness of all drawn lines. Higher resolution users typically use 1 or 2 so that lines are more visible. On G-Force, note that increasing line thickness can cause more frequent color saturation (depending on the current FlowField), causing the entire screen to be flooded with an excess of foreground color. |
TTxt |
PREF_TRACK_TEXT_AUTO |
If this value is non-zero, track text (and album art, if available) will be automatically displayed when the current song changes. If this value is zero, track text and album cover art will never appear automatically. |
TDur |
PREF_TRACK_TEXT_DURATION |
This is the number of seconds track text (and album cover art, if available) will remain visible after it appears. By default, track text (and album cover art) will appear when a new track begins or when 'T' is pressed. |
TFnt |
PREF_TEXT_FONT |
This specifies the default font name used when track information text or Sprite text is drawn. Note that text Sprites can override this by specifying their own TFnt (in their config file)—this allows you to make specific text sprites appear in a specifc way. |
TSze |
PREF_TEXT_SIZE |
This specifies the default text size used when track information text or Sprite text is drawn. Note that text Sprites can override this by specifying their own TSze (in their config file)—this allows you to make specific text sprites appear in a specifc way. |
A_in |
PREF_AUDIO_INPUT_SOURCE |
This specifies the audio input source to be visualized. A value of zero represents the default audio input device/source. This pref is only used when G-Force is running in stand-alone mode. |
UpCk |
PREF_CHECK_FOR_UPDATES |
This specifies how often, in days, G-Force will anonymously check soundspectrum.com for updates when it starts up. If a newer version of G-Force exists (than the version currently running), you will be notified that a new version is available. If you wish to disable this feature, set this pref to 0. |
Vers |
PREF_PREFS_VERSION |
This stores the version of the prefs file and is how G-Force can identify an out-of-date prefs file (if this value is below the "compatible" version number, G-Force will use the "factory" pref values specified in the boot file). You will never normally need to edit this value (and using an invalid or out-of-date prefs file with the "current" G-Force version number could cause G-Force to crash or operate improperly). |
wTop
wLft
wBot
wRgt |
N/A |
This stores the position of the G-Force window in globsal screen coordinates. Note that when G-Force runs under certain media players, these parameters aren't used because the host media player manages the rectangle size and position, not G-Force. |
G-Force Only Prefs |
CInt |
PREF_COLORMAP_INTERVAL |
This expresses the number of seconds to stay on the current ColorMap before transitioning to the next random ColorMap (when the ColorMap slideshow mode is on). |
WInt |
PREF_WAVESHAPE_INTERVAL |
This expresses the number of seconds to stay on the current WaveShape before transitioning to the next random WaveShape (when the WaveShape slideshow mode is on). |
FInt |
PREF_FLOWFIELD_INTERVAL |
This expresses the number of seconds to stay on the current FlowField before transitioning to the next random FlowField (when the FlowField slideshow mode is on). |
SInt |
PREF_SPRITE_INTERVAL |
This expresses the number of seconds to wait until a random Sprite is automatically created. Note that this interval starts hen the previous Sprite was automatically started, not when it ended. |
PInt |
PREF_PARTICLE_INTERVAL |
This expresses the number of seconds to wait until a random Particle is automatically created. Note that this interval starts hen the previous Particle was automatically started, not when it ended. |
UInt |
PREF_UNION_INTERVAL |
This expresses the number of seconds to wait until a random "FlowField Union" will occur when a FlowField change occurs (if the Flowfield slideshow mode is on). Because FlowField Unions are only included with G-Force Gold, this param is not used in the free trial version of G-Force. |
SDur |
PREF_SPRITE_DURATION |
This expresses the number of seconds a Sprite will be on-screen until it disappears (when G-Force starts a new Sprite, it assigns it a duration). If a Sprite defines 'PDur' in a corresponding config file, that value will override this value (and will be used instead). See the Sprites: "Clouds.txt" and "/Sprites/(Auto-Background)/(Default).txt"—both of these Sprites contain overriding 'PDur' definitions. |
PDur |
PREF_PARTICLE_DURATION |
This expresses the number of seconds a Particle will be on-screen until it disappears (when G-Force starts a new Particle, it assigns it a duration). If a Particle defines it's own 'PDur', that value will override this value (and will be used instead). See the particle named "Spinners" for more. |
CMor |
PREF_COLORMAP_MORPH_DURATION |
This expresses the duration (in seconds) of the transitions (or "morph") from one ColorMap to the next ColorMap in the slideshow (when the ColorMap slideshow is enabled). |
WMor |
PREF_WAVESHAPE_MORPH_DURATION |
This expresses the duration (in seconds) of the transitions (or "morph") from one WaveShape to the next WaveShape in the slideshow (when the WaveShape slideshow is enabled). |
FMor |
PREF_FLOWFIELD_MORPH_DURATION |
This expresses the duration (in seconds) of the transitions (or "morph") from one FlowField to the next FlowField in the slideshow (when the FlowField slideshow is enabled). FlowFields are CPU-intensitve to prepare for operation, so if you specify a duration such that a switch request occurs before the next FlowField in the slideshow is ready, the actual switch will not occur until it's ready. |
CTrn |
PREF_COLORMAP_TRANSITION_FCN |
During a ColorMap transition (or "morph"), G-Force must choose the rate that the offgoing ColorMap morphs into the oncoming one. With the input variable i, This expression takes an input from 1 to 0, 1 signifying the start of the morph, 0 signifying the end of the morph. Over the duration of the morph, i simply decreases linearly, from 1 to 0. This expression's result represents the weight of the offgoing config vs. the oncoming config, and it's expected to obey the following boundary conditions (or there will be visual discontinuities):
- Be continuous
- Have endpoints at (1,1) and (0,0)
- Must not result in a value less than 0 or greater than 1
Eye-appealing transitions usually have a high rate of change at the start of the morph (where i is near 1) and low rate of change at the end (as i approaches 0). Here are some examples and note how each obeys the above boundry conditions:
- " i^2 "
- " ( .5 + .5 * cos( PI * i ) )^2"
- " ( .5 + .5 * cos ( 3 * PI * i ) )^2"
|
WTrn |
PREF_WAVESHAPE_TRANSITION_FCN |
(See PREF_COLORMAP_TRANSITION_FCN) |
FTrn |
PREF_FLOWFIELD_TRANSITION_FCN |
(See PREF_COLORMAP_TRANSITION_FCN)
Note that the FlowField transition expression generally doesn't have to be as curved as the WaveShape and ColorMap transition expressions in order to result in a "good" transition. This is because FlowFields affect the derivative of what you see visually (ie, FlowFields express the velocity of pixels) while WaveShapes and ColorMaps affect directly what you see. Similarly, it's a car's position will never be discontinuous (ie, teleport), no matter what you do with the gas pedal. |
Flow |
PREF_FLOWFIELD_SCALE |
This scales all FlowField vector fields. Consider a FlowField that rotates all pixels about the origin: srcR="r", srcT="theta - .06". Seeing the flow scale to .5 would make it seem like time is going twice as slow (or that the field you're seeing is really srcR="r",srcT="theta - .03").
Note that FlowFields with geometrically-significant vector lengths will look grossly different if the flow scale is not 1 (almost always for the worse). Consider: srcX="x", srcY="- y". Normally, this field would produce a mirror effect as the image is flipped vertically each frame, but if it was scaled by half, it results in drastically different flow. |
CCal |
PREF_COLORMAP_CALC_INTERVAL |
To increase G-Force performance, the current ColorMap is not recalcuated for every frame (recall that ColorMaps must be constantly recalculated because they can be time-dependent). Instead, ColorMaps only recalcuated only every so often—CCal expresses this time interval (in seconds). Most ColorMaps change relatively slowly (or not at all), so even a value such as .1 is sufficiently short enough such that there will be no noticable step-change as the ColorMap is recalculated. Some ColorMaps, however, do change significantly in a short period of time, so the factory value is a little less than .1.
Since the sole basis of not recomputing the ColorMap each frame is to decrease system load, you can decrease this value in order to achieve smoother color changes (Note how there's no point in setting this value lower than .02 because you would normally never expect a frame rate higher than 50). A typical setting for a high performance machine is .04, meaning that a ColorMap update will occur at least 25 times a second. If your system is slow, you could increase this value to .2 to only recalcuate the ColorMap 5 times a second. Note that G-Force isn't a slave to the interval you specify in CCal—G-Force will update in shorter intervals during a period of known rapid change (ie, during a ColorMap transition (or "morph") set to have a duration of near one second).
ColorMaps have the ability to override this parameter by specifying their own 'CCal' in the form of an expression. The basis is that, ultimately, only a ColorMap knows how often it needs to be recalculated. The ColorMap "Tri-Chroma.txt" is a good example, and "ColorWheel" contains additional comments. |
|
|