REQUIREMENTS, DOCUMENTATION & GENERAL
==================================================================================

Zhu3D runs under Linux/Unix, Windows XP-Vista and Mac OS X and supports different
CPU's as well as different API's like KDE, Gnome or Motiv. Your operating system
must support OpenGL or at least a compatible software implementation like Mesa.
Isosurface calculation currently supports up to 16 CPU-threads. As additional
speed-booster you may enable vectorising with SSE3.

The absolute minimum screen-size is 1024x768. Hardware accelerated OpenGL is
strongly recommended. Any card from the DirectX9-generation will do the basic
job. For simple viewing even an ancient PC without HW-OpenGL is sufficient.
However, for motion blur, big textures or heavy animations with narrow grids
you will need any CPU/GPU-power you can get.

The strange program name was inspired by Zhu Shijie, a genius ancient Chinese
mathematician. If you are interested, you find some historic remarks in the help.


QUICK START
==================================================================================

The fastest way to explore Zhu3D is to run the menu "Help/Demo". The demo lets
you browse through all examples with just a mouse click. Most examples explain,
what currently is going on. For further information's take a look at the "Help"
menu. Especially the chapter "Mouse handling" may be worth reading:-)

The maybe most important button is the "Switcher" located in the lower left
corner of the mainwindow. Here you switch between editing functions, parametric
systems and isosurfaces.

The most important light/material property is the diffuse portion. So adjusting
the diffuse-sliders will give you quick results suitable for many standard tasks.


TIPS & TRICKS
==================================================================================

* There is a neat way to create customised slideshows for presentation/educational
purposes. Look in the directory ./work/slideshow for details

* When creating legends and text labels, you may want to use a different font.
There is no way to do this within the legends editor itself. But you can set a
new font via the "Settings/General/Font" menu as alternative

* You may start Zhu3D with a command line parameter. This is not only useful
for the text console. This mechanism also allows you an easy and seamless
integration within GUIs like KDE or Windows too. So clicking on a zhu-file
will automatically start Zhu3D itself e.g.

* When handling mathematically "strange" functions or moving to "huge" number-
regions, tessellation may result in odd views. The documentation gives further
hints, how to handle those extreme cases

* For watching parametric curves the point-mode has to be enabled. As alternative
you may switch to Triangle- or Quad-mode and enable the Wire-mode additionally.
The latter method will show a continuous line then

* Compared to function- and parameter-modes texturing in iso-mode works somehow
different. This is not an error! Applied in iso-mode the texture mapping as a
matter principal never can be as perfect as in the other modes. Nevertheless
interesting effects are possible

* Zhu3D is optimised for speed. If you need antialising however then: Open
main.cpp, search for "Multisampling", uncomment the following line and
recompile. Consider that antialising is quite costly in terms of speed and
not worth the effort normally


ERRORS, TROUBLES & HINTS
==================================================================================

Zhu3D is pretty stable and reliable. Nevertheless some hints and observations:

* Due to a bug in Qt4-4.7.1 quick zooming with the middle mouse button does not
work anymore. Use Crtl+/- in the mainwindow as workaround.

* Due to a bug in Qt4-4.6.0 saving/printing pics crashed, when they contain text.
When this crucial, update to newer Qt4-4.6.x what fixes this issue.

* Under Qt 4.5.x: Saving pictures with legends and really huge letters fails for
the latter. If you need this feature, update to Qt 4.5.2, what fixes this
regression.

* Mandriva (2009): When Zhu3D does note compile, remove '-fPIC' and '-DPIC' from
CXXFLAGS in the Makefile and it should build fine. No idea why this happens. This
strange issue seems to be Mandriva specific only.

* Some *nix users (Dec. 2008) reported troubles when using a composite manager.
It may be sufficient to click in the viewer window, or to move or animate the
graph after a fresh start. From then on, things should work well. Currently the
maybe best solution is to switch off the composite manager before starting Zhu3D
(or other OpenGL-apps). Make detailed bug-reports to the composite-developers to
help them fixing these issues

* Old openSUSE 10.3 seems to fail with NVIDIA-drivers from the official repository.
Just re-install the driver manually instead, what fixes the quirks

* Due to driver issues very old proprietary AMD/ATI-drivers may fail, when hardware-
acceleration is turned on. Updating your old graphics-driver will mostly solve
this problem and is strongly recommended anyhow

* Rendering "huge" pictures with static text legends seems to fail with old ATI-
drivers and/or too old Qt4 versions. If you rely on lets say 3000x3000 pics,
make updates to cure this

* PostScript file-generation or printing is somehow depending on your printer/
driver-backends. These even may crash, when print/file dimensions are too big.
My Windows XP prints up to a 8000x8000 resolution without problems. My old
Linux-box handles 2000x2000 only e.g, but my current Linux up to 10000x10000
or even more.


WINDOWS PECULIARITIES & LIMITATIONS
==================================================================================

Sorry Windows-folks, there are some deficiencies and peculiarities I did not want
to fiddle around. So you have to face some (very, very small) limitations, which
you would not even notice normally:

* Under Windows - especially the older versions - the measuring of the GPU/CPU-
utilisation may be a bit erratic and is by far not as precise as in Linux e.g. Due
to this missing timer granularity the CPU-clock is calculated and shown in other
OS's only

* Textures are a grain more brilliant under *nix and Mac OS's due to technical
reasons

* The compiler or the system-libraries are failing in the range of really high
precision calculations. Due to this phenomenon the solver-precision is limited
to 11 digits under Windows

* Under *nix/KDE e.g. language support for Chinese works out of the box. Windows XP
users have to play a little install/reboot-adventure for the Microsoft East-Asian
language pack before

* Ancient 16/32 Bit Windows versions like 98/ME are not tested any more. They may
work or may not work


TRANSLATIONS
==================================================================================

You saw errors/typos in your language setting or you are missing your language as
translation at all? You can help out easily. In the folder ./system/languages you
will find *.ts files, which you can change with the QT Linguist program delivered
with Qt4. With this it is really extremely simple to edit existing translations
or to create new ones. Just send the edited/new ts-file to my mail address (see
"Contact" below or choose the "Help/About"-box within Zhu3D).


VERSIONS AND UPDATES
==================================================================================

Currently updates are found under www.kde-apps.org/content/show.php?content=43071
what may change in future. Look at www.qt-apps.org than or just google in this
case. A detailed version history you will find in ./src/changelog.txt

The "Help/About"-box offers a link, where you quickly can check the latest version.


PROGRAMMING
==================================================================================

A short word to Qt4 from Trolltech: As I really dislike non-portable code, I
hardly ever wrote GUI-programs. This project initially was started to test if
the promises from Trolltech hold true. They do. It is a powerful GUI-framework
for platform-independent solutions. Even without prior experience, I managed to
port my old C-code-basis within a few days.


THANKS
==================================================================================

Over the time Zhu3D grew to a software with nifty features and high level techniques.
I surely would not have spent all the time and efforts, without a couple of people
motivating me. They spent ideas, knowledge, translations, distribution packages,
bug reports or simply patience. Special thanks to:

- Tiziano M. the 1.st packager (Gentoo). A source of inspiration and technical help
- Victor F. who drove 1.st Spanish translation and many other important things
- Juha N. and Joel Y. for the great parser-backend, discussions and prompt fixing
- Yanqing and Henri G. for massive work on Fr+Ch-translations and a lot of feedback
- Pavel F. for the Czech GUI-translation
- Gernot Z. for interesting discussions of tessellation algorithms
- Thomas L. for early Vista compatibility checks and general cooperativeness
- Darwin B. for Arch+Ubuntu-packaging and many fruitful hints and testing
- Pavel N. who always cared for Suse/openSuse-packages
- Jack F. for releasing Mac OS/OSX related versions and testing
- Henry K. who discussed tessellation algorithms on a quite scientific level with me
- The Trolltech/Nokia support/developer team. Always polite, quick in fixing issues
- The Softpedia *nix team for announcing the newest version lightning fast
- Cory Gene B. for the MC/MT-algorithms, which where a great source of inspiration
- Agner F. who inspired me for the hardcore-assembler stuff for hw-near classes
- And many others which helped out, spent time or interest


CONTACT
==================================================================================

If you have wishes, suggestions or just a supernice graph you want to share, mail
to: zhu3d (at) aon.at. I will try to respond as reliable as I can, but don't put
a hat on a hen. Sometimes I am under stress with my regular work.


LICENSE
==================================================================================

This program may be used under the terms of the GNU General Public License version
3 as published by the Free Software Foundation and appearing in the file
license.gpl included in this package.

This program is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

(C) 2010 Heinz van Saanen
