Wacko Software presents:

ChromaPlas 0.95 (pre-release).

ChromaPlas is a program that takes the old-skool demo plasma-effect and applies the plasma to various channels of images in different colour-spaces. The result is something psychedelic looking. It started off as little experiment into applying plasmas to colour-space components and grew into a fully-fledged project. As far as screensavers go, it is a somewhat trippy screensaver.

ChromaPlas is available for all platforms supported by Allegro. Currently, only the Windows version is a screensaver.

The source code is available from http://software.wackonet.net/#CHROMAPLAS (or if this is a source-distribution, it's part of this distribution - see source.txt for details on the source-code). So along with the Allegro library, you can build ChromaPlas for the platform of your choice, or even play with the source.

ChromaPlas is Freeware, meaning it's erm... free.



SYSTEM RECOMMENDATIONS:

The faster the computer, the faster the framerate ChromaPlas runs at. I would recommend a computer that's at least at the equivalent level of speed as a Pentium III or AMD Athlon class PC. To run the program at resolutions the size of large desktops, a much faster PC is needed. The Windows version requires a computer equivalent to a Pentium II class PC, and the DOS version requires a '486 or above (although a Pentium III is still recommended in both cases).



INSTALLATION AND UNINSTALLATION:

Installing the screensaver under windows:

If the ChromaPlas executable file ends in .scr (this is the case for the standard Windows screensaver distribution), you have the screensaver version. There are two ways of installing this. If you do not have permission to copy files into the Windows directory (you don't have Administrator privileges), it is recommended to use the first method.

1: Unzip the ChromaPlas zip to a folder, and right-click the executable (ChromaplasWin.scr). Select 'install' from the context-menu. The 'Screen Saver' dialog should pop up (or in older versions of Windows, the 'Screen Saver' tab of the 'Display Properties' dialog should pop up) with ChromaPlas selected as the screensaver. You may press the 'settings' button to access the ChromaPlas settings dialog. However, if another screensaver (or no screensaver) is then chosen and the dialog is closed, ChromaPlas will be uninstalled (it will disappear form the list and will need to be re-installed using this method).

2: An alternative method of installation if you have administrator privileges: This makes ChromaPlas available for all users of the PC and also means it remains in the list of screensavers when another screensaver is selected.
To install, place the 'ChromaPlasWin.scr' file from this distribution in your Windows-system directory - the 'Windows/Ststem32/' directory (or the 'WINNT/Ststem32/' directory if using Windows NT/2000 or the 'Windows/System/' directory if using Windows 9x). To set ChromaPlas as your screensaver, you can either right click on it in the directory you just copied it to and select 'Install' from the context menu. Or you may install it from the 'Screen-Saver' dialog (or in older versions of Windows, the 'Screen-Saver' tab of Windows's 'Display Properties' dialog) (right click on a blank area of the desktop and select 'personalize', then select 'Screen Saver' (or in older versions of Windows, right click on a blank area of the desktop and select 'properties' and select the 'Screen Saver' tab)). In this dialog, ChromaPlas will be listed as one of the screensavers in the screensaver combo-box. Select ChromaPlas and it becomes the screensaver. You may press the 'settings' button to access the ChromaPlas settings dialog. If you want to use the sample CHROMAPL.INI that came with the distribution (unlike the one generated by ChromaPlas, this one contains many comments describing the settings), you must first find where ChromaPlas writes CHROMAPL.INI to. To do this, press the 'settings' button to bring up the settings dialog, make a change and press the 'OK' button. A CHROMAPL.INI file should be written somewhere. You just need to find where it got written to. In older versions of Windows, it was written to the same Windows system-directory as the screensaver-file. In newer versions, it can be written elsewhere. For example, in the 32-bit version of Windows 7, it is in C:\Users\<username>\AppData\Local\VirtualStore\Windows\System32 and in the 64-bit version of Windows 7, it is in C:\Users\<username>\AppData\Local\VirtualStore\Windows\SysWOW64 [substitute <username> with your username]. Once you've copied the CHROMAPL.INI file across that came with ChromaPlas, you can check to see if it was copied by going to the settings-dialog and pressing the 'About' button and the INI settings name should be "ChromaPlas standard settings for Windows Screensaver distribution" (or whatever name was given to the INI file you are copying across) and not "ChromaPlas settings generated from hardcoded default settings". Note that the sample-images can be placed anywhere, but if you also place them in the same directory as the screensaver, they can instantly be found using the default settings. The screensaver can be un-installed by selecting a different screensaver (or no screensaver) and removing the files from the Windows system-directory they were copied to and removing CHROMAPL.INI.


Installing under all other platforms (or the non-screensaver Windows version):

ChromaPlas can be launched by launching the ChromaPlas executable (e.g. in DOS, this is CHROMAPL.EXE)



INSTALLING FROM A SOURCE DISTRIBUTION:

If you have a source-distribution (a distribution with no executable, but instead it comes with C sourcefiles), see the file source.txt for how to build the ChromaPlas executable. If you have no idea what I'm talking about in this paragraph, then it means you should probably be reading the "Installing under Windows" section instead and give your glance a good seeing to for wondering off aimlessly.



EXPERIENCING CHROMAPLAS:

There are many different ways of enjoying ChromaPlas. When using it as a screensaver, you may set it to grab the desktop image and apply the plasma to it. If you've been staring at your screen too long, it will at first look like either there's something wrong with the monitor, or there's something wrong with your head - until you remember it's the ChromaPlas Screensaver. As well as the desktop image, any picture in JPEG, PNG, BMP, LBM, TGA, PCX format may be used. The program even has a built-in image that can be used to best experience what the different effects can do. And of course, you may view the plasma on it's own so you can see the plasma in it's naked plasma-ness. By adding a funky palette effect to the plasma, it looks ... erm ... funky. Or you can even add a custom-palette from a paletted image (some examples (.pcx images) have been included with ChromaPlas).

What ChromaPlas does is to split the image into it's component channels with respect to a chosen colour-space. Then, it creates a greyscale plasma and adds the plasma value (which can be either positive or negative) to the chosen colour-space channels of the image. There are 3 colour spaces supported by ChromaPlas: RGB, HSV, and HLS. RGB just splits the image into it's Red, Green, and Blue channels. HSV and HLS are the more interesting colour-spaces...

Colour-spaces:

NOTE: The following paragraphs might go waaaay above your head. If that does happen, just run the program, tweak the settings, see what happens, and just sit back and enjoy the psychedelic swirl without having to worry about what is written in the next two paragraphs. Chill out funky dude - it's only a screensaver.

A colour-space is a means of representing a colour by building it up from it's primary components. In RGB space, a colour is created by a mixture of Red light, Green light and Blue light. As this is how monitors create colours, it is the native colour-space of most hardware, and the quickest to convert to and from. However, from a human's point of view, this isn't really an intuitive colour-space. The HLS colour-space splits the colour into more meaningful components - Hue, Lightness and Saturation. Hue describes which colour the colour is (which part of the visible spectrum it's from). Lightness corresponds to the quantity of light being used (how light a colour is from black to white, where colours can be at their most colourful in the middle). Saturation controls how 'colourful' the resulting colour with the given light-intensity is (or how pure or how grey the colour is). The HSV colour-space is a variation of the HLS colour-space. It splits the colours into Hue, Saturation, and Value. Hue in HSV space is equivalent to Hue in HLS space, but Saturation in the two spaces are different.  In HSV space, the Value (or brightness) describes how bright the colour is (the perceived intensity of a coloured-light), and Saturation determines how far away a colour is from the monochrome (greyscale) value of the colour's perceived intensity.

Another way of visualising the colour-spaces is as follows: RGB colour-space can be imagined to be a cube where each axis in the 3 dimensions corresponds to the amount of Red, Green or Blue in a colour. One corner of the cube would be black, and the corner on the other side would be white. The 3 corners adjacent to the black corner would be either red, green, or blue, and the three corners adjacent to the white corner would be the result of mixing two of the three colours. Any position within that cube would have a colour that is described by it's co-ordinates within the RGB cube - which is RGB space. HSV colour space can be imagine as a cone. The Value (brightness) parameter determines how far up the cone the resulting colour lies. The tip of the cone is black, and the base of the cone is where the colours are at their brightest. The Saturation determines how far away the resulting colour is from the cone's central axis (or how close it is to the cone's edge). The outside of the cone is where the colours are at their purest (most colourful) whereas the central axis is where they're least pure (they're a shade of grey between black and white). Hue is represented by the angle round the cone. So you can imagine Hue and Saturation to be a set of polar co-ordinates - Hue is the angle, and Saturation is the distance. Value is the height in the cone. HLS space, on the other hand, can be visualised as the HSV space with the centre-point of the base of the cone pulled up by the same length that the cone is, so this results in a double cone (two cones stuck together at the base). Hue in HLS colour-space is equivalent to hue in HSV colour-space. The same cannot be said for the other two values.

A much better description of HLS and HSV colourspaces can be found at http://en.wikipedia.org/wiki/HSL_and_HSV



TWEAKING CHROMAPLAS:

There are many settings in ChromaPlas that can be tweaked. At the moment, only the Windows Screensaver Version has an interactive means of tweaking the settings. In all other versions, the 'CHROMAPL.INI' file has to be manually edited. In the Windows version, once it's installed as a screensaver, go to the 'Screen-Saver' tab of 'Windows's Display Properties' dialog (right click on a blank area of the desktop and select 'properties'). From there, press the 'settings' button to go to the settings. Any changes made can be seen in the preview screen. To see a full-sized preview, just press the 'test' button from the ChromaPlas settings dialog (or alternatively, the 'preview' button from the ScreenSaver tab). This document just describes the settings. If using a version of ChromaPlas that does not have an interactive means of tweaking the settings, then look at the comments in the sample 'CHROMAPL.INI' file to find out which vales need to be used to obtain the desired settings. Many (but not all) of the settings are explained below. Even if this is too much to take in, just play with the settings and have fun.


Root settings:

+ The value of 'settingsname' can be used to identify a particular INI file. This is useful if you want to make sure you have copied an INI file to the correct location. The one that comes with ChromaPlas has the value set to "ChromaPlas standard settings for Windows Screensaver distribution", and an INI file created by ChromaPlas (if it did not find an INI file or "Restore defaults" was pressed from the settings dialog) will become "ChromaPlas settings generated from hardcoded default settings". To see which INI file is being used, either set the 'DisplayStats' setting to '1' or in the settings-dialog, press the "About" button and the INI settings name will be shown.


Allegro settings:

There are many settings that tweak the Allegro engine used to run ChromaPlas, but here are two important ones:

+ gfx_card: This overrides the graphics driver chosen by Allegro. This should be left blank unless you want to chose which graphics driver is being used.

+ disable_vsync: Normally, the program waits until the monitor is in the middle of a vertical retrace before it draws the frame. This eliminates the shearing effect you get when drawing an image while another image is being displayed, but it slows down the rendering as the program has to wait until the image has been drawn (unless triple-buffering is being used as the rendering-type). One reason for wanting to turn it off is to measure the raw framerate of the app.


Global settings:

+ Global speed: All the individual speeds of the plasma are multiplied by this - even the colour-speeds. Basically, it acts like a multiplier for both the "Plasma speed" and "Plasma colour speed" settings.


Image settings:

+ There is a choice of five different sources for the image. It can be any one of the following
 - No Image (just show the plasma): Displays the plasma by itself as a greyscale. If using no image, there are settings in the "Plasma colours" section that control how the plasma-intensities are represented.
 - Use built in image: Uses an image generated by the program.
 - Use Desktop as image (currently Windows only): Takes a snapshot of the desktop in it's current state and applies the plasma effect to it. When using ChromaPlas as a screensaver, using the desktop produces an interesting effect.
 - Use Desktop wallpaper as image (currently Windows only): Uses the image being used as the desktop wallpaper as the image.
 - Use file as image: Uses the specified image-file as the image.


Rendering settings:

+ One of the following two means of obtaining the image resolution can be chosen:
 - Use image/desktop resolution and colour-depth (or something close to it): Obtains the resolution from the source image.
 - Use the given resolution - Makes ChromaPlas run at the specified resolution and colour-depth that can be specified from the selection of resolutions and colour-depths. Note that if a lower colour-depth is chosen, a greater range of resolutions may become available.

+ Zoom/Reduce image to fit screen: If this is selected, the image is enlarged so it occupies as much of the screen as it can, or reduced so it fits on the screen.
+ Maintain aspect ratio when zooming: If "Zoom/Reduce image to fit  screen", then selecting "Maintain aspect ratio when zooming" will make sure that the image is zoomed on both axes by the same amount (so that the entire image occupies the smallest dimension). If this isn't selected, the image will be zoomed so it fills up the entire screen, but this will squash the image if it does not have the same aspect as the screen.

+ If image is smaller than screen, expand plasma to fill screen: If using an image that does not fill the screen, expand the plasma to fill the screen. Otherwise, the plasma is confined to the image. When zooming and preserving the aspect-ratio, or when the image fits the screen exactly, or when there is no source image, or if the image is generated, this setting will do nothing.

+ Confine everything to square of smallest screen-dimension: If the screen's dimensions are not equal (usually, they aren't), confine everything to a square of the smallest screen-dimension. This even confines the plasma to a square if 'ExpandPlasmaToFillScreen' is set.

All of the following settings in the 'Rendering settings' section do not appear on the dialog and only appear in the INI file.

+ Rendering type (how the image is rendered) (NOTE: This does not appear on the dialog and only appears in the INI file as 'RenderingType'): This is how the image is rendered:
 - Straight to screen: Draws the image on the screen directly. Can sometimes cause a flicker - especially if the statistics are displayed ('DisplayStats').
 - Double buffered: Draws the image on a memory bitmap and blits the contents of the memory bitmap to the screen.
 - Page-flipped: The image is built on an offscreen area of VRAM and when it's built, the screen then points to that area of memory and the next frame is built where the previous screen used to be.
 - Triple buffered: The image is built on an offscreen area of VRAM and when it's built, it allows the this area to be displayed while drawing to another offscreen area of VRAM (it will be displayed at the next vsync() without actually having to wait for a vsync).
 
+ Display statistics (NOTE: This does not appear on the dialog and only appears in the INI file as 'DisplayStats'): Displays a few things like the current framerate, monitor refresh-rate, the image resolution, which colourspace is being used, and a few other things.


Plasma settings:

+ Global plasma speed: All the individual speeds of the plasma (including the 'PlasmaRollSpeed') are multiplied by this (they still get multiplied by the global speed ('GlobalSpeed') as well).

+ Global plasma seed multiplier: This is used to zoom in to the plasma-components. The seed parameters used to build the plasma are multiplied by this. Note that this isn't quite the same as zooming in on the plasma (the amplitudes of the lissajous settings would also have to be tweaked).

+ Full intensity wraparound: The plasma is represented in memory as a series of values ranging from 0 to 255. If we map the plasma values to a cyclic parameter such as Hue, this would not be a problem. However, if we mapped the plasma values directly to the brightness, we would get a noticeable border between 255 and 0. To solve this, if "Full intensity wraparound" is unchecked, the values are mapped to a sawtooth function (plasma-values from 0-127 are multiplied by two, and plasma-values from 128-255 are also multiplied by two but then subtracted from 511). This creates a more aesthetically pleasing effect when non-cyclic values are used. Note that when this is checked, the intensity will always be 255 (the maximum).

+ Intensity: How intense the effect of the plasma is (how much the plasma will effect the selected channels of the colour-space). The value ranges from 0 (no effect) to 255 (the plasma has the greatest difference between maximum and minimum values). Note that when "Full intensity wraparound" is selected, this is always 255. This has no effect in funky palette mode or external palette mode.

+ Intensity rise time: How long (in seconds) it takes for the intensity of the plasma to rise from 0 to the value specified in the 'Intensity' setting. A value of 0 means start immediately with the intensity at full value. It is recommended to use this when using the desktop as the image. This has no effect in funky palette mode or external palette mode. It also has no effect if 'FullIntensityWrap' is on.

+ Confine lissajousses to square of smallest plasma dimension. If the plasma's dimensions are not equal (usually, they aren't), confine the loci of the lissajousses to a square of the smallest plasma-dimension.

All of the following settings in the 'Plasma settings' section do not appear on the dialog and only appear in the INI file.

+ PlasmaSeed1: A value used in the calculation to generate the 1st plasma 'circle'.
+ PlasmaSeed2: A value used in the calculation to generate the 2nd, 34d and 4th plasma 'circle's.

The plasma circles travel round the screen in Lissajous patterns. Each of the four plasma circles are represented by a 'plasma-lissajous'. The four of them can be controlled by the following four multi-valued settings:
+ PlasmaLissajous000Settings
+ PlasmaLissajous001Settings
+ PlasmaLissajous002Settings
+ PlasmaLissajous003Settings

Each plasma-lissajous has 3 parameters per dimension - the first 3 for the X dimension and the last 3 for the Y dimension. Each group of 3 parameters are arranged as follows:
 - Amplitude. This is the peak-to-peak amplitude relative to a screen-dimension (or the smallest screen-dimension dimension if 'ConfineLissajoussesToSquare' is set). Must be in range 0..1, otherwise the screen will go out of bounds of a plasma-circle-bitmap.
 - Frequency. The number of times per second the sine-wave in that dimension completes a full cycle (cycles per second). The frequencies are multiplied by 'GlobalPlasmaSpeed' and 'GlobalSpeed'. The frequency of the Lissajous is the reciprocal of the lowest common multiple of the reciprocals of the frequencies of the Lissajous components. Likewise for the frequency of the entire plasma.
 - Initial phase. This is how far along the sine-wave we begin at. All angles are in degrees. Note that a cosine-wave can be emulated by adding to 90 to the initial phase of a sine-wave.

Additionally, there's another parameter used to generate the plasma:

+ PlasmaRollSpeed: To make the plasma look more 'alive' the values cycle between 0 and 255 and wrap round back to 0 when they reach 255. This value determines how fast they cycle.


Plasma colours (when not using an image):

The generated palette can be one of the following:
 - Simple palette: Here, the palette-index just maps to brightness.
 - Funky palette effect: Apply a dynamically changing palette to the plasma to make it look more colourful. There are several parameters that can be used to control this effect. Implies 'FullIntensityWrap'.
 - External palette: Load the palette from an external source (e.g. an image or palette file) (implies 'FullIntensityWrap').

The following setting are used to control the colours when we're using the funky palette effect:

+ Funky palette effect colour-space: This is the colour-space that the three stimuli operate in. Can be one of RGB, HSV or HLS.
+ GlobalPlasmaColourSpeed: How fast the colour-cycling effect of the funky palette effect runs at (how fast the waves are animated at). All the individual colour-speeds are multiplied by this (they still get multiplied by the global speed ('GlobalSpeed') as well).

All of the following settings in the 'Plasma colours' section do not appear on the dialog and only appear in the INI file.

When using the funky palette effect, each colour-space stimulus is a sine-wave that is centred on the middle-value for the range. Each of these three stimuli are represented by a 'plasma-colour-space-stimulation-wave'. The three of them can be controlled by the following three multi-valued settings:
+ PlasmaColourSpaceStimulationWave0Settings
+ PlasmaColourSpaceStimulationWave1Settings
+ PlasmaColourSpaceStimulationWave2Settings

Each plasma-colour-space-stimulation-wave is animated as a wave across time whose current position represents the stimulus's value at palette entry #0. The waves span the range of palette-indices 0..255 (the number of waves in that range is determined by the wave-number). The following parameters describe the waves. Each colour-space-stimulation-wave has four parameters.
 - Amplitude. This is the peak-to-peak amplitude relative to 0 and the maximum stimulus-value (or -max and max if truncation is taking place). Must be in range 0..1, otherwise the stimulus-value will go out of bounds of it's range.
 - Frequency. The number of times per second the wave completes a full cycle (cycles per second). The frequencies are multiplied by 'GlobalPlasmaColourSpeed' and 'GlobalSpeed'. The frequency of the entire colour-cycling effect is the reciprocal of the lowest common multiple of the reciprocals of the frequencies of all the colour-cycling components.
 - Wavenumber. Number of waves that span the range of the palette (or colour-map table). This is the reciprocal of the wavelength. Must be an integer (this ensures continuity when value wraps from 255 to 0). Can be 0 (amplitude is uniform throughout the palette) or even negative (negative is equivalent to 180-InitialPhase).
 - Initial phase. This is how far along the sine-wave we begin at. All angles are in degrees. Note that a cosine-wave can be emulated by adding to 90 to the initial phase of a sine-wave.


Effect of plasma on image:

+ The colour-space the plasma will act on can be chosen (see the "EXPERIENCING CHROMAPLAS" section for a description of the colour-spaces).
 - RGB space
 - HSV space
 - HLS space

+ Within each colour-space, the stimuli/channels of the selected colour-space the plasma will be applied to can be chosen. If no stimuli are selected, then there will be no effect. It is recommended that just one, or possibly two, or maybe even three stimuli are chosen.



LIMITATIONS:

+ When running ChromaPlas in 8-bit paletted mode, bear in mind that only 6 bits per colour-component are used. To see it in it's full 8-bit per component mode, run it in 32-bit mode (or 24-bit mode) instead.
+ There is currently no means of checking that any values entered are within valid ranges. If after experimenting you can no longer get ChromaPlas to work and you cannot remember what changes you made to the configuration for that to happen. You may either delete the 'CHROMAPL.INI' file (a new one will be generated), copy the one that came with ChromaPlas on top of the one containing your settings (or if using the Windows screensaver, just press the "Restore Defaults" button), and it should work.
+ In the Windows screensaver preview window, if the image is not zoomed, a smaller proportion of the image is displayed in the preview window than would be displayed in the actual screensaver running in fullscreen (unless the unzoomed images is smaller than the preview-window).



TIPS AND SUGGESTIONS:

Here are some suggested image-types to try ChromaPlas out on:
+ Photos with a variety of bright colours.
+ Photos where the colours look like they've been washed out (a plasma that tweaks the image-saturation would look nice here).
+ Computer-generated 'test-patterns'
+ Desktops with one of the abovementioned images as wallpaper.


Sample settings (presets):

+ #1:
 - Use the built in image.
 - Use HLS colour-space and within that, the H and L stimuli.
 - Use plasma-seed multiplier of 2.0 and plasma speed of 1.5.
 - Use a resolution of 640 x 480 (or higher on fast machines - you can go as high as you can get a smooth framerate).
 - Make sure "Full intensity wraparound" is not selected.

+ #2:
 - The same settings as #1, but use a colour photo as the image instead. Notice that with a photo, when using H and L as the stimuli, the lighter and darker colours have different hues, whereas when the lightness was where it originally was, the hue is the same.

+ #3:
 - The same settings as #1, but only use the H stimulus and make sure "Full intensity wraparound" is selected.

+ #4:
 - Use the desktop (if not supported in the version of ChromaPlas being used, use an image-file that looks like an image of a desktop).
 - Choose "Use image/desktop resolution" (on slower machines, you might want to chose a lower resolution).
 - Use HLS colour-space and within that, the L stimulus.
 - Use 1.0 as the magnification and 1.0 as the plasma speed.
 - Make sure "Full intensity wraparound" is not selected.
 - Set the intensity rise time to 10.

+ #4: The same settings as #4 but use the HSV colour-space and within that, the V stimulus. This preset shows the main difference between the HLS and HSV colour-spaces.

+ #5:
 - Use no image.
 - Use 1.0 as the plasma seed multiplier, 3.33333 as the plasma speed and 1.0 as the plasma colour speed.
 - Make sure "Full intensity wraparound" is not selected.
 - Use the simple palette.

+ #6:
 - The same settings as #5 but select "Full intensity wraparound". This setting demonstrates the plasma in it's purest form.

+ #7:
 - The same settings as #5 but chose the option to apply the funky palette effect (make sure the funk palette effect colour-space is RGB-space).
 
+ #8:
 - The same settings as #7, but use larger values for the plasma speed (and possibly the plasma colour speed too (if you want to change both speeds by the same proportion, use the "Global speed" to save you having to change both at once)).

+ #9:
 - The same settings as #7, but set the funky palette effect colour space to HLS, set the wave-number of the Saturation-stimulus to 0 (the third parameter of the third stimulus ('PlasmaColourSpaceStimulationWave2Settings')).

+ #10:
 - The same settings as #7, but set the funky palette effect colour space to HLS, set the amplitude of the Luminance-stimulus to 0.0 (the first parameter of the second stimulus ('PlasmaColourSpaceStimulationWave1Settings')).

+ #11:
 - The same settings as #5 but chose the option to apply a custom-palette and choose "binarypal_bw.pcx", "Atari8BitPalette.pcx", "binarypal_op.pcx" or "binarypal_op_weighted.pcx" as the custom palette.

+ #12:
 - For something really fast, try The same settings as #5 but use 5.500000 as the global speed, 3.333333 as the plasma speed, and 31.0 as the plasma colour speed. Ideally, this should run with a high framerate.


If you have any suggestions for good presets or have found interesting effects when tweaking the values, then let me know about them.


Tips for dealing with a low framerate / making it faster / making it smoother:

+ A good framerate is where the fremerate (FPS or frames-per-second) equals the monitor's refresh-rate (which is often 60 Hz).
+ To see the framerate and other statistics (including the colour-depth that was chosen), set 'DisplayStats' to 1.
+ Instead of using the image/desktop resolution, use a custom resolution, and set it to a value that's low enough to give a decent framerate, and high enough to give the resolution you want to have.
+ Change the colour-depth to a lower value. If using 24-bit as the colour-depth, try changing to 32-bit, as 32-bit is often faster than 24-bit.
+ To make the plasma-animation appear smoother without attempting to increase the framerate, decrease the global speed (or the plasma speed or the plasma colour speed). Increasing the plasma magnification (plasma seed) also has a similar effect.
+ For something that really moves at a high framerate, use the 'no-picture' setting in an 8-bit colour-depth for something really fast!
+ Instead of using triple-buffering, page-flipping or double-buffering as the rendering type, use a rendering-type of "straight to screen", and disable the option where it waits for a vertical retrace. The disadvantage is that the screen might look a bit flickery and you'll get shearing artifacts. The best compromise is to use triple-buffering if it is supported.


To get a raw measurement of the framerate, set the following settings in the 'CHROMAPL.INI' file.
disable_vsync = 1
RenderingType = 1
DisplayStats = 1
The framerate that's printed on the screen will be the measured framerate without waiting for vertical retraces of any kind. The RenderingType can be changed to see how fast each rendering-type is. After you have experimented with the settings, restore the three settings mentioned above to their original values.


NOTE: If no INI file was detected in the directory of the executable/screensaver, an INI file with the default settings appropriate to it's environment will be created in that directory (the value of 'settingsname' will become "ChromaPlas settings generated from hardcoded default settings"). However, it is recommended you start with the sample INI that was provided with this screensaver, as this also contains an explanation of each setting.



TROUBLESHOOTING:

Problem: Sometimes, it looks like there's a shearing or tearing artifact.
Solution: This could be because ChromaPlas is currently set to not wait for a vertical retrace. Make sure the setting 'disable_vsync' is set to 0 in the INI file. If using the funky palette effect in an 8-bit graphics-mode and using triple-buffering and there's still shearing, try using a 15, 16, 24 or 32-bit mode instead. Or try using another screen-updating type such as page-flipping or double-buffering (set 'RenderingType' to the appropriate value). If possible, try and avoid setting 'RenderingType' to '1' (straight to screen). Sometimes, a tear is unavoidable but experiment with different values for 'RenderingType'.

Problem: On newer versions of Windows such as Vista or 7 (or possibly XP as well), when using an 8-bit graphics mode, the colours are messed up and when exiting the app, the desktop may also be messed up.
Solution: 8-bit modes are poorly supported by Allegro in newer versions of Windows. To work around this, don't use 8-bit modes. To make sure an 8-bit mode is not selected when automatically picking a resolution and to make sure no 8-bit modes are selectable from the dropdown combo-box in the settings-dialog, set the setting 'Disable8BPP' in the INI file to '1'.



CHANGELOG:

0.90 to 0.95:
+ Screen updating is now synched to the monitor's refresh rate (if known) instead of a 60Hz timer (if unknown a 60hz timer is still used).
+ Added support for other colour-depths. Can now render using 8, 15, 16, 24 and 32 graphics (both as source and destination).
+ Got the desktop-wallpaper mode to work (but only on Windows).
+ Can now render plasmas without an image in truecolour-modes using a colour lookup table. This enables things like the funky palette effect to be done in truecolour modes.
+ Can now apply a custom palette to the plasma - even in truecolour modes. To use one, load an image with a palete and the palette will be applied.
+ New settings: The full lissajous-paramaters (amplitude, frequency and initial phase) for both dimensions of the moving plasma-circles can now be specified. See 'PlasmaLissajous000Settings' etc. in the INI file (the frequency-component replaces the 'Ellipse__Speed' settings in previous versions).
+ New settings: Funky palette effect: As well as frequency, each colour-space-stimulation-wave has three new user-settable paramaters: Amplitude, initial-phase and wave-number. See 'PlasmaColourSpaceStimulationWave0Settings' etc. in the INI file (the frequency-component replaces the 'ColourCircle_Speed' settings in previous versions).
+ New setting: Added the 'FunkyPaletteEffectColourSpace' setting. Now you can choose which colour-space the funky-palette effect will work in (in previous versions, the RGB-space was used).
+ New setting: Full intensity wraparound ('FullIntensityWrap'). This is useful if the paramater to be affected by the plasma is cyclic (eg. hue).
+ New setting: Intensity Rise Time ('IntensityRiseTime'). The intensity is gradually increased from 0 to the value of the intensity-setting. This lasts for the intensity rise time (in seconds). It is recommended to use this when using the desktop as the image in screensaver-mode.
+ New setting: 'GlobalPlasmaSpeed' that multiplies plasma-params (not plasmacolour params).
+ New setting: "If image is smaller than screen, expand plasma to fill screen" ('ExpandPlasmaToFillScreen').
+ New setting: "Confine everything to square of smallest screen-dimension" ('ConfineEverythingToSquare').
+ New setting: "Confine lissajousses to square of smallest plasma-dimension" ('ConfineLissajoussesToSquare').
+ New setting: 'AlwaysUseColourLookupTableForRawPlasmaInTrueColourModes'. When using plasmas without an image, if set to 1, this will always render in truecolour modes using a colour-lookup table. Otherwise, raw plasmas (when there's no image or palette effects) will be rendered without the use of colour lookup tables. On most cases, it is recommended to set this to '1'.
+ Added the setting 'settingsname' so we can tell which INI file is being used. This is useful if we're not sure where the program will search for the INI file, and also lets us name the settings in individual INI files.
+ Changed settings: All frequencies are now in cycles per second (instead of radians per 1/60th second).
+ Changed setting: Replaced the 'VerticalRetraceSync' setting with Allegro's 'disable_vsync' setting (the on-ness has been inverted, so enabling 'VerticalRetraceSync' is the same as disabling 'disable_vsync'). The setting has been removed from the Windows Screensaver dialog but at least it should now affect page-flipped modes as well.
+ Settings dialog (Windows SS): Implemented test-mode. Just press the "Test" button in the dialog.
+ Settings dialog (Windows SS): Added a "Restore defaults" button that restores the settings to their default values (this overwrites the current values in the INI file).
+ Settings dialog (Windows SS): Got the BPP selection box to work, and 'ImageCustomBPP' now works.
+ Added support for PNG format images.
+ Implemented triple-buffering rendering mode (but currently changing the palette in 8-bit modes produces shearing when using triple-buffering). Set 'RenderingType' to 4.
+ Builds the built-in image quicker.
+ When setting up the image, the app is more responsive to commands to exit the app.
+ Statistics display now displays the monitor's refresh-rate and the Allegro graphics-driver ID, the settings-name and a few other things.
+ Now plays nicer with the CPU.
+ Now obeys app-close messages. This means if the operating-system tries to close the app, it will succeed.
+ Windows version can be compiled as a regular EXE (ie. not a screensaver).
+ Windows SS: Implemented the Screensaver Password setting.
+ Windows SS: If the setting 'UseIdlePriorityClass' is set, sets the process-priority to IDLE_PRIORITY_CLASS
+ Sourcecode: Moved obj.*/ directories to the obj/ directory (and obj.unix renamed to obj.unx).
+ bugfix: The Red and Blue of the builtin image would sometimes get swapped.
+ bugfix: Fixed page-flipping on DOS and Unix-based platforms.
+ bugfix: Windows SS: When running the Windows SS in preview-mode, The preview-window plasma-speed is synched to the actual plasma speed.




THE BIT AT THE END:

Visit http://software.wackonet.net/#CHROMAPLAS for updates and etceteras.


Andrei Ellman.	19/06/11

ae-a-chromaplas
wacko
wackonet
ten

(to get email address, reverse the contents of the last line, concatenate the lines with an @ for the first concatenation and a . for the next two concatenations.)
