Section 2.3.5
Generic Unix

Required:

-	POVUNI_S.TGZ or POVUNI_S.TAR.GZ - The C source code for POV-Ray for Unix. Either archive contains full generic source, Unix and X-Windows specific source.
-	POVUNI_D.TGZ or POVUNI_D.TAR.GZ or any archive containing the sample scenes, standard include files and documentation. This could be the Linux or SunOS executable archives described above.
-	A C compiler for your computer and KNOWLEDGE OF HOW TO USE IT. Although we provide source code for generic Unix systems, we do not provide technical support on how to compile the program.
-	A text editor capable of editing plain ASCII text files.

Recommended:

-	Math co-processor.
-	8 meg or more RAM.
-	Graphic file viewer capable of viewing PPM, TGA or PNG formats.

Optional:

-	X Windows if you want to be able to display as you render.
-	You will need the X-Windows include files as well. If you're not familiar with compiling programs for X-Windows you may need some help from someone who is knowledgeable at your installation because the X include files and libraries are not always in a standard place.

Section 2.3.6
All Versions

Each executable archive includes full documentation for POV-Ray itself as well as specific instructions for using POV-Ray with your type of platform.

All versions of the program share the same ray-tracing features like shapes, lighting and textures. In other words, an IBM-PC can create the same pictures as a Cray supercomputer as long as it has enough memory.

The user will want to get the executable that best matches their computer hardware. See the section "Where to Find POV-Ray Files" for where to find these files. You can contact those sources to find out what the best version is for you and your computer.

Section 2.3.7
Compiling POV-Ray

The following sections will help you to compile the portable C source code into a working executable version of POV-Ray. They are only for those people who want to compile a custom version of POV-Ray or to port it to an unsupported platform or compiler.

The first question you should ask yourself before proceeding is Do I really need to compile POV-Ray at all? Official POV-Ray Team executable versions are available for MS-DOS, Windows 3.1x/95/NT, Mac 68k, Mac Power PC, Amiga, Linux for Intel x86, and SunOS. Other unofficial compiles may soon be available for other platforms. If you do not intend to add any custom or experimental features to the program and if an executable already exists for your platform then you need not compile this program yourself.

If you do want to proceed you should be aware that you are very nearly on your own. The following sections and other related compiling documentation assume you know what you are doing. It assumes you have an adequate C compiler installed and working. It assumes you know how to compile and link large, multi-part programs using a make utility or an IDE project file if your compiler supports them. Because makefiles and project files often specify drive, directory or path information, we cannot promise our makefiles or projects will work on your system. We assume you know how to make changes to makefiles and projects to specify where your system libraries and other necessary files are located.

In general you should not expect any technical support from the POV-Ray Team on how to compile the program. Everything is provided here as is. All we can say with any certainty is that we were able to compile it on our systems. If it doesn't work for you we probably cannot tell you why.

There is no technical documentation for the source code itself except for the comments in the source files. We try our best to write clear, well- commented code but some sections are barely commented at all and some comments may be out dated. We do not provide any technical support to help you to add features. We do not explain how a particular feature works. In some instances, the person who wrote a part of the program is no longer active in the Team and we don't know exactly how it works.

When making any custom version of POV-Ray or any unofficial compile, please make sure you read and follow all provisions of our license in "Copyright". In general you can modify and use POV-Ray on your own however you want but if you distribute your unofficial version you must follow our rules. You may not under any circumstances use portions of POV-Ray source code in other programs.

Section 2.3.7.1
Directory Structure

POV-Ray source code is distributed in archives with files arranged in a particular hierarchy of directories or folders. When extracting the archives you should do so in a way that keeps the directory structure intact. In general we suggest you create a directory called povray3 and extract the files from there. The extraction will create a directory called source with many files and sub-directories.

In general, there are separate archives for each hardware platform and operating system but each of these archives may support more than one compiler. For example here is the directory structure for the MS-DOS archive.

  SOURCE
  SOURCE\LIBPNG
  SOURCE\ZLIB
  SOURCE\MSDOS
  SOURCE\MSDOS\PMODE
  SOURCE\MSDOS\BORLAND
  SOURCE\MSDOS\DJGPP
  SOURCE\MSDOS\WATCOM

The source directory contains source files for the generic parts of POV-Ray that are the same on all platforms. The source\libpng contains files for compiling a library of routines used in reading and writing PNG (Portable Network Graphics) image files. The source\zlib contains files for compiling a library of routines used by libpng to compress and uncompress data streams. All of these files are used by all platforms and compilers. They are in every version of the source archives.

The source\msDOS directory contains all source files for the MS-DOS version common to all supported MS-DOS compilers. The pmode sub-directory contains source files for pmode.lib which is required by all MS-DOS versions. The borland, djgpp, and watcom sub-directories contain source, makefiles and project files for C compilers by Borland, DJGPP and Watcom.

The source\msDOS directory is only in the MS-DOS archive. Similarly the Windows archive contains a source\windows directory. The Unix archive contains source/unix etc.

The source\msDOS directory contains a file cmpl_msd.doc which contains compiling information specific to the MS-DOS version. Other platform specific directories contain similar cmpl_xxx.doc files and the compiler specific sub-directories also contain compiler specific cmpl_xxx.doc files. Be sure to read all pertinent cmpl_xxx.doc files for your platform and compiler.

Section 2.3.7.2
Configuring POV-Ray Source

Every platform has a header file config.h that is generally in the platform specific directory but may be in the compiler specific directory. Some platforms have multiple versions of this file and you may need to copy or rename it as config.h. This file is included in every module of POV-Ray. It contains any prototypes, macros or other definitions that may be needed in the generic parts of POV-Ray but must be customized for a particular platform or compiler.

For example different operating systems use different characters as a separator between directories and file names. MS-DOS uses back slash, Unix a front slash or Mac a colon. The config.h file for MS-DOS and Windows contains the following:

#define FILENAME_SEPARATOR ''

which tells the generic part of POV-Ray to use a back slash.

Every customization that the generic part of the code needs has a default setting in the file source\frame.h which is also included in every module after config.h. The frame.h header contains many groups of defines such as this:

#ifndef FILENAME_SEPARATOR #define FILENAME_SEPARATOR '/' #endif

which basically says if we didn't define this previously in config.h then here's a default value. See frame.h to see what other values you might wish to configure.

If any definitions are used to specify platform specific functions you should also include a prototype for that function. The file source\msDOS\config.h, for example, not only contains the macro:

#define POV_DISPLAY_INIT(w,h) MSDOS_Display_Init ((w), (h));

to define the name of the graphics display initialization function, it contains the prototype:

void MSDOS_Display_Init (int w, int h);

If you plan to port POV-Ray to an unsupported platform you should probably start with the simplest, non-display generic Unix version. Then add new custom pieces via the config.h file.

Section 2.3.7.3
Conclusion

We understand that the above sections are only the most trivial first steps but half the fun of working on POV-Ray source is digging in and figuring it out on your own. That's how the POV-Ray Team members got started. We've tried to make the code as clear as we can.

Be sure to read the cmpl_xxx.doc files in your platform specific and compiler specific directories for some more minor help if you are working on a supported platform or compiler.

Good luck!

The comp.graphics.rendering.raytracing newsgroup has many competent POV-Ray users that are very willing to share their knowledge. They generally ask that you first browse a few files to see if someone has already answered the same question, and of course, that you follow proper "netiquette". If you have any doubts about the qualifications of the folks that frequent the group, a few minutes spend at the Ray Tracing Competition pages at www.povray.org will quickly convince you!

Section 2.4.3
PC Graphics Area on America On-Line

There's an area now on America On-Line dedicated to POV-Ray support and information. You can find it in the PC Graphics section of AOL. Jump keyword POV (the keyword PCGRAPHICS brings you to the top of the graphics related section). This area includes the Apple Macintosh executables also. It is best if messages are left in the Company Support section. Currently, Bill Pulver (BPulver) is our representative there.

Section 2.4.4
The Graphics Alternative BBS in El Cerrito, CA

For those on the West coast, you may want to find the POV-Ray files on The Graphics Alternative BBS. It's a great graphics BBS run by Adam Shiffman. TGA is high quality, active and progressive BBS system which offers both quality messaging and files to its 1300+ users.

  510-524-2780 (PM14400FXSA v.32bis 14.4k, Public)
  510-524-2165 (USR DS v.32bis/HST 14.4k, Subscribers)

Section 2.4.5
PCGNet

The Professional CAD and Graphics Network (PCGnet) serves both the CAD and Graphics communities by making information useful to them widely available.

Formerly known as ADEnet, PCGnet is a new network created from the ground up, incorporating new nodes and focusing evenly on both CAD and graphics related topics, including, but not limited to the following topics: design, drafting, engineering, 2d and 3d modeling, multimedia, systems, raster imaging, raytracing, 3d rendering and animation.

PCGnet is designed to serve the needs of all callers by stimulating interest and generating support forums for active users who have an interest in the CAD and graphics related topics previously mentioned; interest and support is generated through PCGnet's message conferences, file sharing across the network, and industry news and press releases. PCGnet's message conference are moderated forums designed to accommodate friendly, yet professional and informative discussion of CAD and graphics related subjects.

TGA BBS serves as the central hub for a large network of graphics-oriented BBS systems around the world. Following is a concise listing of active PCGNet nodes at the time of this writing. The POV-Team can not vouch for the currency of this information, nor verify that any of these boards may carry POV-Ray.

USA and Canada
  411-Exchange                 Alpharetta        GA      404-345-0008
  Autodesk Global Village      San Rafael        CA      415-507-5921
  CAD/Engineering Services     Hendersonville    TN      615-822-2539
  Canis Major                  Nashville         TN      615-385-4268
  CEAO BBS                     Columbus          OH      614-481-3194
  CHAOS BBS                    Columbia          MO      314-874-2930
  Joes CODE BBS                West Bloomfield   MI      810-855-0894
  John's Graphics              Brooklyn Park     MN      612-425-4436
  PC-AUG                       Phoenix           AZ      602-952-0638
  SAUG BBS                     Bellevue          WA      206-644-7115
  Space Command BBS            Kennewick         WA      509-735-4894
  The CAD/fx BBS               Mesa              AZ      602-835-0274
  The Drawing Board BBS        Anchorage         AK      907-349-5412
  The Graphics Alternative     El Cerrito        CA      510-524-2780
  The Happy Canyon             Denver            CO      303-759-3598
  The New Graphics BBS         Piscataway        NJ      908-271-8878
  The University               Shrewsbury Twp    NJ      908-544-8193
  The Virtual Dimension        Oceanside         CA      619-722-0746
  Time-Out BBS                 Sadsburyville     PA      610-857-2648

Australia
  MULTI-CAD Magazine BBS       Toowong QLD              61-7-878-2940
  My Computer Company          Erskineville NSW         61-2-557-1489
  Sydney PCUG Compaq BBS       Caringbah NSW            61-2-540-1842
  The Baud Room                Melbourne VIC            61-3-481-8720

Austria
  Austrian AutoCAD User Group  Graz                    43-316-574-426

Belgium
  Lucas Visions BBS            Boom                     32-3-8447-229

Denmark
  Horreby SuperBBS             Nykoebing Falster        45-53-84-7074

Finland
  DH-Online                    Jari Hiltunen           358-9-40562248
  Triplex BBS                  Helsinki                358-9-5062277

France
  CAD Connection               Montesson                33-1-39529854
  Zyllius BBS!                 Saint Paul                 33-93320505

Germany
  Ray BBS Munich               Munich                    49-89-984723
  Tower of Magic               Gelsenkirchen            49-209-780670

Netherlands
  BBS Bennekom: Fractal Board  Bennekom                 31-318-415331
  CAD-BBS                      Nieuwegein               31-30-6090287
                                                        31-30-6056353
  Foundation One               Baarn                    31-35-5422143

New Zealand
  The Graphics Connection      Wellington               64-4-566-8450
  The Graphics Connection II   New Plymouth             64-6-757-8092
  The Graphics Connection III  Auckland                 64-9-309-2237

Slovenia
  MicroArt                     Koper                     386-66-34986

Sweden
  Autodesk On-line             Gothenburg                46-31-401718

United Kingdom
  CADenza BBS                  Leicester, UK          44-116-259-6725
  Raytech BBS                  Tain, Scotland         44-1862-83-2020
  The Missing Link             Surrey, England        44-181-641-8593

Country or long distance dial numbers may require additional numbers to be used. Consult your local phone company.

Next Section
Table Of Contents