 Contents - Shield Generator Include File v1.0 (May 1999) By Tom York
=====================================================================

1.........................About the Shield Generator include file (SGIF)
2.........................Using the SGIF
3.........................Parameters
4.........................Preset shield types
5.........................Adding your own shield
6.........................SGIF problems and help
7.........................Feedback and legal information


Section 1 - About the Shield Generator include file
===================================================

  This include file was developed for sci-fi type scenes, and creates an 'energy shield' effect. 
If you've seen Star Trek battles you'll know the kind of thing, and if you haven't then load
up EXAMPLE.POV and find out!. Several different preset shield styles are provided, and all 
the maths is in macros so you can concentrate on visuals if you want to add a new style 
of your own. I can see other 'field effects' coming out of this like hyperspace jumps and so 
on and so forth, but I'd be very interested to hear of any applications in areas other than 
sci-fi. This is also the first include file that I have written for distribution, and I would 
welcome constructive criticism and suggestions on improvements to be made. I understand that 
it is usual to use media (halo in POVRAY 3.0) to get shield effects. However, the scenes that 
I created the SGIF for rendered very slowly with media, which killed my attempts at animation ;) 
There are some disadvantages in using textured spheres rather than media for diffuse effects, 
the main one being that certain shield styles (especially the FLAT style) have sharply defined 
edges. On other types (ABSORPTION and REFLECTION) it is not so obvious, since the spherical
shape gets broken up quite a bit.
  The Shield Generator was written and tested using POV-Ray v3.1 for Windows 95, and has not
been tested on any other version/system combination. The SGIF uses macros, so it will not work
on any version of POV-Ray earlier than 3.1. The SGIF is distributed as SG.ZIP, and consists of 
the following files:
  
SHIELD.TXT       This file
SHIELD.INC       The shield generator include file
EXAMPLE.POV      POV scene file to demonstrate the shield generator.
ABSORB.INC       Files containing preset shield style
DISTORT.INC       .
FLAT.INC          .
HYBRID.INC        .
LIGHT.INC         .
REFLECT.INC       .
RIPPLE.INC        .

Just unzip SG.ZIP to your POV include directory (making sure to preserve the directory structure) 
and the generator is ready to use.  


Section 2 - Using the SGIF
==========================

  The SGIF creates a spherical shield (there is a scaling parameter that can make 
an ellipsoidal shield instead) which is transparent unless 'hit'. By placing an object inside the 
sphere the appearence is created that the object is protected by a hi-tech 'barrier'. 
  To use the shield generator in your scenes, you have to include SHIELD.INC in your scene with
the line
        
#include "SHIELD.INC"   
        
This creates a basic shield effect with the default settings (see section 3 - Parameters). To alter 
settings, you must declare the shield parameters you want to change before including SHIELD.INC, as in 
this example:

#declare s_centre = <0.5, 1, -2>;
#declare s_shot_color = <0.6, 0.12, 1>;
#include "SHIELD.INC"

This creates a spherical shield centred on <0.5, 1, -2>, being hit by a weapon with color <0.6, 0.12, 1>
You can include SHIELD.INC as many times as you like to create multiple shields in a scene. Each shield
can have different parameters (described in the next section). In animations, the behaviour of a shield
is determined by the animation parameters s_cstart (determines at what value of clock the shield is 'hit')
and s_cend (the value of clock after which the shield is not displayed). The actual rate at which the 
shield effect fades is exponential and determined by s_decay. 


Section 3 - Parameters
======================

  The SGIF is controlled through parameters. Any parameter is set by using
  
#declare parameter = value(;)

where parameter is the name of the parameter to set and value is what to set it to. The semi-colon is 
needed for float, vector, boolean (true/false) and colour values but not for strings. The parameters
supported by the SGIF are detailed in this section, in alphabetical order. Note
that the preset shield types vary in exactly how they use these parameters -
some amount of experimentation may be needed to obtain good results. For your
own shields, you can use these parameters however you want.

----------------------------
s_background (colour vector)
----------------------------
This vector is used by the reflection shield to specify a background level
for reflection. It is not used by other shields. The default value is
<0, 0, 0>. 

-----------------
s_centre (vector)
-----------------
Sets the centre point for the shield effect, by default <0, 0, 0>.

------------------
s_coverage (float)
------------------
Sets what area of the shield saturates to the colour of incoming fire. For example, at the 
default of 0.2 (20%) about 20% of the shield saturates, centred on the impact site. Play 
about with this one to get a feel for it. This also sets how intensely the affected area 
reacts, in combination with s_shield_intensity.

----------------------------
s_cstart and s_cend (float)
----------------------------
These parameters control when a shield effect appears and disappears in animations.
If the value of the animation variable (clock) is greater than s_cstart and less
than s_cend then the shield effect is displayed. If not specified, s_cstart 
defaults to 0 and s_cend defaults to 1.

----------------
s_scale (vector)
----------------
Use this to change the size of the shield, or to create an ellipsoidal shield 
as opposed to the usual spherical one. The default is <1, 1, 1> which gives a 
spherical shield 2 units in diameter.

-------------------
s_scramble (vector)
-------------------
The absorption and hybrid shields texture the shield with a bozo pattern which is rotated
rapidly to look like a sparkle effect for animations if the s_shield_grain is small enough. 
However, if you want a static shield or are using a large grain you can set this option.
A value of <x, y, z> makes the shield rotate x degrees around the x axis, y degrees around
the y axis etc, over the period when the shield is visible. The default value is <3e4, 3e4, 3e4>
for a sparkly effect.
                                              
---------------
s_decay (float)
---------------
Sets how quickly the effect of a shot disperses, and how fast the shield returns
to normal. By default this is 3. Setting it to negative values causes the effect
of a hit to increase with time. 
                                       
-----------------------
s_shield_style (string)
-----------------------
Use this option to choose the type of shield. There are six preset shields,
and you can add more if you wish. See sections 4 and 5 for information on 
using the preset shields and adding custom shields. The default shield style
is "absorption".

-------------------------------
s_shield_colour (colour vector)
-------------------------------
Specifies the colour of the shield in the absence of any 'hits'. By default
this is <0.6, 0.6, 0.9>, giving a bluish shield.

-----------------------
s_shield_grain (vector)
-----------------------
This specifies the scaling of the pattern applied to the absorption 
shield. The default value of <0.05, 0.05, 0.05> generates many small
grains.
                                    
--------------------------
s_shield_intensity (float)
--------------------------
This is the intensity of the shield effect - higher values make the shield
colour more dominant in the effect. The default is 0.81. Note that setting
this to zero doesn't make the FLAT shield effect invisible.
                             
-----------------------------
s_shot_colour (colour vector)
-----------------------------                             
Specifies the colour regions of the shield surface adopt when 'hit'. The 
default is <1.2, 0.7, 0.7>, giving a reddish effect.

------------------------
s_shot_intensity (float)
------------------------ 
This is the brightness of the incoming fire. Higher values make regions
of the shield being 'hit' brighter, and makes the weapon colour more 
dominant in the shield effect.              
                                
-------------------
s_shot_dir (vector)
-------------------
Specifies the direction of travel of incoming fire. By default, incoming fire
is assumed to be travelling in the direction of the +ve z axis, <0, 0, 1>.
The s_shot_dir vector is used to calculate where the shot hits the shield.
                     
---------------------                     
s_turbulence (vector)
---------------------
Allows access to the turbulence in pigments applied to the shield, as in the 
absorption and hybrid shields. Just a turbulence vector. The default is 
<0.4, 0.4, 0.4>.
           

Section 4 - Preset Shield Types
===============================

  There are seven preset shield styles in version 1 of the SGIF. They control the appearence of
the shield surface. To choose a preset shield, use the s_shield_style parameter:

#declare s_shield_style = "distortion"

This tells the SGIF to create a distortion shield. The shield name can be in lower or upper case.

FLAT SHIELD (flat):
This is the simplest style. When hit, the shield sphere is given the weapon's colour at the impact 
point of the shot. This is faded into the shield colour at points further away from the impact. No
texturing is done on the shield surface. Since the shield surface is not broken up by a texture, the
edge of the shield sphere is very sharp, and looks ugly. This style is perhaps most useful as a 
'preview' style to get shield sphere placing and scaling correct because it renders fastest.


ABSORPTION SHIELD (absorption):
Similar to the FLAT style, but with a pattern overlaid on it. The pattern appears where the weapon 
colour did in FLAT, and fades out the further from the impact point you get. This shield is broken 
up by the texture, so it looks better than FLAT.


REFLECTION SHIELD (reflection):
This shield is again similar to FLAT, but instead of blending flat colours, it blends reflection 
colours. The shield is normally transparent, but when hit by a weapon, the affected area becomes 
mirror-like. The mirror colour is determined by the shield colour. This works excellently with 
varied backgrounds and it's definitely worth setting your space battles in a nebula ;-)  

HYBRID SHIELD (hybrid):
This is a combination of ABSORPTION and REFLECTION shields. It takes a long time to render, and is 
really only practical for still images rather than animations. 

DISTORTION SHIELD (distortion):
Although normal patterns will not normally work on a shield (see section 6), they will work if the
shield bubble is reflective (because the reflection angle depends on the surface normal). This 
shield adds a normal pattern (ripples) to the reflection shield type. It takes ages to render. You
can adjust the speed of the ripple motion via the x component of s_scramble, so that 
s_scramble = <4, 0, 0>; makes the pattern cycle four times while the shield is visible. 


RIPPLE SHIELD (ripple):
This shield is similar to the absorption shield, but has a ripple pattern instead of the bozo pattern.
The result is a set of coloured ripples that move across the shield surface. The speed of ripple motion
can be adjusted by the x component of the s_scramble parameter, as for the distortion shield above. 


LIGHT (light):
I use this to simulate a shield failure - it's the latest preset shield, and
needs some tweaking. Looks like spherical lightening.

Section 5 - Adding your own shield
==================================

  You can add a shield to the SGIF by editing two files. First you will need to
  create a file containing the texture information describing your shield. Your
  file should create a texture called s_shield_texture:

#declare s_shield_texture = texture {
                                     pigment {           
                                              gradient y
                                              pigment_map {
                                                           [0.00               damaged_shield_texture]
                                                           [(s_coverage*decay) normal_shield_texture]                                     
                                                          }
                                             }
                                     
                                     finish {..}
                                    }

  Most of the shields blend two pigments, but some blend textures (like the REFLECTION shield). Because of 
the way the SGIF works, you will need to use gradient y as the blending pattern if the 'hot' areas of
the shield are to fade to the normal (transparent) shield texture properly.                            
  If you want to avoid problems with lights interfering with the shield, set diffuse = 0.0 in the finish
statement. For examples see any of the shield files that come with SGIF. Note that you can also set the
interior of the shield bubble, by putting these lines in your file

#declare s_spatial = true;    // tells SGIF to use this interior statement

#declare s_shield_interior = interior {
                                       ...
                                      } 

This interior will then be used by the SGIF. A shield using an interior will show normal patterns properly 
if you set the ior in the interior statement to anything other than 1.0. However, it will also badly 
distort the object inside the shield. See the distortion preset shield style for a different approach to 
getting normal patterns on shields.
  Now you have a file containing a custom shield texture (and optional interior). You must now edit the
main SGIF include file (shield.inc). Around line 120 of shield.inc, there are a series of strcmp() 
statements that determine which shield file to use from s_shield_style. Say your shield file is called
myshield.inc; all you do is add

#if(strcmp(s_shield_style, "bounce") = 0)    // bounce is a name for your shield, can be anything you want
#include "shield\myshield.inc"               // myshield.inc is the name of your custom shield file
#end

to shield.inc, and you can call your shield in a scene by setting s_shield_style to 'bounce'. Notice that
SGIF expects the custom shields to end up in a 'shield' directory under the POVRAY include directory. 
To see how the various parameters described in section 3 are used in a shield file, try looking through the 
.inc files that come with SGIF. Note that you can use sclock instead of clock in your files. sclock starts at
0 when the shield starts and ends at 1 when the shield ends (see s_cstart and s_cend in section 3).


Section 6 - SGIF Problems and help
==================================

----------------------------------------------------------------------------------------------------
POVRAY can't find any of the preset shield include files. Where are they?
----------------------------------------------------------------------------------------------------

Either they've been deleted somehow, or you unzipped SG.ZIP without preserving the directory structure.
SHIELD.INC looks for the preset shields in a directory called 'shield' under your POVRAY include 
directory. If you can't find this directory, then the shields have ended up in your include directory
itself. Make a 'shield' directory yourself and move the preset files there.

----------------------------------------------------------------------------------------------------
I've written a shield style using a normal texture, but I can't see the normal pattern on the shield
----------------------------------------------------------------------------------------------------

This is an irritating side effect of the shield's independence of external lighting. The preset 
shield styles all have diffuse lighting set to 0, preventing light sources interfering with the 
shield effect. Since normal textures work by modifying the surface normal of an object (not the 
actual object), the normal texture only shows up when illuminated by a light source. Because 
diffuse effects are switched off by the shield textures, you can put as many light sources in 
as you want without affecting the shield. Unfortunately, this also means you can't see normal 
textures. If you want, you can correct this by using some value for diffuse other than zero, 
but this will make the shield respond to external lighting as well. See the DISTORTION shield 
type for a way to use normal patterns with the shield.


----------------------------------------------------------------------------------------------
I get a warning message saying 'Shield xx not generated for this frame'
----------------------------------------------------------------------------------------------

This message tells you that the animation clock is outside the time range you set for shield xx, in other 
words, the shield effect has either finished or hasn't started yet. Shield ranges are controlled by the 
s_cstart and s_cend parameters described in section 3. Shields are numbered from 1 in the order they appear 
in your scene file. 
          
          
Section 7 - Feedback and legal information
==========================================

Any feedback would be appreciated, especially suggestions for improvement of SGIF. I can be contacted at

tomy@compsoc.man.ac.uk

For the latest version of the SGIF, as well as a gallery of images created using it, see my page at

http://www.schrodingers-cat.co.uk/graphics/graphics.html

SHIELD.INC, this documentation and the shield files provided with the SGIF are Copyright 2000 by Thomas D. 
York. Distribution or modification of the files provided is permitted and encouraged, as long as any 
modifications are documented and noted as such in this file by the user making the modification, and the 
result is distributed under a different name to SG.ZIP. No other restrictions apply. 


