C-Light Demo (Disk 87) (Jun 1988) : Documentation.txt


                           C-LIGHT
              Copyright © 1987 by Ronald A. Peterson


     The copy of C-Light contained on this disk is version 1.0
of a scene editor and ray tracing program.  For those
not familiar with ray tracing, it is a technique whereby very
realistic three dimensional pictures of objects can be created
by tracing the paths of rays of light through a scene.  The
unique features of C-Light include:

   * Full Intuition interface for ease of use.
   * Simple and quick scene creation using a powerful editor that lets you
     visually place objects.
   * Allows creation of scenes with up to 170 objects (spheres, cylinders
     and cubes) each of which can be sized, rotated and located
     independently in all three dimensions.
   * Allows any number of light sources (up to object limit
     of 170) with variable intensity and adjustable ambient light.
   * Supports overscanned and interlaced-overscan images as well as
     320 by 200 and 320 by 400 images, all in the standard IFF
     format.
   * Smoothly shaded objects with the color set selectable out of
     4096 possible colors.
   * Reflecting surfaces (mirrors).
   * Shadows.
   * Movable viewpoint (the observers eye.)
   * Easy editing of scenes both during and after creation.
   * Multitasking.

C-Light differs from other ray-tracers that have recently appeared
in that it is extremely simple to use.  It requires no knowledge
of three dimensional geometry (except that which you were born with)
and presents the user with an interface similar to that found in the
better paint programs available today.  In addition, C-Light can
easily produce smooth curved shapes such as spheres, ellipsoids,
and cylinders that are difficult to construct using polygon based
systems.
     C-Light is made up of several parts or modules.  The 
C-Light scene editor allows the user to create a three 
dimensional scene using simple primitive objects (currently spheres,
cylinders, and cubes.)  These objects can be interactively 
placed, stretched, shrunk and rotated using a very friendly mouse
oriented interface.  The C-Light ray tracer then takes this scene
description and calculates the resulting picture based on the 
locations of the objects, light sources, and eyepoint.  Both 
overscanned and PAL (European) formats are supported, with or 
without interlace.  These pictures can then be saved to disk as 
IFF picture files and viewed using the View utility which is 
provided.  All programs are multitasking and will use fast RAM in
place of chip memory where possible.

     This copyrighted version of C-Light is freely redistributable
so long as it is not sold for profit or modified in any way and is
accompanied by this text file which describes the software and its
source.  All rights are reserved and reside with its author, Ronald
A. Peterson.

     Since C-Light is a commercial product currently being 
marketed, this demo version is slightly limited in that the 
object editor will only allow the user to place ten objects in a 
scene.  Anyone wishing to purchase a complete copy (which allows 
placing up to 170 objects, includes complete documentation and is
not copy protected---as yet) can do so by sending $59.95 to:

                      Ronald Peterson
                      P.O. Box 614
                      Milford, NH  03055

     Since C-Light is being independently marketed (inquiries from
distributors are invited) please distribute this disk freely. 
Posting to bulletin boards is also encouraged so long as this 
text file remains with the software.  This version is already
available on BIX and PeopleLink.

 Formalities aside, here is a brief description of how to use C-Light:

     It is necessary to use V1.2 of Workbench with C-Light and a
Preferences setting for eighty column text is desirable.  C-Light
is a complex program; if run on a 512K Amiga, it will require almost
all memory to be available.  This means that you should have as few
windows as possible open and no other programs running.  On an Amiga
with more than 512K RAM, C-Light will gracefully multitask with only
one side effect---calculating an interlaced picture will cause all
screens to be interlaced.

C-Light makes extensive use of Intuition (gadgets, sliders, 
menus, etc.) which means many functions can be easily understood
just by trying the gadget or slider to see what it does.  The
programs can be run from Workbench or from CLI.  C-Light is in
two parts (C-LightI and C-LightII) and also includes two
utilities: Video and View.

*---VIDEO ---*

     Calling up Video allows you to select screen resolution and
PAL or USA compatability by responding to requestors which ask
yes or no questions about your choices.  (Note that Video has no
effect on pictures that have already been generated.)

*--- C-LightI ---*

     C-LightI is the scene editor.  Upon calling it up you will
see some gadgets on the right side of the screen and a title
bar.  There is a drag-down menu attached to the left side of the
title bar.  This is the utilities menu which contains the
following functions:

      Hide Title Bar - Hides/restores the title bar.
      Hide Selectors - Hides/restores the gadgets on the right.
      New Directory  - Change directory (drawer) or disk.
      Colors         - Lets you change the CURRENT screen colors,
                       not the colors used in the scene.
      Reset All      - For starting a new scene.
      Load file      - Load in a scene file.
      Save file      - Save a scene file.
      Exit           - Go have a look in the fridge.

Most of these menu selections call up requestors. The use of these
requestors conforms to the rules outlined in the "Introduction to Amiga"
manual.  Try loading in and playing with the example scene file
included on the disk which is entitled "Columinaire".

  The function of the gadgets on the right side of the
screen will be covered next:

BALL, CUBE, CAN - When clicked on, these gadgets will cause an 
outline (wireframe image for the technical among you) of the 
corresponding object to appear.  Using the mouse you can move the
object left/right or up/down.  By clicking the right mouse button
(when the cursor is NOT over the title bar) the object can be 
moved in/out in depth with the mouse instead of up/down.  
Clicking the right button again will restore up/down movement.  
Because the space in which you are moving the object is much 
larger than the screen of the Amiga, the object does not follow 
the cursor position.  For example, if the object is in the center
of the screen and the cursor is on the right edge of the screen, 
you can keep moving the mouse to the right (picking it up and 
moving it, picking it up and moving it, ...) and even though the 
cursor doesn't move, the object will keep moving to the right 
eventually going off the screen.  A mouse is inherently a device 
for manipulating two dimensional objects so this is how I turn it
into a 3D manipulator.  You can think of the object being moved 
as a new, three dimensional cursor for the mouse if you like.
     As you are moving the object around you will see the X, Y, Z
coordinates of the CENTER of the object being displayed in screen
coordinates.  Once you have the object somewhere near where you 
want it, click the left mouse button and the Object Modification 
Requestor will appear.  (Fancy name eh?  I thought that one up 
myself.)  The sliders on this requestor let you change the size 
of the object in the X, Y and Z directions and allow you to 
rotate the object around the X, Y and Z axis.  The gadgets 
labeled A, B, C, M let you pick the color for the object.  
I will discuss later how to set these colors to whichever out of
the 4096 possible colors that you choose and how to set
the background color for a scene.  The "M" gadget makes the
object have a mirror (almost perfectly reflecting) surface.
     Hit the CANCEL gadget if you decide you don't want the
object.  The requestor can be moved by dragging it via its
title bar.  You can still move the object around when the object
modification requestor is present by clicking with the left mouse
button anywhere outside the requestor.  The requestor becomes 
inactive and you can then move the object around using the mouse,
just as you did before the requestor appeared.  Clicking the left
button again activates the requestor again and stops the object 
from moving when you move the mouse.  In this way you can 
alternate between moving the object and sizing or rotating it 
until you have it exactly as you want it.  Then, hit the close 
gadget in the upper left corner of the requestor and the 
requestor will disappear and the object will change color 
indicating that it has been set in place.

DEL, CHG - Once you have placed an object you can still change 
it.  Hit the DELete gadget and then click on the CENTER of the 
object you want to delete with the left mouse button.  The object
will be highlighted in a different color and a requestor will ask
if this is the object you really want to delete.
     The CHG gadget works in a similar fashion.  Hit CHG, then 
click on the object you want to change.  It will be highlighted 
in a different color and the object modification requestor will 
appear.  From then on you can treat everything just as though you
were placing the object for the first time.

VIEW - Once you have defined a scene you can use this gadget to 
move, rotate, stretch or shrink the scene as a whole.  Click on 
it and you will see the scene disappear, then a cube and the 
object modification requestor take its place.  Imagine your scene
is inside this cube.  You can then rotate it, move it, and size 
it.  Hitting the close gadget on the requestor will cause the 
scene to be redrawn using the new view.  This is also useful for
rotating a scene to get at and change the parts of it that are in
back of other objects.

EYE - This allows you to set how close or far the observers eye 
is from the scene.  It uses the object modification requestor 
again and works just like moving your own eye nearer or further 
from a window (the screen of your monitor being the window.)  As 
you move closer to the window you can see more of the scene.  It 
also becomes more distorted by perspective (an effect like a fish
eye lense on a camera.)  As you move further away you can see 
less of the scene through the window and things become less 
distorted and more natural looking.  Currently the eye point can 
only be moved closer or further away; I may add up/down and 
left/right movement to it if it seems useful.  Clicking on the 
close gadget will cause the scene to be redrawn using the new 
eyepoint.

COLR - This gadget calls up a requestor that allows you to change
the color of the OBJECTS.  It does not affect the current colors 
used on the screen.  This is where the colors A, B, C and the 
background color are determined.  The colors you pick for A, B, 
and C are the colors that will be used in your object at its 
brightest spots.  The brightest spots will be those closest to 
the light sources.  The rest of the object will be in blacker
shades of this color, getting dimmer the further that part of the
object is from the light.  (Just like in real life!)

LITE - This gadget allows you to place light sources in your 
scene.  A light is treated just like an object (BALL, CUBE, CAN)
and is placed in the same way.  Sizing and rotation of light 
sources has no effect on the picture.  Lights are point sources 
that radiate in all directions.  The only limit on the number of 
light sources is the limit on the total number of objects (10 for
this demo version, but then there would be no room for objects.) 
More lights means a longer calculation time though.

*--- C-LightII ---*

     Once you have created a scene and saved it to disk, the 
second part of the program comes into play - C-LightII.  
C-LightII is the part that actually draws the scene.  Ray tracing
is a complex mathematical process so this can take some time - 
from a half hour up to several days.  When you call up C-LightII 
you will see a requestor.  Hitting "Get File" calls up a 
directory requestor that allows you to select the scene you want 
to calculate.  After picking a scene you can set some of the 
overall characteristics of the scene with the sliders and 
gadgets:

LIGHT slider - This sets the intensity of all the lights in a 
scene.  The number displayed near the slider is the range at 
which the lights will be at half intensity.
AMBIENT slider - This sets the background level of light that 
illuminates ALL objects equally.
BLEND slider - This one controls how much blending together of 
colors occurs.  Given ten shades of each color with which to shade
an object, randomly blending them a little makes the picture
look smoother.  Too much and your picture will be lost in fuzz.
Too little and you will see bands of color.
ALIAS gadget - Turning this on enables anti-aliasing.  This is a 
simple algorithm that tries to lessen the effects of jagged edges
(caused by the fact that the screen is made up of a limited 
number of rectangular dots.)  It doesn't always improve the picture.
SHADOW gadget - Turning this gadget on will cause shadows to be 
calculated for the scene.  Shadows are VERY time consuming and 
can easily cause a complex picture to take days to calculate,
particularly if there are many light sources.
SAVE gadget - This allows you to name and save the created 
picture as an IFF file.  The save requestor will come up 
automatically when the picture is done.
     You can get back to the main requestor at any time (in order to
exit, change settings or save an unfinished picture) by clicking
once with the left mouse button anywhere in the lower three quarters
of the screen.

*--- VIEW ---*

     Finally, the VIEW program is an IFF picture viewer that 
allows you to look at the saved IFF picture files (overscanned 
ones too!)  To view a picture from Workbench you can either just
double-click on the pictures icon or click once on the 
pictures icon while holding down the left Amiga and Shift keys 
simultaneously, then double click on the View icon.  From CLI you
can type: VIEW 'picture' where 'picture' is the name of the file
you want to see (without the '.ilbm' extension.)  Click anywhere
in the upper left corner to end it.

     So...that should be enough to get you started.  I have tried
to make this program as simple to use as possible, modeling it 
after paint programs like DeluxePaint.  In fact, because shading 
is a tough thing to do with a mouse, C-Light makes a nice 
addition to paint programs since it lets you easily create 
backgrounds of shaded 3D objects.  Have fun with this demo 
version and if you like it, send a check my way and tell a friend
about it!

     Let me know of any bugs that you find and I will correct 
them and repost a new demo version (and maybe send you a free 
copy of C-Light if you find something serious.)  Also, not having
a European Amiga, I have not been able to test overscan while in 
PAL mode.  I would appreciate knowing if it works.  Future 
enhancements will be offered for a small fee to registered users 
and will include:

     More object primitives - Cones, Half spheres, Trapezoidal
         patches.
     Specular reflections (glossy surfaces)
     Better memory management.
     Animation editor & viewer - for making short, animated
        movies on the Amiga (in the ANIM format) or long animated
        movies on film or video tape.



Amiga, Workbench and Intuition are trademarks of Commodore-Amiga,
Inc.
DeluxePaint is a trademark of Electronic Arts.