Description: The sarah0 plugin (a.k.a. Sarah's first plugin)
Description: If you like this plugin you should really check out the main website for the latest version.
Author: Sarah Kelley
Email: sarah@sakelley.org
Website: http://blender.sakelley.org
License: GPL



                         How to use Sarah0

Sarah0 generates tiled shapes in 3D space, with or without distortion.
There are five different types of shapes, each described below.
The shapes can be adjusted using four controls:

	Lo - "Low value"
	Hi - "High value"
	Pa - "Parameter A"
	Pb - "Parameter B"

The function of the four controls depends on the shape and the variant.

Each basic shape has four different algorithm variants, selected
via the control marked "Var".



THE SHAPES

Squares - creates classic checkerboard patterns

	Variant 1: is a plain checkerboard
	Variant 2: plain checkerboard, but z lines up differently
	Variant 3: checkerboard with odd squares taking on random values
	Variant 4: checkerboard with even squares taking on random values.

	For all four variants, Lo and Hi adjust the size of some of the
	squares to give different kinds of patterns. Pa and Pb can be used
	to adjust the brightness of some squares in some variants.
	
	
Circles - creates radial gradients and nested rings.

	Variant 1: radial gradient or rings
	Variant 2: like variant 1 but with innermost ring randomly shaded
	Variant 3: like variant 1 but with outermost ring randomly shaded
	Variant 4: like variant 1 but both inner and outer ring randomly shaded

	For all four variants, Lo and Hi are used to adjust the size of the
	circles. Pa and Pb are unused.

Boxes - creates boxes, which can be hollow or nested.

	Variant 1: box with white outside, grey middle, and black inside.
	Variant 2: variant 1, but in true 3D space
	Variant 3: This is actually like circles and is likely to be replaced.
	Variant 4: basic grpid, uses Hi Lo for intensity,
	           and Pa Pb to adjust box sizes. Likely to be changed/replaced. 

	For variants 1-3, Lo and Hi are used to adjust the size of the
	boxes.

Blurbles - creates multiple groups of splotches on a grid.

	Variant 1: three splotch intensities, white, grey, black
	Variant 2: like variant 1 but black splotches are random shade
	Variant 3: like variant 1 but white splotches are random shade.
	Variant 4: like variant 1 but grey splotches are random shade.

	For all variants, Lo and Hi adjust the blurbles. Pa and Pb are unused.
	
Cirbles - randomly shaded cubes and shapes on a grid

	Variant 1: randomly shaded cubes.
	Variant 2: squares, circles, and plus signs.
	Variant 3: mostly circles. 
	Variant 4: needs work

	Variant 1 doesn't use any of the sliders, and the others use only
	Hi and Lo at the moment.



ADDING DISTORTION

The shapes by themselves are ok, but the textures really start to get
interesting when some distortion is added. The distortion is controlled
by four slidersand an integer:

	Nb - noise, blender algorithm
	Np - noise, perlin algorithm
	Ts - turbulence, soft
	Th - turbulence, hard
	Td - turbulence depth (integer)
	
Each of the four sliders is checked, and if not zero, distortion using the
specified algorithm is used. The meaning of the parameter is different
for each algorithm, but they're fairly straightforward to experiment with.

When multiple kinds of distortion are applied, they are averaged
together.

The distortion can also be scaled, in two different ways.

If the Ds value is nonzero, then that scale value is used for all four
types of distortion, and the other scalers are ignored.

When Ds is zero, the "extended" scalers are used:

	NbS - scaler for blender noise
	NpS - scaler for perlin noise
	TsS - scaler for soft turbulence
	ThS - scaler for hard turbulence

These scalers work in a peculiar way. 0.5 is the "center point" that
applies a scale of 1.0 (i.e. no scaling). Values towards zero scale
down to about 1/1000 scale, and values towards 1.0 scale up to
about 1000x.




BUMP MAPPING

Bump mapping is supported; use the Nabla control to adjust
the normal calculations. To turn off bump calcuations 
(which will speed things up a bit if you're not using them),
set Nabla to 0.0.



TIPS

Some of the algorithm variants don't work well, or seem to generate
a solid color for a lot of their settings. If this happens, you might
want to try turning off the noise (set Nb,Np,Ts,Th to zero) and get 
the shapes adjusted first.

All of the sliders can be adjusted at any time, however, keep in mind
that some values are special:
	
	Ds - When 0.0, the extended scalers take effect.
	     When not zero, the extended scalers don't do anything.
	     
	Nb,Np,Ts,Hh - to disable a particular kind of distortion, set its
		slider to zero. When all four kinds of distortion are zero,
		the distortion scalers, both Ds and the extended scalers,
		have no effect.

Some distortion scales simply generate noise, with no particular
pattern. This usually means one or more distortion sliders are set
either too low, or too high.

When possible, use Variant 1 for all the shapes, because these tend
to be easier to use than the other variants.



ISSUES

Anti-aliasing may be broken/incorrect/inaccurate

Bump Mapping may be broken/incorrect/inaccurate

Some variants don't work very well yet

It's possible to disable the extended distortion scaler by undefining
the EXTENDED_DISTORTION_SCALER macro and recompiling. This is only
useful if you have an older version of the plugin that lacked the
extended distortion scaler, to retain backward compatability. However,
that version was never distributed to the public, so you probably don't
have it, and this information is probably not very useful to you.
But if you wondered why EXTENDED_DISTORTION_SCALER is in the source
code, now you know!

You can compile the code with DEBUG_LOG_INPUTS to write a log
file in /tmp that contains texvec,dxt, and dyt for every plugin call
that requests anti-aliasing. You probably DON'T want to do this.