What is CoolTitle?
------------------

	CoolTitle is a simple perl script that front-ends POV-Ray to
generate cool 3D text as seen at "Jim's Cool Icons"
(http://snaught.com/JimsCoolIcons/).  CoolTitle generates a customized
POV-Ray scene, renders it, and post-processes the resulting image to
produce a set of JPEG image files of various sizes.  All in one "swell
foop" from a simple command line interface.

	The core of CoolTitle is a simple POV-Ray scene file.
CoolTitle simply automates the tedious task of customizing and
rendering this scene file.  By automating this task, it is very easy
to create a large set of title graphics for a website with very
consistent results.

	CoolTitle is copyrighted by Jim Evins, evins@snaught.com.  It
is released under the terms of the GPL.  See COPYING for more
information.

	Check http://snaught.com/CoolTitle/ for updates.


CoolTitle Prerequisites
-----------------------
First you will need POV-Ray (x-povray).  The script has been tested
with version 3.1g.  POV-Ray can be downloaded from the official
POV-Ray website (http://www.povray.org/).

In addition to POVRay you will need the following installed on your
system:

	Perl version 5 (only tested on 5.005)

	cjpeg and wrjpgcom (clients from libjpeg version 6b)

	pnmscale and pnmnlfilt (from libgr-progs version 2.0.13,
	  			also in NetPBM and PBMPLUS)

	FreeType library (only tested with versions 1.2 & 1.3)
	
With the exception of POV-Ray, all other items come standard with the
RedHat 6.2 distribution of Linux.  CoolTitle should be portable to most
UNIX or Linux variants -- given the above prerequisites.  This script is
provided as-is, with no guarantees that it will work on your particular
platform.  Please let me know of your successes, and any modifications
required.


Compiling and Installing CoolTitle:
-----------------------------------
The first step is to compile the CoolTitle C helper program
(cooltitle-calcwidth.c):

	make

Finally to install CoolTitle:

	make install

By default this will install files under /usr/local/bin and
/usr/local/lib/cooltitle.  If you wish to install in different
locations you will have to edit the values of BINDIR and LIBDIR in the
file Makefile, and $libdir in the file cooltitle before running this
command.


Running CoolTitle:
------------------
Example: to use the word "Text" as a CoolTitle icon:

Simply type:

	cooltitle Text

It will take several minutes to render your image, a 3D version of the
word "Text."  CoolTitle will produce several files in your current
directory:

	Text.pov	(The fully expanded POVRay scene)
	Text.ini        (A POV initialization file with rendering parameters)
	Text.pnm	(The very large raw image)
	Text-032.jpg	(JPEG image -  32 pixels high)
	Text-048.jpg	(JPEG image -  48 pixels high)
	Text-064.jpg	(JPEG image -  64 pixels high)
	Text-096.jpg	(JPEG image -  96 pixels high)
	Text-128.jpg	(JPEG image - 128 pixels high)


Usage:
------

cooltitle [primary options] [-- theme override options] text

Primary options:

  -q[uick]       Quick low quality render. [FALSE]
  -h[igh]        High quality render (very slow) [FALSE].
                 (-quick and -high options are mutually exclusive)

  -pause         Pause POV-Ray when rendering complete, before closing
                 preview window.

  -skip          Skip render POV-Ray scene generation and rendering steps.
                 Only post-process previously rendered text.

  -j[pg]         Quality of JPEG compression (0-100). [75]
                 0   = worst quality, smallest file
                 100 = best quality,  largest file

  -t[heme]=name  Theme name.  See 'cooltitle-themes.cfg' for more information.
                 [classic]

Theme override options:

  These options override settings defined in the selected theme.  These options
  must be preceded by the '--' option.  These options are useful for testing
  settings for a new theme.

  -font=fontfile    Name of ttf font file.

  -bg_color=color   Background color, from 'colors.inc' file or in POV-Ray
                    'color red x green x blue x' syntax.

  -[no]shadow       Cast shadows against backdrop.

  -pad=npixels      Horizontally pad width of output image by npixels.  May
                    be needed to make room for shadows.

  ... or any other field in a theme definition.