README.TXT file for LIGHT_I.PXP
A Shareware Lighting Utilities Program

To install LIGHT, copy the file LIGHT_I.PXP into your 3D Studio process
directory, typically C:\3DS3\PROCESS.  The program is accessible from the 3D
Editor by pressing F12 and choosing LIGHT from the list.

LIGHT provides the following functions: Light Style, Light Arrays, and Light
Delete By Name.

LIGHT STYLES:
  This function allows you to update existing lights in your scene with 
new properties.  To do this, modify an existing light using the
standard 3ds lighting adjust routines (Lights/Omni/Adjust, 
Lights/Spot/Adjust...  This 'Prototype Light' will function as the 
prototype for adjusting other lights.  Any or all properties of this light
may be assigned to any other light in the scene.  In this way, the 
'Prototype Light' defines a 'Light Style'.

To test it out, load the test drawing LT-TEST.3DS provided in the Zip file.

-Adjust one of the lights, perhaps changing its color and Multiplier status.
You might also turn it off, as this will make it easy to see the updated
lights.  Note the name of the light.  This will be your 'Prototype'.

- Run LIGHT from the PXP loader pulldown (or press F12).  The main menu will
come up.  Choose the Update radio button and then click "Next" or press ENTER.

- The 'Prototype for Update' dialog comes up, presenting you with a list of
existing lights in the scene.  Choose the light you just updated (the 
Prototype) and select "Next".

- Now the 'Choose the Lights to Update' dialog comes up.  This dialog is used
to tag lights you wish to modify.  You may tag/untag by 3 methods:
   1) Click on the name in the list.
   2) Use the Tag/Untag buttons with wildcard characters * and ?.  This will 
      tag/untag all lights that match the pattern.
   3) Use the 'Quick Find' feature.  Click in the CYAN window above the 
      Quick Find text. The window shows "----------" indicating you have not
      made a selection yet.  Type characters which uniquely identify light
      names in the list.  Quick Find will locate the first light in the list
      whose name matches the entire sequence you have typed so far.  When you
      have typed enough characters to locate the light you want, press the 
      Spacebar or ENTER and the light will be tagged (or untagged). 
      If you make an error and find an incorrect light, press ESC
      to start over.  You may also invoke the quick find from the keyboard
      by typing ~ (the tilde character).
Note: If you pick an Omni light as the Prototype, only Omni lights show up 
in the lights to alter list.  (Only lights of the same type are presented).

- Once you have selected all the lights to update, you are presented with
the 'Parameters to Copy from the Prototype' dialog.  Via buttons, select 
the properties of the prototype light you wish to copy to the lights you 
have tagged.  Any properties you select get copied to each previously 
tagged light.  Properties you did not select are left unaltered.

The options for Properties to Copy are:

[On/Off] -      If the Source if off, the tagged lights will be off.If the 
                source was on, the tagged lights will be on...
[Color] -       Color of light
[Exclude] -     Object Exclusion List
[Multiplier] -  'Brightness factor' of light
[Atten/Range] - Both Attenuation On/Off and light Range settings
[Location] -    X/Y/Z coordinate of source
[Shadows] -     All the shadow parameters: Cast Shadow On/Off, Mapped or
                Raytraced shadows, Bias value, Map size, Sample Range.
[Cone/Ho/Fo] -  Cone visibility, Hotspot angle, Falloff angle
[Target Pt] -   X/Y/Z location of spotlight target point of source.
[Rect/Circ] -   Shape of hotspot/falloff areas.
[Roll/Aspect] - Both the bank angle and aspect ratio.
[Overshoot] -   Overshoot On/Off
[Projector] -   Projector light On/Off and Image File (if On).

While in the dialog, if you forget the meaning of any of these, you can
use 3ds style Alt-Mouseclick help.  A brief message will popup describing
that button.  (This is also available on the main menu buttons.)

Note:  The Location parameter (and Target Pt for spotlights) control the 
actual X/Y/Z location of the light in the scene.  If you select one of these
options, all the tagged lights will be moved to the same location as the
Prototype.  At times this may be handy, but at times it may be disasterous.
You are given ample warning however!

Once you choose OK, and answer Yes to the confirmation prompt, all the tagged
lights are update with the parameters you've choosen.  Do a Lights/Omni(Spot)/
Adjust and check it out...
 
Two other functions are available which help support light styles:
Light Array, and Light Delete.

LIGHT ARRAY:
This function allows you to create both rectangular and polar (circular) 
arrays of lights.  

Choose the Array function from the main menu, and select the prototype light.
Again, this defines the style of all the created lights.  A dialog will be 
presented for both types of arrays.  Choose the Radio button which 
corresponds to the type of array you want to create. Note: This is fairly
easy to forget.  You may find yourself just filling in the parameters, so
be sure to check the type of array you want.

For rectangular arrays, you specify Width, Depth and Height
Counts.  These represent the number of lights along that dimension of the 
scene.  You also specify Width, Depth and Height Spacing.  This is the 
center to center spacing of the lights.  The following example coordinate
formats demonstrate what is available for the spacing parameters.

2        (This would indicate 2 of whatever units you are in (", ', CM or M))
2.0"     (2 inches...)
5'2"
5'2-3/8" (Seperate the fraction from the whole number with the '-' sign)
5/32'    (3ds's denominator is not relevent.  Use whatever you need).
525.125'

Polar arrays use a Source light at the Center of the array.  The created lights
are generated at a user defined plane and radius from this center point.
The dialog prompts for the following values: Number of items (total number of
lights to create), Radius (same formats as the spacing parameter described
above), Construction Plane (Top/Front/Side).  This parameter lets you array
the lights horizontally (Top plane), or vertically aligned with the Front 
viewport (Front plane), or vertically aligned with the Side viewport (Side 
plane).  The depth along the axis perpendicular to the plane is defined by
where the source lights is along that axis.  Thus, if you want to create
an array of lights parallel to the ground plane, 8' in the air, with 
an overall diameter of 40', you would create your prototype light 8' high,
and positioned wherever you need the center of the array.  Then specify
the Top plane and a radius of 20'0".  You are also able to enter a start
angle (0.0 degrees is to the right, along the horizontal axis).  Positive
rotation is counter clockwise.  The final parameter is Angle to Fill.  If 
set for 360 degrees, a complete circular array is generated.  For Spotlights,
you can select the Rotate Spotlights button.  If off, all the spotlights
retain their original orientation as they go around the circle.  If set to
On, all the spotlight targets point toward the source light location.  The
depth along the axis perpendicular to the construction plane is not altered.
Experiment a bit with this, and you'll see what happens!

For both rectangular and polar arrays, a name prefix is requested.  You may 
type up to 8 characters.  If you leave this field blank, the default prefix 
is the name of the Prototype light for the array.  All created lights are
named with the prefix and numbered sequentially.

LIGHT DELETE BY NAME:

This function uses the same 'Choose Lights' dialog box as described
above.  Choose the lights you wish to delete and press OK.  After a 
confirmation prompt, they are deleted.

SHAREWARE:

If you find this program useful to you, please register your copy.  Provide me
with your Name, Address and Compuserve User ID.  I'm keeping a database of
registered users and will inform those in the database when program updates
are available.  Except for any major bug fixes, I do not plan to post any
updated code, so if you want updates with new features, please register.

To register, send a check in the amount of $35.00 to:

Mark Meier
650 Hidden Valley #212
Ann Arbor, Michigan 48104

If you have ideas for new features or changes to existing ones, please
let me know.  Also, if you find any bugs, then certainly let me know!

Thanks and enjoy the program,

Mark Meier
CIS: 76330,3402
