deformvertexes explained

G'day folks,
Does anyone know of any documentation /tutorial regarding deformvertexes or perhaps your own understanding of them?

I know of the basic example taken from default shaders...
deformVertexes flap t 80 cos 0 5 0.2 0.25 0
They are said to represent <amplitude> <phase> <frequency> <optional min> <optional max>
... or ...
deformVertexes wave 45 sin 0 2 0.5 6
... but we have a few more parameters than the <explained parameters> so which goes with which and what do each of them do?

There are also several words that can follow "deformVertexes" such as :
flap, wave, buldge, move, sawtooth, ...

And there's also things like:
rgbgen wave triangle 1 5 1 3
... which can also include various formations following the "rgbgen wave".
triangle, square, sin, ... and possibly others.

Has anyone delved in and documented the changes made by using different parameters?

Here's a scenario that I have just encountered and endured.
I have been helping a friend with his first map. It has foliage textures on a few patches and I wanted to make the top of the foliage sway as if by a breeze.
So I used :
deformvertexes flap t 2 cos 0 1 0 .10 0 2
However that made the bottom of the texture sway more so than the top of it so I rotated the patches upside down and flipped the textures upright.
They still swayed at the bottom more so than the top.
I changed the values " 0 1 0 .10 0 2" by swapping the numbers around which just deformed them to all kinds of shapes like a hyped up frog in a sock.
I held my tongue to the left then to the right. Same result.

So I ended up redrawing my foliage TGA textures upside down in my paint program and applied the alpha channel mask upside down too.
This has taken the better part of a whole day (23 TGA files with transparency masks plus trial and error of editing the parameters).
Where as a better understanding of the "deformvertexes" would have taken less than a minute to edit in the shader.

Any guidance on this matter would be greatly appreciated. Thank you.

Okay, at the risk of replying to my own question, here's a list regarding deformvertexes that might be of use to you (as a mapper) and / or others.
Although if someone could still explain how to make the top of the deformvertexes sway (instead of the bottom) in plain English I'd appreciate it.

deformVertexes
This function performs a general deformation on the surface's vertexes, changing the actual shape of the surface before drawing the shader passes. You can stack multiple deformVertexes commands to modify positions in more complex ways, making an object move in two dimensions, for instance.

deformVertexes wave <div> <func> <base> <amplitude> <phase> <freq>
Designed for water surfaces, modifying the values differently at each point. It accepts the standard wave functions of the type sin, triangle, square, sawtooth or inversesawtooth. The "div" parameter is used to control the wave "spread" - a value equal to the tessSize of the surface is a good default value (tessSize is subdivision size, in game units, used for the shader when seen in the game world) .

deformVertexes normal <div> <func> <base> <amplitude ~0.1-~0.5> <frequency ~1.0-~4.0>
This deformation affects the normals of a vertex without actually moving it, which will effect later shader options like lighting and especially environment mapping. If the shader stages don't use normals in any of their calculations, there will be no visible effect.

Design Notes: Putting values of 0.1 t o 0.5 in Amplitude and 1.0 to 4.0 in the Frequency can produce some satisfying results. Some things that have been done with it: A small fluttering bat, falling leaves, rain, flags.

deformVertexes bulge <bulgeWidth> <bulgeHeight> <bulgeSpeed>
This forces a bulge to move along the given s and t directions. Designed for use on curved pipes.

Specific parameter definitions for deform keywords:
<div> This is roughly defined as the size of the waves that occur. It is measured in game units. Smaller values create a greater density of smaller wave forms occurring in a given area. Larger values create a lesser density of waves, or otherwise put, the appearance of larger waves. To look correct this value should closely correspond to the value (in pixels) set for tessSize (tessellation size) of the texture. A value of 100.0 is a good default value (which means your tessSize should be close to that for things to look "wavelike").

<func> This is the type of wave form being created. Sin stands for sine wave, a regular smoothly flowing wave. Triangle is a wave with a sharp ascent and a sharp decay. It will make a choppy looking wave forms. A square wave is simply on or off for the period of the frequency with no in between. The sawtooth wave has the ascent of a triangle wave, but has the decay cut off sharply like a square wave. An inversesawtooth wave reverses this.

<base> This is the distance, in game units that the apparent surface of the texture is displaced from the actual surface of the brush as placed in the editor. A positive value appears above the brush surface. A negative value appears below the brush surface. An example of this is the Quad effect, which essentially is a shell with a positive base value to stand it away from the model surface and a 0 (zero) value for amplitude.

<amplitude> The distance that the deformation moves away from the base value. See Wave Forms in the introduction for a description of amplitude.

<phase> See "Waveform Functions" below for a description of phase)

<frequency> See "Waveform Functions" below for a description of frequency)

Design Note: The div and amplitude parameters, when used in conjunction with liquid volumes like water should take into consideration how much the water will be moving. A large ocean area would have have massive swells (big div values) that rose and fell dramatically (big amplitude values). While a small, quiet pool may move very little.

deformVertexes move <x> <y> <z> <func> <base> <amplitude> <phase> <freq>
This keyword is used to make a brush, curve patch or md3 model appear to move together as a unit. The <x> <y> and <z> values are the distance and direction in game units the object appears to move relative to it's point of origin in the map.

The <func> <base> <amplitude> <phase> and <freq> values are the same as found in other wave form manipulations.

The product of the function modifies the values x, y, and z. Therefore, if you have an amplitude of 5 and an x value of 2, the object will travel 10 units from its point of origin along the x axis. This results in a total of 20 units of motion along the x axis, since the amplitude is the variation both above and below the base.

It must be noted that an object made with this shader does not actually change position, it only appears to.

Design Note: If an object is made up of surfaces with different shaders, all must have matching deformVertexes move values or the object will appear to tear itself apart.

DeformVertexes autosprite
This function can be used to make any given triangle quad (pair of triangles that form a square rectangle) automatically behave like a sprite without having to make it a separate entity. This means that the "sprite" on which the texture is placed will rotate to always appear at right angles to the player's view as a sprite would. Any four-sided brush side, flat patch, or pair of triangles in an .md3 model can have the autosprite effect on it. The brush face containing a texture with this shader keyword must be square.

Design Note: This is best used on objects that would appear the same regardless of viewing angle. An example might be a glowing light flare.

DeformVertexes autosprite2
Is a slightly modified "sprite" that only rotates around the middle of its longest axis. This allows you to make a pillar of fire that you can walk around, or an energy beam stretched across the room.

************************

Waveform Functions
Many of the shader functions use waveforms to modulate measurements over time. Where appropriate, additional information is provided with wave modulated keyword functions to describe the effect of a particular waveform on that process. Currently there are five waveforms in use in Q3A shaders:

Sin: Sin stands for sine wave, a regular smoothly flowing wave ranging from -1 to 1.
Triangle: Triangle is a wave with a sharp ascent and a sharp decay, ranging from 0 to 1. It will make a choppy looking wave forms.
Square: A square wave simply switches from -1 to 1 with no in-between.
Sawtooth: In the sawtooth wave, the ascent is like a triangle wave from 0 to 1, but the decay cuts off sharply back to 0.
Inversesawtooth: This is the reverse of the sawtooth ... instant ascent to the peak value (1), then a triangle wave descent to the valley value (0). The phase on this goes from 1.0 to 0.0 instead of 0.0 to 1.0. This wave is particularly useful for additive cross-fades.

Waveforms all have the following properties:

<base> Where the wave form begins. Amplitude is measured from this base value.

<amplitude> This is the height of the wave created, measured from the base. You will probably need to test and tweak this value to get it correct for each new shader stage. The greater the amplitude, the higher the wave peaks and the deeper the valleys.

<phase> This is a normalized value between 0.0 and 1.0. Changing phase to a non-zero value affects the point on the wave at which the wave form initially begins to be plotted. Example: In Sin or Triangle wave, a phase of 0.25 means it begins one fourth (25%) of the way along the curve, or more simply put, it begins at the peak of the wave. A phase of 0.5 would begin at the point the wave re-crosses the base line. A phase of 0.75 would be at the lowest point of the valley. If only one wave form is being used in a shader, a phase shift will probably not be noticed and phase should have a value of zero (0). However, including two or more stages of the same process in a single shader, but with the phases shifted can be used to create interesting visual effects. Example: using rgbGen in two stages with different colors and a 0.5 difference in phase would cause the manipulated texture to modulate between two distinct colors. Phase changes can also be used when you have two uses of the same effect near each other, and you don't want them to be synchronized. You would write a separate shader for each, changing only the phase value.

<freq> Frequency. This value is expressed as repetitions or cycles of the wave per second. A value of 1 would cycle once per second. A value of 10 would cycle 10 times per second. A value of 0.1 would cycle once every 10 seconds.

I hope it helps someone.

I think flap and wave are similar by the looks of it. I've seen comments online that say wave was replaced with flap in CoD 1, which uses id Tech 3 too (and was made by a lot of the MOHAA crew).

What do you get if you use: deformvertexes flap t 2 sin 0 1 0 .10 0 2

Just out of curiosity more than anything.

It was all used in Quake 3 Arena. I extracted it from the official shader manual by id software.

I did replace "cos" with "sin" at one stage and although I can't recall that actual result, it didn't do what I wanted.

I've been playing with the deformvertexes for a couple of hours today and I'm not finding much of a difference between "wave", "flap" or "bulge" except bulge doesn't have the <div> <func> or <base>, it only has three numbers trailing it.
I can get the same results with either of them.
I recall seeing a youtube clip on deforming vertexes. The example showed a flag using the bulge parameter.
One long ripple flows across and down the flag diagonally.
I'm trying to create the same effect but horizontally as a wave in the ocean.

The default ocean textures use "flap" for some and "wave" for others but they all basically do the same boring deformation where the whole water brush moves one corner up and the other corner down.
Its more like the tidal movement of a bay or cove rather than the waves of the ocean.
I have tried the bulge width from 1024 to 8 and it still moves the whole water brush the same.

Replacing "sin" with "sawtooth" in a flap or wave wasn't the answer either. It rises as a normal wave but then just drops suddenly and unnatural.