Please make sure that, when you're using these macros, my name and perhaps my homepage is mentioned somewhere in the credits, even if you're using modified versions of the macros. That is mostly more or less a moral issue. For people who actually make money in any way aided by these macros, I'd like to receive a note in which way, and would be happy to have a look at it. But since I don't expect anyone will actually make much money with these macros, but more with their own ideas, I don't want to have people think I'd want money for this. I don't.
As a general rule of thumb (and you may easily apply this to works of others as well): give credit where you feel credit is due.

Don't expect a full-blown liquids simulation system, with which you can pour wine out of a bottle or fill a glass of water. This system takes care of liquid surfaces (hence the name) and simulates waves. Due to the limitations of the underlying algorithm (which originally was an animated 2D-Effect for pixel-displacement on images), it doesn't handle splashes, shallow shores, foam or stuff like that. If you've taken a look at the example animations on my website, you should have a feeling what you can expect.

In order to use a macro, all of them require the LSS-File-Identifier as the first parameter, in order to let the macro know which simulation data to access. Additionally, other parameters are required, in most cases to set the wave-effects generated by the macro.

If your OS supports filenames longer than the 8+3 digits (DOS-Standard), you may specify the Identifier as long as the maximum number of digits possible minus 4. The files will be named "[Identifier]_xxx.tmp", where xxx specifies the type of data saved within the file. All files are temporary and may be deleted AFTER the scene has been traced successfully (though it is recommended to keep the files until the entire animation is complete).

Amount of Macro Calls

Three macros are meant to be called once per simulation. LSS_Start and LSS_Stop are the obvious first and last Macros you'll use to begin and end the simulation process in any given frame. Right after LSS_Start, you may call LSS_Import, which imports a formerly exported Buffer (which may be done with LSS_Export). LSS_Environment is a macro which you'll have to call right after LSS_Import, or, if it isn't used, right after LSS_Start, since it will make heavy modifications to the simulation as a total. Note that the ex- and importing functionality is designed to be used for the same simulation, and takes care of loading a saved buffer instead of the default calm surface.

Then there are "Adding Macros", which may be called several times and will add waves into the simulation. This applies to LSS_Rain, LSS_Drop, LSS_Path, LSS_Stomp and above all, LSS_Object.

Additionally, there are LSS_UpdateTime and LSS_UpdateSpan, which update either time-settings or size-settings. The time-update is especially useful when you've finished a simulation and notice that you need an extra second or two. Without having to run the entire simulation again, you can just move onward using the older data, but with an enlonged timeframe.
The size-resetting only applies to the four defining corner- and above-nodes. With it, you may move the surface about and still have objects interact properly with it. It will retain its waves and node-detail, so stretching and squashing the area will result in strange effects.

Finally, there are LSS_Visualize and LSS_PreVisualize, which return a mesh for the surface. LSS_PreVisualize may be used without the entire simulation, but requires the Global variables to function properly. It is only meant as a preview where the surface is placed, it doesn't show any waves at all.

Animation_Time and -FPS

Throughout this Help, you'll find reference to the variable name "Animation_Time". This is a User-Set variable, and specifies the amount of seconds the current scene will render. All simulation-macros will then base their timing on this value, which runs from 0 to the specified second. Additionally, it might be helpful to declare "Animation_FPS". Normally, for movies you'd use a FPS (frames per second) of 25. If you want a 6 second animation, you'll thus use 6x25=150 frames. The FPS multiplied with the amount of simulation-seconds should be the minimum amount of steps you'd want your simulation to calculate, otherwise you'll get lots of frames which make use of interpolated steps, rather than new data. Using more steps will cause the waves to move faster. This variable sets the total amount of seconds which are being RENDERED.

Subset-Framing and Resimulation

The Simulation supports POV's subset-framing to a limited extent. The system doesn't save the state for every frame, but updates its data for every frame. If you jump back and forth between different sections of the simulation, it will resimulate the time up to the actual moment. By itself, the system will yield the same results as long as the same settings are used (and as long as the used macros are designed to do the same changes for the same steps, regardless of when they've been called. This is a special problem when using random-streams, and isn't easily overcome).

Additionally, when stopping renders during parsing time, it may occur that you corrupt the data in the process. This happens when you interrupt while the system is writing data to disk. The system will handle this by "Resimulation". It will simply simulate all steps required to reach the actual moment, which may be pretty parsing-intensive, dependant on the amount of steps to be calculated and the amount of data used.

In addition to keeping the simulation running properly, some corrupted files may be recalculated on the fly without harming the simulation at all. This applies to the final mesh, the default calm state of the surface and the DatSet, which tracks active and inactive nodes.

For final runs, keep in mind that it is best to stop the render during the tracing-phase, and continue the image using the Continue_Trace-Option (commandline use is "+C"), in order not to lose the simulation-data. This is of especial importance for very detailed simulations, where tons of data is processed, which would be pretty time-consuming to resimulate.

Last but not least, the two Updating-Macros LSS_UpdateTime and LSS_UpdateSize aren't functional for resimulation. They directly update the information of a simulation in order to reposition the surface or change the timing. Animations which make heavy use of these (this applies especially to LSS_UpdateSize, as it makes visually observable changes, e.g. rotation of the surface) won't calculate former steps properly. The subset-algorithm assumes the simulation is using the actual position of the surface and calculates everything based on that. If you modify the position during the animation, the algorithm will assume it has been in the new position from the beginning on, but this will only have effect as soon as the system tries to resimulate former steps. Keep that in mind when trying to do subset-animations with LSSM.

Here's a complete overview of all macros that you may use in your scene files, along with the required parameters and an explanation.

LSS_Start (Identifier)

This macro will generate the basic files. It is the very first macro you'll have to call to begin a simulation. It requires several predeclared variables, which are explained in detail later. Note that you MUST NOT exclude this Macro at any time in a simulation, as it updates internal timers and arrays.

LSS_UpdateTime (Identifier)

Once a simulation has finished, you might notice that you need an extra second or two. Just modify the timeframe of the simulation and alter the amount of frames rendered for the scene along with Animation_Time. If you then begin subset-framing at the frame you've reached before, the simulation will continue without resimulating. Note that it won't take a new beginning time into account until the simulation is restarted (either by rendering from the beginning again, or due to resimulation).

LSS_UpdateSize (Identifier)

During a simulation, you might want to move the surface. If you just translate it around, the other interactions won't line up with the surface anymore. That's why you should use this macro. It'll recalculate the corners and the topside of the simulation, but keeps all waves in their nodes. Useful to simulate rising water. Note that updating the size isn't handled as a movement, so when the moving surface interacts with an object, it won't cause waves unless the object itself is moving. Also, this macro isn't compatible with resimulations.

LSS_Export and LSS_Import (Identifier, Filename)

LSS_Export will export the current wave-data and the current mesh to the given file (which is a complete filename, e.g. "filename.end"). Note that it will use the data currently active at the moment LSS_Export is called, so this is best used after LSS_Stop.
Then, LSS_Import may be used to import the saved waves and mesh as the initial setting of a simulation, and replaces the default "totally calm surface" with a previosly generated one. Waves will keep their movement and act properly. Note that these macros require the original and the new simulation to be of the same NPU and position. In effect, these macros are mainly intended to run a simulation, pick a good frame, and use this as an initial state in order to circumvent the "totally calm surface" at the beginning.

LSS_Environment (Identifier, Environment-Object)

This macro will recode the data to properly simulate waves reflecting off of walls and other objects. This macro is designed to be called right after LSS_Start, and is meant to be called only once. The specified Object needs to be unanimated and unmoving. To use moving Objects with the simulation, use LSS_Object. Also note that depending on object-type (CSG, mesh, etc) you need to specify the Inside-Test to use Mesh-Support.

LSS_Object (Identifier, Array of Strings, Array of UV-Timeframes, UV-MinSpeed, UV-MaxSpeed, Detach-Height)

For Objects to interact with the surface, they need to fulfill certain requirements, which are explained later. They are then handed to this macro by filling an array with strings, each being the name of the object-macro.
Then, each object gets its own timeframe of animation, handed with an array of UV-Vectors. The u-part tells the second in which the animation of that particular object starts, and v tells the second when the animation stops. Both values are in relation to the Animation_Time.
Almost last but most important, two additional UV-Vectors. The first specifies the minimum speed at which an object may introduce waves into the simulation, where u is the speed (in POV-Units per second) and v is the height of the wave. The second vector defines a maximum speed and wave-height. Objects moving between the two speed boundaries will cause waves with a height according to the speed. Objects moving faster than the specified speed will only cause waves with the given maximum height, effectively limiting the height of waves introduced by moving objects.

Detach-Height is a float which defines the height of waves caused when the object fully "exits" or "enters" the surface. When a node isn't blocked anymore, a wave will be placed. This will counter the LSS_Obj_Memory effect in order to introduce these waves. If Detach-Height is 0, this feature is switched off.

NOTE: During my testing-phase of the simulation-process, I've found that waves caused by objects easily add up to four or five times the specified height. If sudden peaks appear near an object, this may be due to that, and you should try reducing the height of the waves or broaden the speed-limits you've put on the macro.

NOTE #2: This macro will output a Text-File named [LSS_Identifier]+"_ofs.txt". The value saved in this file is the highest speed introduced by objects during the current simulation. It is reset to 0 once a simulation is restarted.

Place_LSS_Objects (Animation_Time*clock)

This Macro was added to easily place all objects that have been supplied to the latest LSS_Object. It will position and animate them according to the latest macros. If you redefine a macro that has been used for LSS_Object after its use, and then call this macro, the results won't be the same as used for the simulation. Thus, it is best to use this macro right after LSS_Object.

Note that before and after an object has reached its timeframe, it will stay motionless where it begins/ends.

LSS_Rain (Identifier, Drops per Step, UV-Heightrange, Timeframe)

This macro will drop the specified amount of waves per step into the simulation. Their height will be a random value between the u and the v component of the UV-Heightrange. The waves will be dropped during the given Timeframe.

LSS_Drop (Identifier, Position, Magnitude, Time of Impact)

This macro will place a single wave at the given position, at the given time. If the position is above or below the surface, it will be mapped onto it. The height of the initial wave is set with magnitude. Obviously, Position is a vector, whereas Magnitude and Time of Impact are floats. The time of impact is, as always, a float ranging from 0 to Animation_Time. The wave will be dropped at the specified time, rounding up or down towards the nearest step where necessary.

LSS_Path (Identifier, Path-Name, Emitter-Vector, Step-Check, Timeframe)

This macro requires another macro which defines a path in 3D-Space. The name of that macro is handed to the LSS_Path-Macro as a string. The given Macro needs to be based solely on one float-parameter, e.g.

#macro This_Path(X) [...] #end

and returns a 3D-Vector, or to be more precise, a position. The Emitter-Vector is used as follows:
x-component defines the radius of the path. This does not simulate a spherical object, rather think of it as mapping radius: if the path isn't directly on the surface, it will get mapped to the surface if it isn't farther away than the specified radius. The waves caused by the path vary in height, according to the distance to the surface. The y-component sets the height when the path is right on the surface, z sets the height for waves when the radius barely touches the surface.
Step-Check is a UV-Vector. If the path comes to a halt during its movement, the macro would normally add for each and every step a new wave. This might not be a desirable effect for a non-moving position. The u of the vector tells the macro how many steps to check before the actual one, and if the movement is too less, it will create a wave with the height given by v. Timeframe, as always, is a UV-Vector, where u defines the beginning and v the ending time. Again, this is in relation to Animation_Time.

Note that unlike LSS_Object, this macro only introduces waves in relation to its position, not its speed, and is best suited for effects which would only create uniform-height waves, e.g. an insect swimming on the surface.

LSS_Stomp (Identifier, Magnitude, Time of impact)

Given a magnitude and a time of impact (as always in relation to Animation_Time), this macro will cause the environmental object to create waves where the liquid surface touches the environmental object. This is similiar to the effect seen when banging a table with a glass of water on it. The shockwave will travel through table and glass and emit into the water, causing a wave.

LSS_Stop (Identifier)

This is the last macro you will call for the simulation. It gathers all modifications made to the data by the various Macros, and calculates the next step(s) of the simulation. After that, all you need to do is use LSS_Visualize to generate a smooth-mesh for the surface.

LSS_Visualize (Identifier)

This macro is actually an inbuilt composition from my Mesh-Modifying-Macros. It loads the final data of the simulation, generates the normal-vectors required for the smooth_triangles, and builds the mesh. You should embrace this macro with object{} in order to texture the mesh.

LSS_PreVisualize (Identifier)

This macro is suited to just read the Corner-Positions and generate a minimal mesh from that (two triangles). It is used to position the surface before doing any kind of heavy-duty parsing. Set the system and comment the simulation macros out (not this one though). Now check if the position of the surface is correct using PreVisualize instead of LSS_Visualize. When everything is as desired, just delete the "Pre" and uncomment the simulation-macros.

LSS_Get_MeshDat (Identifier)

This is an internal macro which may be of use for other purposes as well. It reads the final data of the simulation and returns a twodimensional array, in which every index specifies one node of the rectangular grid. Internally, it is used for LSS_Visualize to model the surface, but if you've got other methods of visualizing the different nodes, this provides the required data. It simply returns an array and should be used as follows:

#declare/local Mesh_Position = LSS_Get_MeshDat("Some_Sim");

Inside-Test and Mesh-Support

POV-Ray has a native, inbuilt float-function called inside(). It uses two parameters, an object and a position. It will return true if the position is inside the object. This only works for objects which have a well defined inside, like spheres, boxes and cones; They may be used in CSG-Operations and are "solid" objects. This doesn't apply to (for example) meshes, which are just a bunch of triangles which may or may not enclose a volume. Look in the POV-Docs for more information on this.

For both Macros, LSS_Environment and LSS_Object, to work properly, I need a method with which I can find out if a node of the simulation is inside an object, or outside. To do this, I use the inside()-function. But what when a User wants to use meshes?

To solve this, you may declare a variable named LSS_Mesh_Support PRIOR to calling the LSS_Environment or LSS_Object Macros. It sets which type of inside()-test to use. Method 0 is the simple CSG-Type, Method 1 shoots rays upwards through the object and counts the amount of surfaces hit. If it is uneven, the test assumes its inside an object. Method 2 shoots rays up- and downwards. If the object is hit in both directions, the test assumes its inside an object.

For known issues with internal surfaces, objects handed to the system should be wrapped not with a union{}, but with a merge{}, when using Method 1. This gets rid of internal surfaces as long as some CSG objects are being used. Since you'll be handing identifiers, not actual objects to the macro, you can of course specify one object for the simulation's calculations, and use a different object in the scene.

LSS_Environment Specs

The object handed to the LSS_Environment macro needs to fulfill above mentioned specifications, additionally, it has to be static. LSS_Environment "hardcodes" a node's state to disk and excludes dead nodes from the calculation process to save parsing time. Effectively, LSS_Environment is meant to specify a "solid" structure in which the simulation takes place. Moving and altering objects are meant to be set with LSS_Object. If you alter the simulation's surface during an animation using LSS_UpdateSize, you'll have to use LSS_Environment again.

LSS_Object Specs

Objects handed to LSS_Object need to be declared inside a macro, which takes only one Parameter: float X. It should fulfill the merge-requirement from above in case you want to use Mesh-Support for objects.

As an example, here's a setting for an object:

#macro Some_Object(X)
[Object based on variable X]
#end

It is essential that the macro only takes one parameter, which is a float. You can use any other name, it doesn't have to be X. Just remember that its a float which will range from 0 to 1 when called. This 0 to 1 value represents the timeframe of the object which you specify in LSS_Object, but I'll return to this later.

Every object then requires an additional Transformation-Macro, which MUST have the same name as the object-macro, but requires an additional "_Transform" at the end. For already given example, this would be:

#macro Some_Object_Transformation(X)
transform{ [Any kind of Transform, based on X] }
#end

Again, X may be any name, and is a float.

For the LSS_Object to identify the objects it is using and to animate them, you hand the object's name as a string inside an array. For example, above object would be set as following:

array[1] {"Some_Object"}

There is no need to specify the transform-macro, the system will do that by itself. As a second parameter, LSS_Object requires another array, this one being filled with UV-Vectors. The first and second array given to the macro should have the same size. Every index of one macro (the name of the object-macro) is paired with the same index of the timeframe-array. The UV-Vector specifies the beginning and ending time for the object's movement. These values are given in seconds and relate to (you should have read that often enough by now) Animation_Time.

The simulation-macro will then take care of the rest. It will convert the UV-Timeframe into the above mentioned values ranging from 0 to 1, and these are also set according to the timeframe of the simulation itself. But you don't need to clutter yourself with these thoughts: just set a timeframe for the objects, and the macro will take care of the rest.

Note on LSS_Object's approach

LSS_Object calculates the speed of an object by reverse-transforming a given position to its initial state, then transforming it back to a state just before the actual moment. The distance between the two positions is used to determine the speed, because the object's part which is now blocking a certain node has travelled the calculated distance in a given time.

Obviously, this approach may run into trouble when pure rotation is being applied to the object. There is also no guaranteed method to derive the rotating speed if the rotation is too fast for the time-intervals used by the macros. But simulations running on discrete steps always have the problem of data being missed in between the steps, so please don't complain about that. Just raise the steps.