------------------------------------------------------------------
TSXtruder 1.0 by Bendy's 3D Systems
Copyright (C) 1999

Based on Extruder 1.1 by Bryce Denney
Copyright (C) 1999

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

The complete GNU public license is also in this directory.
------------------------------------------------------------------
For more information on this program, or to find a more recent 
version, look at http://www.bendys.com
------------------------------------------------------------------

TSXtruder 1.0 
25 April 1999
==================================================================
TSXtruder is a Truespace 3.x extension which can be used to create
heightfield objects by extruding TGA image files from the top
of a cube.

Big Thanks to Bryce Denney for giving me permission to base this
on his Extruder 1.1 program for Truespace 2.
REQUIREMENTS

trueSpace v3.0 or above and API Software Developers Kit.

INSTALLATION

Unzip all files with directory names into your Projects directory.
Open the TSXtruder.dsw workspace in Microsoft Visual C++ 5.0 and set
the library and include file directories (menu Tools/Options/Directories)
so they point to the location of your trueSpace 3.0 (or above) API include
and library files. That's all there should be to it, hit F7 and the TSX
will build. Once you have compiled the TSX simply fire up Truespace 3.0 or
later, open the 3D Plugins window and load 'TSXtruder.tsx' into the plugin panel.
If trueSpace reports "Library not found" or the TSX Extender refuses
to load the plugin please download the file mfc42u.dll from my webpage
and install it. This should fix the problem. However you shouldn't have
this problem cause you just compile the program so you ought to have that
dll.

NOTES

This code was developed under Microsoft Visual C++ 5.0. It shouldn't be
too hard to port it to MSVC 4 (Caligaris supported platform). I don't 
recommend trying to build TSXs under Borland C++ Builder at this time as
Borland does not support the library format that tsxapi.lib is in. 

FILES 

readme.txt - this document
license.txt - the GNU public license
tsxtruder.tsx - the plugin itself
b.tga - a 67x67 TGA file of a greyscale letter 'B' *
dougnut.tga - an 80x80 TGA file of a dougnut *
circles.tga - an 82x82 TGA file of some circles
				(used to make the icon)
ExtrudeTSX.cpp - Source files
ExtrudeTSX.def
ExtrudeTSX.rc
Hfield.cpp
StdAfx.cpp
Tga.cpp
TSXAboutDialog.cpp
TSXDialog.cpp
ExtrudeTSX.h
HFIELD.H
Resource.h
StdAfx.h
TGA.H
TSXAboutDialog.h
TSXDialog.h
BDelDown.BMP
BDelUp.BMP
BExtDown.BMP
BExtFlat.BMP
BResXMDown.BMP
BResXMUp.BMP
BResXPDown.BMP
BResXPUp.BMP
BResYMDown.BMP
BResYMUp.BMP
BResYPDown.BMP
BResYPUp.BMP
BSaveDown.BMP
BSaveUp.BMP
BSizeMZMDown.BMP
BSizeMZMUp.BMP
BSizeMZPDown.BMP
BSizeMZPUp.BMP
BSizePZMDown.BMP
BSizePZMUp.BMP
BSizePZPDown.BMP
BSizePZPUp.BMP
BSizeXMDown.BMP
BSizeXMUp.BMP
BSizeXPDown.BMP
BSizeXPUp.BMP
BSizeYMDown.BMP
BSizeYMUp.BMP
BSizeYPDown.BMP
BSizeYPUp.BMP
dialogbg.BMP
extruder.bmp
extruder2.bmp
iconsml.bmp
res\ExtrudeTSX.rc2

manual\manual.html - HTML manual page. Point yer browser here.
manual\faces.jpg
manual\res.jpg
manual\dialog.JPG
manual\xysize.jpg
manual\zsize.jpg
manual\ftype.jpg
manual\tri.JPG
manual\quad.jpg
manual\house.jpg
manual\dialog.html
manual\info.html
manual\head.html
manual\other.html
manual\res.html
manual\faces.html
manual\extbut.html
manual\delbut.html
manual\xysize.html
manual\zsize.html
manual\ftype.html
manual\text.html
manual\smooth.html
manual\file.html
manual\prog.html
manual\icon.JPG
manual\test.html
manual\mounds.JPG
manual\xtrd.JPG
manual\text.JPG
manual\smooth.jpg
manual\file.jpg
manual\prog.jpg
manual\extbutu.jpg
manual\extbutf.jpg
manual\delbutu.jpg
manual\delbutf.jpg
manual\fileb.jpg
manual\planar.html
manual\np.JPG

* - From original Extruder 1.1 by Bryce Denney.

TO BUILD YOUR OWN TSX

This is not a detailed description of how to write Windows MFC dlls. It
simply outlines what is necessary to setup a TSX so it can interface with
trueSpace. I am assuming you already know how to create and use MFC dialogs.
A trueSpace TSX is simply a Windows dll which contains four exported functions
called tsxGetData, tsxOnLeftClick, tsxOnRightClick and tsxDeactivate. These
interface functions are what trueSpace calls to load and execute the TSX.

tsxGetData: Called when the TSX is loaded. Used to pass information about the
plugin to trueSpace and check the version #.
tsxDeactivate: Called when the TSX is unloaded. Used to close down the dialog
box and perform housekeeping.
tsxOnLeftClick: Called when the user left clicks on the TSX icon. Usually 
displays a dialog box for the user to work with.
tsxOnRightClick: Called when the user right clicks on the TSX icon. Used to
display an About box or parameters.

trueSpace provides an API (Application Programmer Interface) containing library
functions which are used to control and manipulate trueSpace. These are the 
heart of plugin programming and allow you to create objects, animate attributes,
modify polyhedra and many many other functions. The API consists of a library
and a set of header files. It is necessary to include the header file in all
files using the API and the library must be linked to the DLL. There are 
currently five versions of the API one for each version of trueSpace that 
adds more TSX functionality (3.0,3.1,3.2,4.1,4.2). As a programmer you should
have all five versions and you should use the oldest version of the API that
you can. This ensures that the largest group of users will be able to use your
plugin. So, if you're not using any of the new features in version 3.2, don't
use it, use version 3.1.

1. Creating the TSX.
Make a new 'MFC AppWizard' (dll) project (menu file/new) (either shared or
static) in MSVC. A static dll links the standard MFC library at compile time
and should be fully selfcontained. A shared dll won't link the standard MFC
library with the TSX. It will be dynamically loaded when the TSX is run. This
reduces the size of the TSX however users will need to have the file
'mfc42u.dll' installed under Windows. This is a standard file and most people
will have it, if they don't it is distributable and I have a copy at my
TSX web site (http://www.bendys.com).
Your new project will have a number of items already created. Firstly a class
'CNameApp' and implementation files will exist which can be used to store and
control the TSX dialog. An instance of this class will also be defined as
'theApp'. Other files include a '.def' file, standard system includes file and
resource files.

2. Specify API.
MSVC needs to know where to find the TSX API files. Goto Options under the
Tools menu and add your TSX API include and library directories to their respective
search paths. Finally you need to specify link options under the Project/Settings
menu. Under the link tab enter the output file name ('name.tsx') and add
'tsxapi.lib' to Object/Library modules.

3. Export functions.
Now we need to export the interface functions. Open the '.def' file and
add the four interface function names (tsxGetData, tsxOnLeftClick,
tsxOnRightClick and tsxDeactivate) to the EXPORTS section of the file. The
'.def' file is used to define the dll and is read and link time to find out
if we're compiling an exe or dll and what functions to export. 

4. Resources.
TSXs require 2 resources to be defined, a bitmap to use as the icon and a
string to display in the trueSpace status bar. To create these click on the
ResourceView tab in the InfoView window. Right click on the resources tree
and select insert. Select Bitmap and hit insert. Repeat this to add a string
table. Open the resource tree and double click on the new bitmap resource to
open it. Hit Alt-Enter to display the properties and set the size to 32x32.
Now you can make your icon. Alternativly you can import a bitmap you made
elsewhere and use it as the icon. Open the string table and add a new string
to use as the message trueSpace displays. Note the IDs that these resources
are given as you'll need to use them in the tsxGetData function. In addition
to these you will of course need to make at least one dialog box as the user
interface to the TSX. This dialog will control the TSX and its code will 
call the trueSpace API to do the actual work. You may also want to create a
help dialog. Everything is now setup and you can begin coding.

5. Starting coding, TSX setup.
Now we can begin to write the actual code. To control the dialog box and
active state of the TSX I use the CNameApp class which MSVC created when we
started. First, create a simple dialog box which just has a Close button.
Add a BN_CLICKED event handler to the object which calls DestroyWindow() to close
the window. Don't worry about functionality until you get the TSX coming up in
trueSpace. Once you have made the dialog box and added a class for it (select
the dialog box and open the Class Wizard (ctrl-w)) you need to define a pointer
to store the dialog in the CNameApp class and a BOOL to indicate if the TSX
is active or not. Also include the file 'resource.h' in the header file.
You will also need code to show and hide the dialog box, set and check the
active state and to create and destroy the class. Check out 'UVRip.h' and
'UVRip.cpp' for details.

6. Starting coding, interface functions.
The four interface functions is the last step in preparing the TSX. These 
functions are implemented in the class implementation file 'Name.cpp'.
These functions can be found in the file 'UVRip.cpp'.

int tsxGetData(tsxData* tsx_data, int tsxid)
	tsxGetData is used to initialise the plugin on loading. It returns
a code indicating if the initialisation was successful or not (tsxPLUG_tsxDONE
or tsxPLUG_FAILED). This function should fill the tsx_data structure with 
information about the TSX.
struct tsxData
{
    char  m_Title[32];	//Brief name of this eXtension.
    char  m_Author[64]; //Name of author|company.
    short m_ResidBtnBmp;  //Resource id used for Button Bitmap
    short m_ResidBtnHelp; //Resource id used for Button Help Message
};
The tsxid variable is a unique ID for this TSX. It is used with callback 
functions to identify the TSX. This value should be stored for later use.
You should also call tsxGetTsVersionNbrs to check which version of trueSpace
is running and that it supports your TSX.

int tsxOnLeftClick(void)
	tsxOnLeftClick is called when the user runs the plugin by clicking
on its icon. Here we activate the TSX and display the dialog box so the user
can use it. This function returns a value indicating if the plugin is finished
or not (tsxPLUG_DONE or tsxPLUG_STAYON). If tsxPLUG_STAYON is returned then the
plugin will be unloaded when the user selects a standard trueSpace function.
Because of this UVRip returns a tsxPLUG_DONE so that trueSpace believes the 
plugin is finished. However, the dialog remains active and the TSX can still
be used.

void tsxOnRightClick(void)
	tsxOnRightClick is called when the TSXs icon is right clicked. It usually
displays an about dialog. Simply create a dialog box and display it.

void tsxDeactivate(void)
	tsxDeactivate is called when the plugin is deactivated. It simply makes
the plugin inactive and hides the dialog box. For more information on when
a plugin becomes deactivated read the readme.txt file that comes with the API.

7. All the rest
Add a line in 'Name.cpp' to set the plugin to start as inactive 
'BOOL CnameApp::sm_bIsActive = FALSE;'. You should now be able to build your tsx
and load it up into trueSpace. If you click on the icon the dialog should appear
with it's close buttons. You can now start adding functionality.

You may use my TSXtruder code as a base but note that any program you release which
is derivative of this one (IE: contains code directly from it) it will have to be
released in accordance with the GNU public license. The main implication of this
is that the source code must be distributed with your software and others who use
the code must be able to distribute their versions as well. Basically, it must
remain "Open Source" in the truest sense of the term. Read license.txt for more
information. In addition you will need to add the disclamer giving explicit
permission to link with tsxapi.lib. This is due to some issues involving the GPL
and plugins to non-GPL products.

Important factors to remember when building TSXs:
	You _must_ export the 4 trueSpace interface functions tsxGetData,
	tsxOnLeftClick, tsxOnRightClick and tsxDeactivate.
	
	Remember to make sure your dialog boxes are marked visible. MSVC5
	makes dialogs invisible by default. If you don't the nothing will 
	happen when you click on the TSX icon.
	
	You may get a compiler error of the form 'fatal error C1010: unexpected
	end of file while looking for precompiled header directive'. This
	occurs when you write your own cpp files rather than creating classes
	using MSVCs add class function. If your code isn't using MFC code you
	can simply turn off precompiled headers for that file (right click on
	the filename, select settings, C++ tab, Precompiled Headers category.
	Now select the 'Not using precompiled headers' radio button). Alternativly,
	if you are using MFC or you still wish to use precompiled headers add
	the line #include "stdafx.h" as the first include in the source file.

For more information on coding TSXs and details on the functions provided see
the documentation that comes with the SDK.

INSTRUCTIONS:

1. Fire up the extension by clicking on it's icon in the TSX panel.
2. Click the 'File' button to select the 16/24 Bit Uncompressed 
   TGA file you want to use.
3. Set the x and y resolution of the object. The default value is the
   size of the TGA file selected. You can change these and the number
   of faces will be updated in the dialog box.
4. Set the height for the extrusion (default=1).
5. Set the height of the cube being extruded from (default=1).
6. Set any other parameters you want
7. Hit the 'Extrude' button. 
8. That's It. Render your newly made heightfield.

The 'delete' button can be used to delete the object after creation,
if you so desire.

RESTRICTIONS

TSXtruder can only read uncompressed 16 or 24 bit TGA files.

KNOWN BUGS

None?

CHANGES SINCE VERSION 1.0 BETA 1

Added heaps of new features, size controls, smoothing, different
face types, textures, bumpmaps.

Fixed bad face normals.

Added support for 16 bit TGA files.

Better error checking on TGA files.

TODO FOR THIS VERSION (1.0)

Iron out any unknown bugs.

TODO FOR NEXT VERSION (1.1)

Option to mirror extrusion to base.

Support for more TGA file formats (compressed, indexed etc..)

Animation...,
Other stuff I (or you) can think of.

HOW TO GET IN TOUCH
Please send any comments, suggestions, and bug reports to 
bendy@bendys.com. If submitting a bug report please put the word
'bug' in the subject of the message.
Point your web browser to http://www.bendys.com for updates to
TSXtruder.

The original Extruder 1.1 by Bryce Denney which this plugin is based
on can be found at http://www.physics.oberlin.edu/~bdenney/extruder.
Bryce can be contacted at Bryce.Denney@bigfoot.com.

TrueSpace is a product of Caligari, Inc.  Their web site is at
http://www.caligari.com.
