Class Documentation

Name:Ripple
Version:1.0
ID:ID_RIPPLE
Status:Stable
Category:Effect
Date:December 2003
Author:Rocklyte Systems, Algorithms by Scott Scriven
Copyright:  Rocklyte Systems (c) 2002-2003, Scott Scriven (c) 1997. All rights reserved.
Short:  Creates water ripple effects in real time.



Description

The Ripple class draws an animated effect that emulates the appearance of water ripples, as well as other wave and vibration based effects. The algorithms use a large amount of CPU time and this increases according to the size of the area that the graphics are being applied to.

Once initialised, the effect will run automatically until the object is freed from the system.

Structure

The Ripple object consists of the following public fields:

CanvasHeight  Defines the height of the ripple effect buffer.
CanvasWidth  Defines the width of the ripple effect buffer.
Density  The density of the canvas is determined by this field.
DropHeight  The height of new droplets is determined by this field.
Flags  Special flags are applied here.
Height  The height of the ripple graphic is specified here.
Strength  The amount of strength applied to new ripples.
Width  The width of the ripple graphic is specified here.
XCoord  Defines the horizontal position of the ripple graphic.
XOffset  Defines the horizontal offset of the ripple graphic.
YCoord  Defines the vertical position of the ripple graphic.
YOffset  Defines the vertical offset of the ripple graphic.
Field:CanvasHeight
Short:Defines the height of the ripple effect buffer.
Type:LONG
Status:Read/Init

Once it is initialised, the ripple object allocates its own graphical workspace for generating the effect. The CanvasWidth and CanvasHeight fields have default values, but you may want to set the dimensions of the area as it has a direct effect on the speed and quality of the algorithm.

If the value is high, the quality will increase but the effect will take longer to generate. If the value is low then the quality will decrease but the effect will be generated more quickly. It is recommended that the value you specify is between the range of 50 and 400.


Field:CanvasWidth
Short:Defines the width of the ripple effect buffer.
Type:LONG
Status:Read/Init

Once it is initialised, the ripple object allocates its own graphical workspace for generating the effect. The CanvasWidth and CanvasHeight fields have default values, but you may want to set the dimensions of the area as it has a direct effect on the speed and quality of the algorithm.

If the value is high, the quality will increase but the effect will take longer to generate. If the value is low then the quality will decrease but the effect will be generated more quickly. It is recommended that the value you specify is between the range of 50 and 400.


Field:Density
Short:The density of the canvas is determined by this field.
Type:LONG
Status:Read/Set

The Density field controls the density of the ripple canvas. The higher the density, the quicker the ripples will fade away. Very low density values will cause the ripples to die over a long period of time.

The range of this field is between 0 and 100.


Field:DropHeight
Short:The height of new droplets is determined by this field.
Type:LONG
Status:Read/Set

The DropHeight has an effect on the height that is applied to new ripples. This primarily impacts on the lighting and the initial size of new ripples. The minimum height is a value of 10 and the maximum is 1000. You may find that very low values are useful for more subtle ripple effects.


Field:Flags
Short:Special flags are applied here.
Type:LONG
Status:Read/Set

Special flags supported by the Ripple class can be specified here. As there are many options available, try experimenting with the application of different flags to create all sorts of different effects.

The following flags are responsible for adding automated effects:

FlagDescription
SURFERThe surfer mode creates a constantly applied ripple that travels around the display using a sine wave.
RAINDROPS  This effect creates the impression of raindrops falling on the canvas.
SPLASHESThis effect is identical in style to the raindrops effect but uses bigger drops to create the impression of large splashes.
SWIRLThis effect creates a swirling pattern that spins around in the centre of the canvas.

The following flags determine the type of ripples that are applied. Note that if neither of these flags are set, the default 'raindrop' type is used.

FlagDescription
PUNCHThis flag provides a ripple effect combined with a distortion.
WARPThis flag provides a pure distortion that has no rippling effect at all.

The following flags impact upon drawing style and user activity:

FlagDescription
BLENDThis flag changes the drawing routine so that it applies pure alpha blending for the ripples with no other special techniques for 3D styling.
GREYSCALEThis flag forces the drawing routine to simply draw the grey scale version of the ripple's internal effect buffer. Very useful for generating a different type of effect.
HIGHQUALITY  Use this flag to enable high-quality mode. This is slower than the default quality standard.
INTERACTIVESet this flag to enable user interactive mode. This allows the user to draw his own ripples using the attached pointing device. The first button places a ripple and the second button switches the current ripple type that is being used.

Field:Height
Short:The height of the ripple graphic is specified here.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

If a ripple graphic is to be limited to a specific drawable area, set this field to limit the clipping height. A percentage may be specified if the FD_PERCENT flag is used when setting the field.


Field:Strength
Short:The amount of strength applied to new ripples.
Type:LONG
Status:Read/Set

The Strength field determines the amount of strength that is applied to new ripples. This primarily impacts on the overall size of new ripples, so if your ripples are looking too small, it will help to increase the Strength field. Values between 10 and 25 are usually appropriate.

The minimum setting for this field is 2 and the maximum is 200.


Field:Width
Short:The width of the ripple graphic is specified here.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

If a ripple graphic is to be limited to a specific drawable area, set this field to limit the clipping width. A percentage may be specified if the FD_PERCENT flag is used when setting the field.


Field:XCoord
Short:Defines the horizontal position of the ripple graphic.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The horizontal position of an image can be set to an absolute or relative coordinate by writing a value to the XCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:XOffset
Short:Defines the horizontal offset of the ripple graphic.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The XOffset has a dual purpose depending on whether or not it is set in conjunction with an X coordinate or a Width based field.

If set in conjunction with an X coordinate then the image will be drawn from that X coordinate up to the width of the container, minus the value given in the XOffset. This means that the width of the image is dynamically calculated in relation to the width of the container.

If the XOffset field is set in conjunction with a fixed or relative width then the image will be drawn at an X coordinate calculated from the formula "XCoord = ContainerWidth - RippleWidth - XOffset".


Field:YCoord
Short:Defines the vertical position of the ripple graphic.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The vertical position of an image can be set to an absolute or relative coordinate by writing a value to the YCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:YOffset
Short:Defines the vertical offset of the ripple graphic.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The YOffset has a dual purpose depending on whether or not it is set in conjunction with a Y coordinate or a Height based field.

If set in conjunction with a Y coordinate then the image will be drawn from that Y coordinate up to the height of the container, minus the value given in the YOffset. This means that the height of the ripple is dynamically calculated in relation to the height of the container.

If the YOffset field is set in conjunction with a fixed or relative height then the image will be drawn at a Y coordinate calculated from the formula "YCoord = ContainerHeight - Height - YOffset".