====================================================================
Program Name:   3D BILLBOARD
Platform:       Java Applet
Author:         Shahad N Ahmed
Version:        1.01b
Price:          Freeware - If you like the applet then send me an
                           Email.
====================================================================

If you want to be kept informed of new special-effects for 3D-
BillBoard then send email to: billboard@albanet.demon.co.uk
Your email address will NOT be passed on to any other companies, or 
third party.

You can also check out my latest Java creations, most of which are 
freeware, at: http://www.albanet.demon.co.uk/java.html

IMPORTANT: Before using 3D BillBoard, please read the Licence 
conditions at the end of this document.


------------
0.  Contents
------------

1.  Introduction
2.  Some Features of 3D BillBoard
3.  Setting up 3D BillBoard
4.  Using 3D BillBoard in Your HTML Documents
5.  Parameter descriptions
6.  Known Issues
7.  Support Details
8.  Revision History
9.  Licence



---------------
1. Introduction
---------------

3D BillBoard was written to provide a fast and efficient means of 
producing 3D animated advertisements for the web. 

Simply supply a list of images you want to display in sequence, and 3D 
BillBoard produces an animation that rotates each image about the 
horizontal axis. As one image rotates out of view, the next image 
rotates into view.

As well as rotating images about an axis, the user can choose from a 
number of other exiting transitions between images.


Acknowledgements:
This applet was produced as an exercise whilst experimenting with 3D 
image manipulation, and perspective, in Java. The idea for 3D 
BillBoard was inspired by Robert Temples excellent Dynamic BillBoard 
applet (available from http://www.db.erau.edu/java/billboard). 
Therefore, I do not take credit for the idea of producing an animated 
Java billboard. Robert was kind enough to supply the source code for 
Dynamic BillBoard and I acknowledge the use of several ideas taken 
from his code. For example, 3D BillBoard uses many of same parameters 
as Dynamic BillBoard. I have also used Roberts idea of passing a list 
of transition names as parameters, so that new transitions can be 
plugged into the applet. Unfortunately, I could not incorporate my 3D 
rotational effects into new transitions for Dynamic BillBoard; my use 
of perspective effects requires images to be scaled differently to the 
scaling used in Dynamic BillBoard. Hence, the reason for writing 3D 
BillBoard.

3D BillBoard was developed using Symantec Caf Version 1.5.




--------------------------------
2. Some Features of 3D BillBoard
--------------------------------

(1) Interactive Advertisements
You can associate a URL (that is, a web link) with each image, so that 
clicking on an image links users to new web pages, email, sounds, 
movie clips etc.

(2) Utilises the space on your web pages to the fullest extent.
3D BillBoard makes an excellent advertising tool by allowing you to 
advertise many products in a single area of a web page.

(3) Make animated adverts quickly:
To generate animated GIFs similar to the animations produced by 3D 
BillBoard requires knowledge of 3D Rendering and Paint applications. 
With 3D BillBoard you supply the key images you want to display and 
let 3D BillBoard produce the 3D animation - Automatically.

(4) Change your adverts quickly:
If you want to change your animated adverts, then simply change the 
list of images and let 3D BillBoard do the rest.

(5) Fast download of advertisements to customers visiting your 
website:
Consider an advert constructed from 4 key images each 4K bytes in 
size. The resulting animation produced by 3D BillBoard contains 32 
frames.

   Size of 3D BillBoard animation downloaded to customer
      4 * 4K key images    = 16K bytes
      3D BillBoard applet  = 28K bytes
                             ----------
                    total    44K bytes


  Size of equivalent animated Gif downloaded to customer
     32 * 4K per frame     = 128K bytes

(6) 3D BillBoard displays the first key image as soon as it is 
downloaded; you do not have to wait for all the key images to be 
downloaded before an image appears. Therefore, your valuable web 
advertising space is being utilised to the fullest extent.

(7) The modular design of 3D BillBoard means that new transition 
special-effects can be plugged into 3D BillBoard as they become 
available.



--------------------------
3. Setting up 3D BillBoard
--------------------------

3D BillBoard is supplied in a Zip file called bb101.zip.

1. Unzipping bb101.zip creates a new folder called billboard. billboard 
contains a folder named classes, together with an example HTML 
document called Billdemo.html and this ReadMe file. The contents of 
classes is as follows:

Classes: BarTransform.class, Bill.class, BillBoard.class, 
BillTransformation.class, RollForwardTransform.class, 
RollingTransform.class, RollSpinTransform.class, RollTransform.class, 
RotateTransform.class, SpinningTransform.class, SpinTransform.class, 
StaticTransform.class, WaveLeftTransform.class, 
WaveRightTransform.class, WhipTransform.class.

Classes also contains a folder called images which should contain the 
following graphics files.

Images: bb.gif, bbc.gif, clear.gif, glencoe.jpg, logo.jpg, 
newscentre.gif, snownet.jpg, sun_ad.gif

2. The file Billdemo.htm and the files in the images folder are all 
part of the 3D BillBoard demonstration. If you wish, you can run the 
demonstration by opening Billdemo.html in your favourite Java aware 
web browser, such as Netscape version 2.0 and above; and Microsoft 
Internet Explorer version 3.0 and above. If you are using Netscape 
then I strongly recommend versions 3.0 and above -- earlier versions 
of Netscape contain some bugs in their implementation of Java. If you 
have problems running the demonstration using Internet Explorer 
versions 3.02 or 4 beta then please see the Known Issues (Section 6) 
below. If you no longer require the demonstration of 3D BillBoard then 
you may delete file Billdemo.html and the folder named images.

3. The folder named classes contains the implementation of the 3D 
BillBoard applet. The applet is called BillBoard.class (I would have 
called it 3DBillBoard.class, but class names cannot start with a 
number). The implementation uses several other Java classes, all of 
which appear in folder classes.

IMPORTANT: The files in the folder named classes should not be 
separated. If you wish to move BillBoard.class to a new folder then 
all the other files in classes must also be moved to the new folder, 
otherwise BillBoard.class may not run.



--------------------------------------------
4. Using 3D BillBoard in Your HTML Documents
--------------------------------------------
 
Use the APPLET tag to add 3D BillBoard to your HTML documents. Here is 
an example call to applet BillBoard.class (3D BillBoard):

<APPLET 
CODE="BillBoard.class" 
CODEBASE="classes" 
ALIGN=RIGHT 
WIDTH=200 HEIGHT=43>
<param name="bills" value="4">
<param name="bill0" value="hello.gif,http://www.albanet.demon.co.uk">
<param name="bill1" value="stuff.gif,my_stuff.html">
<param name="bill2" value="logo.gif,http://www.company.com">
<param name="bill3" 
value="image.gif,http://www.your_company.com/welcome.html">
<param name="img-width" value="200">
<param name="img-height" value="30">
<param name="delay" value="2000">
<param name="background" value="#FFFFFF">
<param name="transparent" value="on">
<param name="store" value="1">
<param name="transformations" 
value="WaveTransform,WhipTransform,RollTransform,RollSpinTransform">
<param name="sequence" value="2,3,1,4">
<param name="side_width" value="5">
<param name="side_colour" value="#000000">
</APPLET>

The above example uses four (key) images (hello.gif, stuff.gif, 
logo.gif and image.gif) to produce an animation. Clicking on hello.gif 
causes a jump to http://www.albanet.demon.co.uk; clicking on stuff.gif 
causes a jump to the document my_stuff.html which we will assume is a 
local HTML document; clicking on logo.gif causes a jump to 
http://www.company.com; and clicking on image.gif causes a jump to 
http://www.your_company.com/welcome.html.

The parameter CODE sets the applet to be run: in this case 
BillBoard.class (i.e. 3D BillBoard). Parameter CODEBASE is a path to 
the folder in which BillBoard.class is stored. The path is set 
relative to the location of the HTML document in which the Applet tag 
is used; in the above example, BillBoard.class is stored in folder 
classes which in turn is stored in the same folder as the example.

The parameters WIDTH and HEIGHT set the width and height, 
respectively, in pixels, of the area in which the applet may appear. 
If WIDTH and HEIGHT are set too small then parts of the animation may 
be clipped; similarly, if they are set too large then an unnecessarily 
large part of your web page will be left blank. To help you set the 
optimum WIDTH and HEIGHT values, 3D BillBoard outputs recommended 
WIDTH and HEIGHT values, for the your chosen key images, to the Java 
Console. In Netscape 2.0, and above, the contents of the Java console 
are displayed by selecting "Show Java Console" from the "Options" 
menu; In Microsoft Internet Explorer 3.0 (for Windows 95) the output 
to the Java Console can be found in the file javalog.txt which is 
usually stored in the folder c:\Windows\Java.

A detailed description of all the parameters of 3D BillBoard is given 
below.



-------------------------
5. Parameter descriptions
-------------------------

This section lists the 3D BillBoard applets parameters. For each 
parameter, we define its legal values, and how it affects the applets 
behaviour.

Name: bills
Type: Integer, greater than 0. Default = 1
Description: Specifies the number of (key) images to be downloaded by 
the applet.


Name: bill# (where # is an integer in the range 0 to bills-1 
inclusive. For example, if bills=4 then the applet must have 
parameters named bill0, bill1, bill2 and bill3)
Type: String 
Description: bill# is a string representing a URL to Key image #. 
Optionally, you may add a second URL to the end of the first URL, 
separating the two with a comma (,); no spaces allowed on either side 
of the comma. The second URL is a link jumped to whenever a users 
clicks on the image specified by the first URL. If the first URL (to 
the key image) contains a syntax error, or if the image cannot be 
found, or loaded, then the "Title" image is used. If the second URL 
(the link associated with the image) is incorrect, then it is ignored.
Example: Given bills=2 then we must include two parameters, bill0 and 
bill1, that supply the locations of 2 key images. For example:
    <param name="bill0" 
value="hello.gif,http://www.albanet.demon.co.uk">
    <param name="bill1" 
value="your_add.gif,http://www.your_company.com">
The above example specifies 2 key images (hello.gif and your_add.gif) 
together with URLs http://www.albanet.demon.co.uk and 
http://www.your_company.com for each image, respectively.



Name: delay
Type: Positive integer, including 0. Default = 2000
Description: Delay in milliseconds between transitions from one key 
image to the next in the animation. In other words, its the time that 
a key image remains on the screen before the next key image starts to 
rotates into view.


Name: img-width
Type: Positive integer, including 0.
Description: All key images are scaled to this width. If the img-width 
parameter is not supplied then the default width is the width of the 
first key image (specified by bill0). In addition, see the section 
titled "Using 3D BillBoard in Your HTML Documents" (above) about 
important information on setting an optimum applet width and height.


Name: img-height
Type: Positive integer, including 0.
Description: All key images are scaled to this height. If the img-
height parameter is not supplied then the default height is the height 
of the first key image (specified by bill0). In addition, see the 
section titled "Using 3D BillBoard in Your HTML Documents" (above) 
about important information on setting an optimum applet width and 
height.


Name: transformations
Type: String consisting of names separated by commas (,); no spaces on 
either side of commas.
Description: Each of the special-effects (transitions) that transform 
one advertisement to the next has a name. If you wish to use a 
transition then its name must appear in the transformations list; the 
default transition, RollTransform, does not have to be added to the 
transformations list. The current distribution of 3D BillBoard comes 
with the transitions described below:

   BarTransform: Divides an image into vertical bars and rotates all 
the odd bars in unison; and then rotates all the even bars in unison. 
   RollForwardTransform: Rotates the current image (about the 
horizontal axis) towards the observer as the next image appears from 
above. 
   RollSpinTransform: Rotates the current image (about the horizontal 
axis) away from the observer; the next image appears to be on the back 
of the previous image.
   RollTransform: Rotates the current image (about the horizontal 
axis) away from the observer as the next image appears from below.
   StaticTransform: Changes the current image to the next image 
instantaneously.
   WaveLeftTransform: Causes a rotating wave, from left to right, that 
eventually flips the entire image over to the next image.
   WaveRightTransform: Causes a rotating wave, from right to left, 
that eventually flips the entire image over to the next image.
   WhipTransform: The next image slides in horizontally to cover the 
current image.

Example: To make an advertisement that uses the RollTransform and 
RollForwardTransform together with the WaveLeftTransform and the 
WaveRightTransform, you must define the transformations parameter as:
   "RollForwardTransform,WaveLeftTransform,WaveRightTransform"
Note that RollTransform does not need to appear in the list as it is 
the default transform. You may list the transitions in any order.
The transformations parameter provides a means of "plugging" new 
transitions into 3D BillBoard as they become available in the future.


Name: sequence
Type: String of integers separated by commas (,); no spaces on either 
side of commas.
Description: This parameter specifies the sequence in which 
transitions are used in an advertisement. The user specifies the order 
in which transitions are used as a sequence of integers, where each 
integer uniquely identifies a transition in the transformations list. 
The integer identifier of each transition is its position in the 
transformations list; we assign 1 to the first transition in the list, 
2 to the second, etc. The default transition, RollTransform, always 
has the value 0. There is no limit on the size of the sequence list, 
and each transition can be used more than once. 3D BillBoard applies 
the transitions specified in the sequence in the order in which they 
appear in the sequence. 3D BillBoard repeats the sequence ad 
infinitum. If the user does not assign a value to the sequence 
parameter then 3D BillBoard chooses the sequence of transitions at 
random from the transformations list.
Example: Consider the following transformations list:
   "RollForwardTransform,WaveLeftTransform,WaveRightTransform"
A sequence value of 
   "2,1,1,3,0,0"
specifies an animation sequence consisting of a WaveLeftTransform 
followed by 2 RollForwardTransfoms followed by a WaveRightTransform, 
followed by 2 RollTransforms.


Name: store
Type: Positive integer, including 0. Default = 0.
Description: 3D BillBoards default behaviour is to discard, from 
memory, the animation transition between the previously displayed 
image and the current image. However, through the store parameter, the 
user can specify that animation transitions are stored in memory so 
that, when the transition repeats, it can be fetched from memory 
rather than be recalculated. Animation transitions are stored in 
multiples of the value of parameter "bills". Therefore, if bills=4 
then a store value of 1 stores the first 4 transitions between the key 
images; a store value of 2 stores the first 8 transitions etc. The 
transitions stored in memory are repeated ad infinitum. This last 
point is important as it means that the transition sequence specified 
by the parameter "sequence" may be overridden; for example, if 
sequence="3,3,2,1,4,5,2,2" and you specify store=1 when bills=4 then 
3D BillBoard stores, and displays, the first four transitions in 
sequence (i.e. 3,3,2,1). In this example, the user can display all the 
transitions in the sequence by assigning store the value 2. A store 
value of 0 specifies that no transitions are to be stored in memory.

Name: transparent
Type: String. Either "on" or "off". Default is "on".
Description: If transparent="on" then 3D BillBoard use an animation 
technique known as double-buffering. This technique reduces animation 
flicker, but may slow down animation on a slow machine. 
IMPORTANT: Set transparent="on" if some of your key images are 
transparent GIF images, otherwise they may not be displayed properly.


Name: background
Type: 6 Digit Hexadecimal. Default = #FFFFFF (white)
Description: Sets the background colour used by 3D BillBoard. A colour 
is specified by its hexadecimal RGB value. In HTML a colour is 
specified by a hexadecimal red-green-blue triplet of the form #rrggbb 
where rr, gg and bb are hexadecimal value in the range 00 to FF 
representing the red green and blue components of the colour, 
respectively. You may prefix the hexadecinal RGB value with an 
optional # or & symbol to indicate it is a hexadecimal value. Here are 
the hexadecimal RGB representations for some colours:

    Colour   Hexadecimal RGB representation
    ---------------------------------------
    white  = #FFFFFF
    black  = #000000
    red    = #FF0000
    green  = #00FF00
    blue   = #0000FF
    ---------------------------------------


Name: side_width
Type: Positive integer, including 0. Default side_width=5.
Description: Some transformations, such as RollSpinTransform, display 
the side or bottom edge of an image during a transition. The parameter 
side_width sets the width of the bottom and side edges, in pixels. If 
side_width=0 then no edge is displayed.


Name: side_colour
Type: 6 Digit Hexadecimal. Default = #000000 (black)
Description: The parameter side_colour sets the colour of the side and 
bottom edge of an image. Colours are represented by a hexadecimal RGB 
value; see the description of the parameter "background" (above) for a 
description of hexadecimal RGB values.



---------------
6. Known Issues
---------------

The "Title" image - i.e. the image that appears while the first key 
image  downloads  is not always displayed properly under Netscape 2.0 
and 2.01. As far as I know, this is due to a bug in the implementation 
of Java in Netscape 2.0.

Some transparent Gifs cause 3D BillBoard to clip all the images in an 
animation. This problem is under investigation.

If some of your key images have been replaced in the animation 
sequence by the 3D BillBoard Title image then 3D Billboard was unable 
to download the images from your specified URL. 3D BillBoard sends a 
lists all images that fail to load to the Java Console; see the end of 
Section 4 for details on accessing the Java Console. Here are some 
possible causes of this problem:

   1. the URL you specified for the image may have a syntax error in 
it; check the bill# parameter (where # is the number of the image). 
Please remember that many Unix web servers are case sensitive. For 
example, if you specified an image URL as IMAGE.GIF, and it is stored 
on your web server as image.gif, then it will not be downloaded. Note 
that the case sensitivity also applies to file suffixs (gif, jpg, 
etc.). Some paint packages store files with capitalised file suffixs 
(e.g. .GIF, .JPG); other packages, such as Photoshop, use lowercase 
suffixs. It is a common mistake for a user to specify an image URL 
with a lower case suffix, such as image.jpg, when the file actually 
has an upper case suffix, such as image.JPG.

   2. The web server that stores the image may be unavailable, or 
busy. There is little you can do about this error except contact the  
web server support staff.

   3. The file type of the image may be incompatible with Java. 
Currently, Java only supports GIF and JPG image files.


Some JPG files appear as blank images. 3D BillBoard may report a Bad 
JPGFileFormat Error to the Java Console. I have come across several 
JPG files on the web that cause this error. These JPG files seem to 
contain extra data. As a result, Java does not load these files 
correctly. I have found that loading these files into a graphics 
package, such as Photoshop, and then saving them again solves the 
problem; the extra data seems to be removed by this process.


3D BillBoard leaves grey edges on the bottom and/or the right of the 
animation. This occurs if the WIDTH and HEIGHT values in the APPLET 
tag are larger than the recommended WIDTH and HEIGHT values displayed 
by 3D BillBoard in the Java Console. This is not an error but a design 
decision. For efficiency, and hence the best animation performance, 3D 
BillBoard only updates that part of the applet area containing the 
animation. Hence, the rest of the applet area will contain the 
ubiquitous grey applet background. To solve this problem, run 3D 
BillBoard and then change the WIDTH and HEIGHT parameters of the 
APPLET tag to the recommended values output by 3D BillBoard on the 
Java Console. See the end of Section 4 for details on accessing the 
Java Console.

Problem: 3D Billboard fails to run from your local hard drive under 
Microsoft Internet Explorer version 3.02, or 4.0(Beta). 
Symptom: The green 3D Billboard splash screen is displayed, but no 
advertisements are displayed.
Cause and Solution: After discovering some security problems with 
Internet Explorer 3.01, Microsoft released version 3.02 to address the 
problems. Unfortunately, there is a problem with the security model in 
the Java Virtual Machine (VM1516) supplied with IE 3.02 and 4.0 beta. 
It prevents Java applets reading files from the local hard disk unless 
you are connected to the Internet. Microsoft realised that this was 
causing Java developers a great deal of inconvenience, since it made 
it difficult to test new applets locally. Therefore, they released a 
fix which loosened the security model in VM1516. This fix is available 
at http://www.microsoft.com/java in the form of a new virtual machine 
VM1518. However, although VM1518 allows you to run an applet locally, 
any files used by the applet (such as graphics files) must be in the 
same folder as the applets class file, or in a sub-directory of the 
folder containing the applets class file. This last condition is new 
to VM1518; version of the VM prior to VM1516 did not have this 
restriction.




-------------------
7. Support Details
-------------------

If you have any problems with 3D BillBoard then please read section 6, 
"Known Issues", as somebody else may already have reported the 
problem. 

If you have any comments about 3D BillBoard then send them to the 
following Email addresses:

Email: billboard@albasoft.co.uk
Email: billboard@albanet.demon.co.uk

These, and other contact details are also available on my web pages:

http://www.albanet.demon.co.uk

I will try and answer your questions, time permitting. But please 
remember that 3D BillBoard is a Freeware product. Any support I give 
is done in my spare time; and out of the goodness of my heart.



--------------------
8. Revision History
--------------------

Version 1.00b updated to 1.01b on 26 February 1997
New Features: background and side_colour parameters must now be 
specified as hexadecimal RGB values (see description of these 
parameters in section 5). This change was made so that the method of 
specifying colours in 3D BillBoard is the same as that used in HTML.




-----------
9. Licence
-----------

This 3D BillBoard Software is owned by Shahad N. Ahmed, herein 
referred to as the "owner".  The owner grants to the user a 
nonexclusive license to use this 3D BillBoard Software.  The user may 
not commercially distribute, sublicense, resell, or otherwise transfer 
for any consideration, or reproduce for any such purposes, the 3D 
BillBoard software or any modification or derivation thereof, either 
alone or in conjunction with any other product or program. The user 
may distribute the 3D BillBoard software for non commercial purposes, 
provided that this licence is included with the distribution.

THIS 3D BILLBOARD SOFTWARE IS PROVIDED TO THE USER ''AS IS.''  THE 
OWNER MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO 
THIS 3D BILLBOARD SOFTWARE AND/OR ASSOCIATED MATERIALS PROVIDED TO THE 
USER, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF MERCHANTABILITY, 
FITNESS FOR A PARTICULAR PURPOSE OR AGAINST INFRINGEMENT. THE OWNER 
DOES NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE SOFTWARE WILL 
MEET YOUR REQUIREMENTS, OR THAT THE OPERATION OF THE SOFTWARE WILL BE 
UNINTERRUPTED OR ERROR-FREE, OR THAT DEFECTS IN THE SOFTWARE WILL BE 
CORRECTED.  FURTHERMORE, THE OWNER DOES NOT WARRANT OR MAKE ANY 
REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE OF THE 
SOFTWARE OR ANY DOCUMENTATION PROVIDED HEREWITH IN TERMS OF THEIR 
CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE.  NO ORAL OR WRITTEN 
INFORMATION OR ADVICE GIVEN BY THE OWNER OR AN OWNER AUTHORIZED 
REPRESENTATIVE SHALL CREATE A WARRANTY OR IN ANY WAY INCREASE THE 
SCOPE OF THIS WARRANTY.

LIMITATION OF LIABILITY - THE OWNER IS NOT LIABLE FOR ANY CLAIMS OR 
DAMAGES WHATSOEVER, INCLUDING PROPERTY DAMAGE, PERSONAL INJURY, 
INTELLECTUAL PROPERTY INFRINGEMENT, LOSS OF PROFITS, OR INTERRUPTION 
OF BUSINESS, OR FOR ANY SPECIAL, CONSEQUENTIAL OR INCIDENTAL DAMAGES, 
HOWEVER CAUSED, WHETHER ARISING OUT OF BREACH OF WARRANTY, CONTRACT, 
TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, OR OTHERWISE.

16 June 1997
