Program     : tga2df3
Author      : Ross Litscher 
Contact     : rlitscher!!at!!speakeasy!!dot!!net 
              remove ! marks
              replace at with @
              replace dot with .
Description : Convert a series of 24 bit, uncompressed, 
              True-color TGA images to a POV-Ray 
              (http://www.povray.org) compatible DF3 "density" 
              file. Using other TGA types or image types is 
              not supported and may result in problematic 
              behavior. 
Website     : none yet. 
Copyright   : Copyright 2004 Ross Litscher


Fast Start:

run the commands:
make
make install

The help command, '/usr/local/bin/tga2df3 -h' will be run
on successfull compilation.

'make install' requires permissions to write to /usr/local/bin/, 
if you have permission, this will result in tga2df3 placed
there. Otherwise, move tga2df3 to the location of your choice
or run it from the current directory with ./tga2df3 [OPTION]
Also, see USAGE below.


General Information:

tga2df3 is written to be as compliant to the C++ standard as 
possible. You will need a recent C++ compiler such as GNU "g++" 
3.2.3 (http://www.gnu.org). tga2df3 has been built and tested on 
both Windows and Linux using the GNU C++ compiler. I would 
imagine the freely available Microsoft C++ compiler would work 
as well. This document will focus only on compiling with the GNU 
C++ compiler "g++".

tga2df3 has been developed on Linux Slackware 9.1 with GNU g++ 
version 3.2.3. Thus, most testing has gone into this Linux 
version. tga2df3 has been succesfully built and tested on MS 
Windows also with GNU g++ version 3.2.3 using Dev-C++ 
(http://www.bloodshed.net).

If you are building this program for Linux or other unix-like
systems skip to the section entitled LINUX INSTALLATION. For 
DOS or WINDOWS based systems skip to the section entitled DOS 
INSTALLATION. For everything else, hopefully you will know what
you are doing :) Insight into your experience is welcomed 
feedback.

For usage, see the section entitled USAGE.

For reporting bugs see the section REPORTING BUGS.


LINUX INSTALLATION:

The brief instructions:
1) decompress and unarchive tga2df3.x.x.tar.gz.
2) change to the tga2df3.x.x directory
3) run "make"
4) move the tga2df3 executable to your desired location, or
   run "make install" to move it to /usr/local/bin/

The detailed instructions:

"tar" and "gzip" are required to decompress and unarchive the 
source files. The easiest way to build tga2df3 is to have a 
working version of GNU "make" as well as "g++" from GNU GCC 
3.2.3. "g++", "make", "tar", and "gzip" are available from 
http://www.gnu.org

Unarchive tga2df3.x.x.tar.gz with the command:
tar xvzf tga2df3.x.x.tar.gz 

where x.x. is replaced with the current version number. This 
will create a directory called "tga2df3.x.x" containing the
source files.

Change to the new directory:
cd tga2df3.x.x

If you have "make" installed on your system, simply try 
running the command:
make

This will build the tga2df3 executable program. If sucessfull 
the command line options for tga2df3 will be displayed.

You may install tga2df3 in the directory specified by BIN in 
the Makefile. The default value may require that you have 
superuser priviledges. Edit the Makefile and set BIN to the 
directory of your choice. If you would like to do this, after 
make has built tga2df3 without errors, run:
make install

You are done. The directory that tga2df3 is in now in might 
need to be added to your PATH.

If you do not have "make" you can compile each .cpp file 
separately and then link the object files. for example, the 
following works on my system, however your results may vary:
g++ -c *.cpp
g++ -o tga2df3 *.o

See your compiler documentation for information on how to 
compile source files. If successfull, you will have a 
tga2df3 executable. You may move this file to an acceptable 
place.

I recommend getting "make" and using it.


DOS INSTALLATION:

I have done minimal development in DOS or WINDOWS. 
Hopefully this will be enough to get you through. If worse 
comes to worse, check your compiler documentation.

These directions will be rather GNU specific. GNU
tools are widely available for Windows. I will not provide 
binary distributions of this program at this time. 

You may need to download versions of the GNU 
(http://www.gnu.org) programs "tar" and "gzip" to decompress 
and unarchive the source code. However, programs such as WinZip 
may have the needed funtionality. 

When unarchived, it will create a directory called 
"tga2df3.x.x" that contains the source code and Makefile.win. 

If you have the program "make", read Makefile.win and make any 
changes specific to your system. The Makefile.win file was 
generated and edited for use with an installation of Dev-C++ 
(http://www.bloodshed.net) installed in D:\Dev-CPP (*see notes
for IDE's below)

Once Makefile.win is correct for your system, run:
make -f Makefile.win

Additionally, you could compile each .cpp separately. 
Assuming you are using GNU g++, the following may work:
g++ -c *.cpp
g++ -o tga2df3 *.o

(*)IDE Notes:
An easier way to build tga2df3 if you are using Dev-C++ is to
start a new console project and add all the .cpp and .hpp
files to it. Proceed to Rebuild All. This should create a 
working tga2df3 executable. Something similar can probably
be done with most Integrated Development Environments. 


USAGE:

Simply running tga2df3 without any options or input will result
in tga2df3 appearing to hang. It is simply waiting for input. 
This behavior is different from other people's implementation
of a tga->df3 converter. The reason I do it this way is to 
maintain a portable code base. In the future the 
Boost::Filesystem library (http://www.boost.org) may be used 
to reproduce the functionality of reading tga files based on a 
basename. See the "Files from basename" option below.


-h or --help
---------------------------------
For help in using tga2df3, type:
tga2df3 -h
or
tga2df3 --help


Piping to tga2df3
---------------------------------
Typically you will use the output of a directory listing 
redirected or piped to tga2df3. 

In Linux this would be:
ls -1p some_tga_files*.tga | tga2df3 

In DOS this would be:
dir /B /ON some_tga_files*.tga | tga2df3.exe

Note that if the tga files are set as executable in unix-like
sytems, the -p option must be passed to the 'ls' command
or else the tga filenames will have a * appended to the end.
this will make the files unopenable.


Specifying a DF3 output name
---------------------------------
The output DF3 file will be named base upon the first file 
found that matches some_tga_files*.tga. For example, if the 
first file found was called "some_tga_files101.tga", the 
resulting df3 would be "some_tga_files101.df3". This can be 
changed by specifying an ouput file with the -o option:
ls -1p some_tga_files*.tga | tga2df3 -o my.df3


Reading TGA names from a file
---------------------------------
If you have a text file containing names of TGA files you 
would like to use to create a DF3 you may use the -f option. 
Note you may want to turn sorting off if your file lists
the tga images in a specific order.
As an example, imagine you created a list with the command:
ls -1p some_tga_files*.tga > tga_list

You could then use that list with tga2df3 with:
tga2df3 -f tga_list

The file containing the list must have one filename per line.


Sorting input
---------------------------------
By default, incomming file names are sorted. To turn off 
sorting, use the -s option:
tga2df3 -f tga_list -s


Verbose messages
---------------------------------
You may also want to see the status of tga2df3 as it processes
input. To do this use the -v option with any other options.
ls -1p some_tga_files*.tga | tga2df3 -o my.df3 -v


Files from basename (NOT IMPLEMENTED)
---------------------------------
In the hopefully near future you will be able to use the -b 
option to read the current directory for files starting with a 
specified basename and generate a DF3 from those files:
tga2df3 -b tga_basename

Trying this now will result in a notice saying this is not
implemented and offer several suggestions to mimick that 
behavior.


REPORTING BUGS:

Are you sure it's a bug with tga2df3? Make sure that the TGA 
file is really a 24 bit, uncompressed, true-color TGA. A method 
for producing this type of file with POV-Ray is by using the 
+FT option. This is the only supported file type. Do not submit 
bugs for unsupported files. 

Otherwise, if you are sure it is a supported file type, rerun
tga2df3 with the -v option. Please copy the output of the 
tga2df3 command that resulted in error. If the bug is not 
reproduced when -v is used, copy any output error message of the
run that produced an error. Email that message, as well as your
operating system name and version, compiler name and version. 
Specify the steps that need to be taken to reproduce the error.

If you feel so inclined, patches will be considered if you 
have encountered a bug and fixed it yourself. In that case, 
specify the version of tga2df3 that you are using. Either send 
the entire source code file or a diff. Only portable, ISO 
standard C++ will be accepted.

Send all reports to the email address at the top of the README
file, or from the FEEDBACK section.


FEEDBACK:

Any ideas, suggestions, and comments can be emailed to me.
Simply follow these anti-spam measurements. My email
address is:
rlitscher!!at!!speakeasy!!dot!!net
But you must
1) remove the ! marks
2) replace at with @
3) replace dot with .


ROADMAP:

There are no immediate plans for new features. The foreseeable
future holds bug fixes that will show up once this is released
upon the world.

I can see how a simple GUI might be usefull to select files. 
Ideally this would be a cross platform solution. It would of
course be an optional componant and must be extremely quick
loading since tga2df3 is usually used once and put away. Slow
load times would be harmfull to the usefullness of a GUI.

Finally, at some point creating a png2df3 might be an 
interesting study and force a refactoring of the current 
source code to be more generic. The possible consequences of
this has not been explored. There are atleast several points
in the source code that are tied too closely to the TGA 
file format and I regret showing it to the public in that 
condition. However, one could refactor a personal project
infinitely. On that note, happy raytracing!


FAQ:

1)
  Q. How do I use tga2df3 in Linux?
  A. Assuming you have a bunch of tga files that begin with 
     the name "myfile", type:
     ls -1p myfile*.tga | tga2df3 -v 

2)
  Q. How do I use tga2df3.exe in Windows?
  A. Assuming you have a bunch of tga files that begin with
     the name "myfile", type:
     dir /B /ON myfile*.tga | tga2df3.exe     

3)
  Q. How do I specify a name for the created DF3?
  A. see the '-o' option in USAGE.
     
4)
  Q. I get the error, 
     ERROR: Unable to open myfile01.tga*
     DF3 file not created.

     but I have permission to read myfile01.tga. What's the 
     deal?

  A. This means that myfile01.tga is set as executable. the 
     "ls" command prints a "*" after the filenames of 
     executable files unless the '-p' option is used with "ls". 
     You can either use "ls -1p" instead of "ls -1" or you can 
     change the permissions of your tga files with 
     "chmod -x myfile*.tga" and then use "ls -1"



