<!doctype linuxdoc system>

<!-- LinuxDoc file was created by <Dave Jarvis> Sat Jan 15 09:06:00 2000
 -->

<ARTICLE>
<TITLE>3D Graphics Modelling and Rendering mini-HOWTO</TITLE>
<AUTHOR>
<HTMLURL URL="mailto:dave@joot.com" NAME="Dave Jarvis">
</AUTHOR>
<DATE>v1.1, 27 March 2001</DATE>
<ABSTRACT>
Details download and installation instructions for a graphics rendering and
modelling development environment using RedHat Linux.
</ABSTRACT>
<TOC>

<SECT>
Introduction<LABEL ID="Introduction">

<SECT1>
Preamble<LABEL ID="Intro-Preamble">
<P>
This document will guide you through the steps used to install and
configure an environment for modelling and rendering three-dimensional
graphics using Linux.  In this section you will also find information
in  laymans terms about the required components and how they piece
together.  The installation section is purposely minimal; merely the
quick and dirty steps needed to take to get up and running (if it
doesn't work, more information is available).  For those that want more
information about the software components and what they do (in general),
please continue reading.
</P>

<P>
There are, at the minimum, three software packages you'll need in order to
get up and running.  These are as follows (in the order they are
explained, not the order they are installed):
</P>

<P>
<ITEMIZE>
<ITEM>a graphics library;
<ITEM>a graphics modeller;
<ITEM>a graphics renderer.
</ITEMIZE>
</P>

<SECT1>
Modelling vs. Modeling<LABEL ID="Intro-Modelling">
<P>
The spelling <EM>modelling</EM> is Canadian.  The spelling <EM>modeling</EM>
is American.  The original author of this document is Canadian.  ;-)
</P>

<SECT1>
Copyright Information<LABEL ID="Intro-Copyright">
<P>
Copyright &copy; 2000-2001 Dave Jarvis
</P>

<P>
This document may be reproduced in whole or in part, without fee, subject
to the following restrictions:
</P>

<P>
<ITEMIZE>
<ITEM>the copyright notice above and this permission notice must be
preserved complete on all complete or partial copies;
<ITEM>any translation or derived work must be approved by the author in
writing before distribution;
<ITEM>if you distribute this work in part, instructions for obtaining
the complete version of this manual must be included, and a means for
obtaining a complete version provided;
<ITEM>small portions may be reproduced as illustrations for reviews or
quotes in other works without this permission notice if proper citation
is given.
</ITEMIZE>
</P>

<SECT>
Background Information<LABEL ID="Background">
<P>
The content of this section exists only to describe, in general, the
three main components required for three-dimensional modelling and
rendering with a Linux-based system.
</P>

<SECT1>
The Graphics Library<LABEL ID="Background-GL">
<P>
A graphics library consists of the most basic tools used for manipulating
graphical images.  Think of all the things needed to build a house: wiring,
plumbing, wood, bricks, and such.  The graphics library can be thought of
as not these items, but rather the tools used create such items.  After
all, wire, metal tubes, planks, and bricks don't magically appear; rather
they are created and formed as entities unto themselves.  On a similar note,
graphics don't magically appear on the screen -- typically they consist
of lower-level graphics primatives (lines, rectangles, and individual
pixels, for example).
</P>

<P>
So the graphics library, then, can be thought of as the low-level graphics
primatives used to build more complex objects (spheres, boxes, complex
polygons, etc.).  Those complex objects are then used to build even more
complicated shapes and figures.
</P>

<P>
The graphics library installed was the freeware implementation of OpenGL
called <EM>Mesa</EM>.
</P>

<SECT1>
The Graphics Modeller<LABEL ID="Background-GM">
<P>
Since the graphics renderer is, ideally, completely hidden from the end-user,
we'll deal with that last (besides which, modelling is the next logical step
in keeping with my house-building analogy).  However, when it comes to the
actual installation, a graphics modeller relies on the renderer already being
installed.
</P>

<P>
If the graphics library is akin to the tools used to build the tools used
to build a house (!), then graphics modellers can be thought of as the
tools used to build the blueprints for the house -- sophisticated
blueprints, as modellers let you dictate exactly where the wiring, plumbing,
wood panels, bricks, and forth are supposed to go.  Furthermore, they
let you pick the style of panelling and the colour of the bricks you
desire.
</P>

<P>
The graphics modeller installed was the freeware package called
<EM>The Mops</EM>, which produces <EM>RenderMan</EM>-compatible files.
</P>

<SECT1>
The Graphics Renderer<LABEL ID="Background-GR">
<P>
In keeping with the house-building analogy, the graphics renderer is then
the construction workers.  Once you have the blueprints and materials ready
to go, you need something to actually build the house so it appears how it
was designed.  The graphics renderer is given information (i.e., the
blueprints in the form of a <EM>RenderMan</EM>-compatible file, or
equivalent) from the modeller to produce the final result.
</P>

<P>
Just as the graphics modeller needs the graphics renderer before it can be
installed, the renderer relies on the graphics library being installed
beforehand.
</P>

<P>
The graphics renderer installed was the <EM>Blue Moon Rendering Toolkit</EM>
which uses <EM>RenderMan</EM> files.
</P>

<SECT>
Installation Instructions<LABEL ID="Inst-Instructions">
<P>
Keep in mind that these are brief instructions; a quick summary of the more
important details you'll find listed in README files for the corresponding
software packages.  It is, by no means, a substitute for actually reading
those files (as they contain copyright information and other instructions
not necessarily covered by this document).
</P>

<SECT1>
Warning<LABEL ID="Inst-Warning">
<P>
First, let it be known that this document only covers how to get up and
running using RedHat v7.0.  Whenever given the choice as to which software
package to download, please make sure it is compatible with the flavour
of Linux you happen to be running.
</P>

<P>
Second, please only send E-mail if you have information that would be
helpful to other people who might read this document (such as explaining
how to install other tools, pointers to other tutorials, missing steps
grammar and/or speling mistakes and/or tpyos, etc.).  If software
doesn't compile, or you can't figure it out, please read its accompanying
documentation.  Please understand that your system may be completely
different, and as such debugging problems via E-mail across the Internet is
not a task anyone enjoys.  ;-)
</P>

<P>
Third, these are software packages that installed without any severe
hitches (read: severe headaches).  In the Related Links section, there
are alternate software packages along side the ones covered below.  Note
that just because a given software package is not covered in depth does
not mean it is any worse (or better) than those chosen to install.
</P>

<P>
Good luck!
</P>

<SECT1>
Download the Software<LABEL ID="Inst-Download">
<P>
Before you begin, you will need a web browser and Unix shell.  If you
don't know how to use a shell [bash, ksh, etc.], you're own your own
(although instructions are given in both English and shell commands).
</P>

<P>
Unless otherwise specified, all instructions are to be carried out as
<TT>root</TT>.

<P>
<ENUM>
<ITEM>Create a new directory <TT>/usr/local/archives</TT> for the packages:
<TSCREEN><VERB>
mkdir /usr/local/archives
</VERB></TSCREEN>

<ITEM>Download the following packages (in <BF>.tar.gz</BF> form)
into the newly created directory (homepages are given, as
well as links to download pages, and minimum software version):

<ITEMIZE>
<ITEM>
  <URL URL="http://www.mesa3d.org/"
   NAME="Mesa Graphics Library"> v3.4.1:
  <URL URL="http://www.mesa3d.org/download.html"
   NAME="www.mesa3d.org/download.html">
<ITEM>
  <URL URL="http://www.bmrt.org/"
   NAME="Blue Moon Rendering Toolkit"> v2.6beta:
   <URL URL="http://www.bmrt.org/BMRTdownload/index.html"
   NAME="www.bmrt.org/BMRTdownload/index.html">
<ITEM>
  <URL URL="http://www.informatik.uni-rostock.de/~rschultz/mops/"
   NAME="The Mops"> v0.42d:
  <URL URL="http://www.informatik.uni-rostock.de/~rschultz/mops/download.html"
   NAME="www.informatik.uni-rostock.de/~rschultz/mops/download.html">
</ITEMIZE>
</ENUM>
</P>

<SECT1>
Install the Graphics Library<LABEL ID="Inst-GL">
<P>
Old versions of <TT>tar</TT> do not support the <TT>z</TT> argument.
For those systems, leave out the <TT>z</TT> argument and use <TT>gunzip</TT>
on the file before using <TT>tar</TT>.
</P>

<P>
<ENUM>
<ITEM>Change to the <TT>/usr/local/archives</TT> directory:
<TSCREEN><VERB>
cd /usr/local/archives
</VERB></TSCREEN>

<ITEM>Extract <EM>Mesa</EM> (substitute version number where required):
<TSCREEN><VERB>
tar zxf MesaLib-3.4.1.tar.gz
tar zxf MesaDemos-3.4.1.tar.gz
</VERB></TSCREEN>

<ITEM>Change to the <TT>MesaLib</TT> subdirectory:
<TSCREEN><VERB>
cd Mesa-3.4.1
</VERB></TSCREEN>

<ITEM>Configure, make, and install <EM>Mesa</EM> with the following sequence of
commands:
<TSCREEN><VERB>
./configure; make; make install
</VERB></TSCREEN>

<ITEM>Edit <TT>/etc/ld.so.conf</TT>, and ensure you have a line that
reads:
<TSCREEN><VERB>
/usr/local/lib
</VERB></TSCREEN>

<ITEM>Run the dynamic library configuration program:
<TSCREEN><VERB>
ldconfig
</VERB></TSCREEN>
</ENUM>
</P>

<SECT1>
Install the Graphics Renderer<LABEL ID="Inst-GR">

<P>
<ENUM>
<ITEM>Return to the <TT>/usr/local/archives</TT> directory:
<TSCREEN><VERB>
cd ..
</VERB></TSCREEN>

<ITEM>Extract the <EM>Blue Moon Rendering Toolkit</EM> (substitute version
number where required):
<TSCREEN><VERB>
tar zxf BMRT2.6beta.linux-glibc2.tar.gz
</VERB></TSCREEN>

<ITEM>Change to the <TT>BMRT</TT> subdirectory:
<TSCREEN><VERB>
cd BMRT2.6
</VERB></TSCREEN>

<ITEM>Copy files to appropriate destination directories:
<TSCREEN><VERB>
cp bin/* /usr/local/bin/
cp lib/lib* /usr/local/lib/
cp include/* /usr/local/include/
</VERB></TSCREEN>

<ITEM>Make a directory for the shaders, ensure it is world-writable,
then copy the shader files into it:
<TSCREEN><VERB>
mkdir /usr/local/shaders
chmod 777 /usr/local/shaders
cp shaders/*.sl* /usr/local/shaders/
cp shaders/*.h /usr/local/shaders/
cp examples/*.sl* /usr/local/shaders/
cp examples/*.h /usr/local/shaders/
</VERB></TSCREEN>

<ITEM>Edit the system login profile (<TT>/etc/profile</TT> or equivalent),
and add the line:
<TSCREEN><VERB>
export SHADERS=.:/usr/local/shaders
</VERB></TSCREEN>

<ITEM>Copy the <TT>.rendribrc</TT> file to each user's home directory.
</ENUM>
</P>

<P>
If anything goes wrong, please consult the <TT>README</TT> file
that accompanies the <EM>Blue Moon Rendering Toolkit</EM>, or visit
their website.
</P>

<SECT1>
Install the Graphics Modeller<LABEL ID="Inst-GM">
<P>
<EM>The Mops</EM> may be installed on a per-user basis, or on a system-wide
basis by root (or equivalent).  In this example, it is installed using a
non-administrative account, which should yield positive results.  Note that
the compile failed during the install (missing a C header file), so the
precompiled binaries (compatible with RedHat v6.0, your system may vary)
were installed, as follows:
</P>

<P>
<ENUM>
<ITEM>Change to one directory above where you'd like <EM>The Mops</EM> to
reside.  For example, if <TT>/usr/local/mops</TT> was desired, then issue
the following command:
<TSCREEN><VERB>
cd /usr/local
</VERB></TSCREEN>

<ITEM>Extract the mops (substitute number where required), then change into
its directory:
<TSCREEN><VERB>
tar zxf /usr/local/archives/mops-0.42d-BMRT26-linux.tar.gz
cd mops
</VERB></TSCREEN>

<ITEM>Move the following files from <TT>/usr/local/mops/src</TT>
to <TT>/usr/local/mops</TT>:
<TSCREEN><VERB>
mv src/crtmopssh.sh .
mv src/mfio.so .
mv src/mops .
</VERB></TSCREEN>

<ITEM>Copy the <TT>.mopsrc</TT> file to the home directory of each user
wanting to run The Mops.  For example, the user "jane" would need the
following commands run:

<TSCREEN><VERB>
cp src/mopsrc /home/jane/.mopsrc
</VERB></TSCREEN>

<ITEM>Create <TT>/usr/local/lib/mops</TT> and move the buttons and shaders:
<TSCREEN><VERB>
mkdir /usr/local/lib/mops/
mv buttons/* /usr/local/lib/mops/
mv shader/*.sl* /usr/local/shaders/
</VERB></TSCREEN>
</ENUM>
</P>

<P>
If anything goes wrong, please consult the <TT>README</TT> and
<TT>Setup.txt</TT> files that accompany <EM>The Mops</EM>, or visit
their website.
</P>

<P>
Log out from <TT>root</TT>.  Log in as a regular user, and run
<EM>The Mops</EM> as follows:
</P>

<P>
<TSCREEN><VERB>
/usr/local/mops/mops
</VERB></TSCREEN>
</P>

<P>
You may wish to create a subdirectory within <TT>$HOME/mops</TT> called
<TT>models</TT> for saving 3D models.
</P>

<SECT1>
Clean Up<LABEL ID="Inst-Clean">
<P>
Now that the installation is complete, you can remove from your
system all files that you no longer require (substituting version
numbers where required).
</P>

<P>
<TSCREEN><VERB>
cd /usr/local/archives/
rm -rf BMRT2.6
rm -rf Mesa-3.4.1
</VERB></TSCREEN>
</P>

<P>
Note: Be cautious when using <TT>rm -rf</TT> ... make sure you are
in the correct directory, and the files and/or directories you wish to
delete are present.
</P>

<SECT>
Miscellaneous Information<LABEL ID="Misc-Information">
<P>
Instead of a frequently asked questions section, here is information
about some of the (almost embarassing) problems faced.
</P>

<SECT1>
Lighting<LABEL ID="Misc-Lighting">
<P>
The most frustrating problem, initially, was trying to figure out why
everything was black -- and then how to actually light objects up.  In
these "virtual worlds" where you are modelling objects, the worlds
are created from scratch.  There is <EM>no light</EM> in the world until
you actually put a light source in it!  The light sources then shine
a given direction, illuminating things in their path (according to
the surface properties of the objects).  Make certain that your light
source is:
</P>

<P>
<ENUM>
<ITEM>pointing (rotated and translated) in the correct direction;
<ITEM>intense enough to actually cast discernable lighting.
</ENUM>
</P>

<SECT1>
Tutorials<LABEL ID="Misc-Tutorials">
<P>
The most basic thing a person would want to do with modelling/rendering
packages is position a sphere on a surface, give it some lighting, and
see the result.  A decent tutorial should describe that first.
</P>

<P>
That said, <EM>The Mops</EM> has a wonderful
<URL URL="http://www.informatik.uni-rostock.de/~rschultz/mops/tut1/tut1.html"
 NAME="first tutorial">.
</P>

<SECT>
Related Links<LABEL ID="Links-Related">

<SECT1>
Graphics Libraries<LABEL ID="Links-GL">
<P>
<URL URL="http://www.mesa3d.org/" NAME="Mesa"> - An OpenGL-compliant
Graphics Library.
</P>

<SECT1>
Graphics Renderers<LABEL ID="Links-GR">
<P>
<URL URL="http://www.bmrt.org/" NAME="BMRT"> - The Blue Moon Rendering
Toolkit.
</P>

<P>
<URL URL="http://www.povray.org/" NAME="POV-Ray"> - The Persistence of
Vision Raytracer.
</P>

<SECT1>
Graphics Modellers<LABEL ID="Links-GM">

<P>
<URL URL="http://www.informatik.uni-rostock.de/~rschultz/mops/"
 NAME="The Mops"> - A 3D modelling package that uses BMRT.
</P>

<P>
<URL URL="http://www.blender.nl" NAME="Blender"> - Freeware modelling
and rendering suite of tools.
</P>

<SECT1>
Miscellaneous Links<LABEL ID="Links-Misc">
<P>
Here are some links that don't really fit into any other category, yet
are still worthwhile checking out if you are seriously considering
using your Linux computer as a 3D modelling and rendering machine.
</P>

<P>
<URL URL="http://glide.xxedgexx.com/software.html"
 NAME="3D Software for Linux"> - Contains most (if not all) links in
this document and then some.
</P>

<P>
<URL URL="http://ntua.linuxberg.com/x11html/gra_3d.html"
 NAME="3D Modelling Software for Linux"> - Links to software packages
chiefly related to modelling.
</P>

<P>
<URL URL="http://linux3d.netpedia.net"
 NAME="3D Modelling and Rendering using Linux"> - A comprehensive site
with articles and software that explains what this document summarizes.
</P>

<SECT>
Acknowledgements<LABEL ID="Acknowledgements">
<P>
I would like to extend a heart-felt thanks to the developers of the
software packages detailed in this document.  The quality of their
products is of a commercial level, yet they keep the spirit of free
software alive.  Well done!
</P>

</ARTICLE>


