------------------------------------------------------------------------------
$File: //depot/povray/smp/windows/readme.txt $
$Revision: #7 $
$Change: 4572 $
$DateTime: 2008/02/18 06:22:49 $
$Author: chrisc $
------------------------------------------------------------------------------

NOTE: use of our source code in any other project (other than a fully-functional
custom version of POV-Ray) is prohibited. In other words you may make your own 
derivitive version (subject to the license conditions referenced below), but 
you may not remove functionality or incorporate the source code into another 
program.

Use of the POV-Ray source code is governed by the conditions laid out in 
distribution-license.txt and source-license.txt. Be sure you read these files 
(which are included in this source archive, and also linked from 
http://www.povray.org/povlegal.html) before doing anything with this source.

Furthermore, as this source code is a beta distribution, further conditions
are added. These further conditions are documented near the start of most
source files. One of these notices is reproduced below for your reference:

/*********************************************************************************
 * NOTICE
 *
 * This file is part of a BETA-TEST version of POV-Ray version 3.7. It is not
 * final code. Use of this source file is governed by both the standard POV-Ray
 * licences referred to in the copyright header block above this notice, and the
 * following additional restrictions numbered 1 through 4 below:
 *
 *   1. This source file may not be re-distributed without the written permission
 *      of Persistence of Vision Raytracer Pty. Ltd.
 *
 *   2. This notice may not be altered or removed.
 *   
 *   3. Binaries generated from this source file by individuals for their own
 *      personal use may not be re-distributed without the written permission
 *      of Persistence of Vision Raytracer Pty. Ltd. Such personal-use binaries
 *      are not required to have a timeout, and thus permission is granted in
 *      these circumstances only to disable the timeout code contained within
 *      the beta software.
 *   
 *   4. Binaries generated from this source file for use within an organizational
 *      unit (such as, but not limited to, a company or university) may not be
 *      distributed beyond the local organizational unit in which they were made,
 *      unless written permission is obtained from Persistence of Vision Raytracer
 *      Pty. Ltd. Additionally, the timeout code implemented within the beta may
 *      not be disabled or otherwise bypassed in any manner.
 *
 * The following text is not part of the above conditions and is provided for
 * informational purposes only.
 *
 * The purpose of the no-redistribution clause is to attempt to keep the
 * circulating copies of the beta source fresh. The only authorized distribution
 * point for the source code is the POV-Ray website and Perforce server, where
 * the code will be kept up to date with recent fixes. Additionally the beta
 * timeout code mentioned above has been a standard part of POV-Ray betas since
 * version 1.0, and is intended to reduce bug reports from old betas as well as
 * keep any circulating beta binaries relatively fresh.
 *
 * All said, however, the POV-Ray developers are open to any reasonable request
 * for variations to the above conditions and will consider them on a case-by-case
 * basis.
 *
 * Additionally, the developers request your co-operation in fixing bugs and
 * generally improving the program. If submitting a bug-fix, please ensure that
 * you quote the revision number of the file shown above in the copyright header
 * (see the '$Revision:' field). This ensures that it is possible to determine
 * what specific copy of the file you are working with. The developers also would
 * like to make it known that until POV-Ray 3.7 is out of beta, they would prefer
 * to emphasize the provision of bug fixes over the addition of new features.
 *
 * Persons wishing to enhance this source are requested to take the above into
 * account. It is also strongly suggested that such enhancements are started with
 * a recent copy of the source.
 *
 * The source code page (see http://www.povray.org/beta/source/) sets out the
 * conditions under which the developers are willing to accept contributions back
 * into the primary source tree. Please refer to those conditions prior to making
 * any changes to this source, if you wish to submit those changes for inclusion
 * with POV-Ray.
 *
 *********************************************************************************/

------------------------------------------------------------------------------
           PLEASE READ THIS FIRST - IT COULD SAVE YOU SOME HEADACHES
------------------------------------------------------------------------------

About this document
===================

This document does not attempt to explain how POV-Ray works or how to make 
modifications to it. Some of the internals of POV-Ray are highly complex; if 
you wish to gain a better understanding of that topic, please follow the link 
provided on the source code page mentioned below. This document is intended 
only to assist you in getting the POV-Ray source code built using an officially-
supported compiler on Win32 or Win64. Furthermore, no attempt is made to cover 
advanced subjects such as profile-guided optimization (though we will point out 
that the latter is definitely worthwhile, if you have the time and patience).

Assistance
==========

The POV-Team does not guarantee to provide assistance with compiling POV-Ray,
and as a general rule will not respond to emailed requests for assistance of 
this nature. Please use our support groups at http://news.povray.org/ or
news://news.povray.org/. These groups provide the best means for support with 
relation to this subject. We recommend you visit the povray.beta-test group 
there (presuming the beta is still current - if we have gone to a release of 
3.7, you should update your source with that version).

Visual Studio 2005
==================

Currently the only officially-supported means of building the Windows version 
of POV-Ray is via the Visual Studio 2005 project using a full version of Visual 
Studio and the compilers provided with it or with the platform SDK.

The express edition is reported to work in building 32-bit executables but this 
is not officially supported, and additionally takes some effort to get set up 
if you want to build the editor DLL's (these are optional). That said, we will -
time permitting - endeavour to assist express edition users in building 32-bit
versions of POV-Ray, but make no promises. We do not recommend that express
edition users attempt to build a 64-bit executable as the requisite compilers
are not supplied with VSE.

Earlier Versions of Visual Studio
=================================

Note that versions of Visual Studio prior to 8.0 (VS 2005) are not supported at 
all and furthermore WILL NOT WORK. The code in POV-Ray 3.7 requires a reasonably
up-to-date C++ compiler and STL, and earlier versions of VC++ are not compatible.

Intel Compiler
==============

Despite the fact that the last few official releases (including the current) of
POV-Ray for Windows were compiled with it, we can not recommend the use of any 
version of the Intel Compiler (ICL) with the POV-Ray 3.7 codebase (at least on 
Windows).

The last release of ICL known to work with any version of the POVWIN source 
was version 8, which is able to build version 3.6 of POV-Ray for Windows. Both 
version 9 and version 10 of the ICL suite have been observed to fail with 
various issues when working with the 3.7 codebase, both with and without use of 
the Visual Studio integrations.

Currently it may be possible to build an EXE with ICL version 10 if you turn 
off IPO, however this degrades performance and as such you may be better off 
with Visual C++. With ICL's IPO turned on, you will probably get a link failure 
with the message "internal error: backend signals", or possibly other internal 
errors. Please don't report this to us if you do as there is nothing we can do 
about it; the issues have reported to Intel numerous times since we began working
with ICL 9.

Other Compilers
===============

There are template config files for borland, mingw32, and watcom (aka openwatcom)
compilers, but these have not been updated for 3.7 and thus will require some 
(possibly considerable) work to get going. See the vfe\win\compilers\ directory 
for more information if you wish to attempt this (plus be sure to read the rest 
of this document, particularly the remarks about the custom entry point).

OpenEXR library
===============

The official beta binaries of POV-Ray are linked with the openexr library 
(http://www.openexr.com/). As with boost (mentioned below), we do not include
this library in our source tree, and if you want to use it, you will need to 
obtain and build it yourself. However, there is a problem in that the openexr 
projects for Windows do not build static libraries. POV-Ray does not currently 
depend on any non-os DLL's (it will even work without the editor DLL's present),
and we do not want to change this policy at this point. Thus, to make building
this beta source easier, we have disabled the use of openexr for the time being
(this is controlled by the macro OPENEXR_MISSING in vfe\win\syspovconfig.h).

If you wish to include openexr support, please remove the above macro and build 
suitable openexr libraries (make sure they are set for static RTL linking). 
You'll also need to place the path to the openexr include files into your VS 2005
path setup as per the instructions for boost below.

Please note that versions built without openexr support may not be re-distributed.

------------------------------------------------------------------------------
    SO YOU WANT TO COMPILE IT NOW ??? - QUICK START FOR THE IMPATIENT
------------------------------------------------------------------------------

We may have a 'quick start' section in the online version of these instructions. 
We won't include it here since abbreviated instructions are more prone to 
problems and thus more likely to need updating. Please visit the windows source 
page at http://www.povray.org/beta/source/windows/.

------------------------------------------------------------------------------
        READ THIS IF YOU ARE NOT USING VISUAL STUDIO 2005 FULL VERSION
------------------------------------------------------------------------------

VISUAL STUDIO EXPRESS USERS
---------------------------

Express edition users should not try to build the editor DLL's (cmedit and 
codemax projects) unless you have read this document in full and installed the 
ATL libs. These DLL's are not built by default, so you don't need to do 
anything about this unless you want to include them in the build automatically.

If you do want to compile the editors, you will need a file (atlthunk.lib) that 
does not ship with the express edition or in the platform SDK. A solution is
listed at http://www.codeproject.com/KB/wtl/WTLExpress.aspx.

VISUAL STUDIO 2008 USERS (EXPRESS AND FULL)
-------------------------------------------

Visual Studio version 9 does not support building applications for any version 
of Windows prior to Windows 2000. Currently the project file still targets 
earlier versions of Windows. To get the code to compile, right-click the povwin 
project, choose Properties, then expand "Configuration Properties" followed by 
"C/C++" and finally "Preprocessor". You will need to edit the preprocessor 
definitions for each configuration you target such that WINVER is set to 0x0500 
and _WIN32_WINNT is also 0x0500.

See http://msdn2.microsoft.com/en-us/library/6sehtctf.aspx for more information.

Additionally, boost 1.34.1 (see full instructions below for more information 
about boost) requires some minor patches before it will compile with VC9. This 
is fixed in the trunk version, however if you want to use 1.34.1, please read 
the following:

http://www.nabble.com/Re%3A-Preliminary-0.9.0-tarballs---VC%2B%2B-2008-Express-p14161224.html

------------------------------------------------------------------------------
                      INCLUDING THE EDITORS IN THE BUILD
------------------------------------------------------------------------------

 **************************************************************************
 * NOTE: it is not necessary to build the DLL's unless you want to modify *
 * the editor. They are loaded via LoadLibrary() and thus no import       *
 * library is required. You can also just use the official DLL's.         *
 **************************************************************************

Select the Configuration Manager (found in the Build menu) and for each 
configuration that you wish to build the editors with, tick the cmedit and 
codemax checkboxes.

------------------------------------------------------------------------------
                                  BUILD STEPS
------------------------------------------------------------------------------

FIRST: check out http://www.povray.org/beta/source/windows/ for an updated 
version of these instructions or of the source itself. This is IMPORTANT if you 
wish to avoid potential frustration! As we get feedback from others we will be
improving the build instructions and project files - if you strike a problem in
building the code, it could very well have been already solved. [Check the 
revision number at the head of this document against the version supplied via
the above web page if you want to know if it's different]. We will probably 
also have an area on http://wiki.povray.org/ dedicated to the source and its 
use.

           ====================================================

SECOND: make sure you have a working copy of the beta binary as supplied by the
POV-Team installed. This ensures that the appropriate registry settings and
support files are present. You may also need to install POV-Ray v3.61 to get
some of these, depending on whether or not the current beta includes an 
installer. If you don't do this, your compiled code will not work on your 
machine.

           ====================================================

THIRD: before attempting a compile you must obtain a recent version of the
boost libraries (http://www.boost.org/). We do not recommend use of any version
earlier than 1.34.1. At the very least you require the full set of headers plus
a version of the boost::threads library compiled for your target architecture
(32 or 64-bit). The library must be built for static linking with the compiler
run-time libraries. For 32-bit windows, an example of the libraries would be
'libboost_thread-vc80-mt-s-1_34_1.lib' and 'libboost_thread-vc80-mt-sgd-1_34_1.lib'
(the latter being the debug version).

If you are planning on making a 32-bit executable, you can save yourself some
time by visiting Boost Consulting at http://www.boost-consulting.com/products/free/
and downloading the most recent free version of BoostPro, then running it and 
selecting to install the boost:threads library. This provides the headers and 
pre-compiled versions of the thread libraries for 32-bit windows. When prompted
for which libraries you wish to download, it is only necessary to obtain the
multi-threaded libraries with static run-time-library. You do not need any DLL's.

If you are building for 64-bit, you may either build the library from the boost
source yourself, or ask in the POV-Ray beta group in case someone has made one
available.

However you get boost installed, you need to ensure that the path to its include
and library files are set up in Visual Studio's global settings, since the 
POV-Ray project files do not hard-code any particular path for it (apart from
not knowing where you install it, we also don't know what version you would be
building against).

To set this in VS 2005, select the Tools menu, then Options, and from the 
dialog that appears, expand 'Projects and Solutions' in the left pane and 
select the 'VC++ Directories' sub-item. For each of 'Include Files' and 
'Library Files' in the right-hand combo-box, ensure that the appropriate paths 
are set. You should do this for both Win32 and Win64 targets for consistency.

NB: the include path should be set to the root of the boost install. If you
choose to use the default location suggested by the above-mentioned installer,
this will probably be "C:\Program Files\boost\boost_1_34_1" or similar 
(depending on the version).

           ====================================================

FOURTH: open windows\vs8\povray.sln in Visual Studio 2005.

Set 'povwin' as the start-up project. Then, select the 'povcore' project and
expand 'Backend Headers', then open the file 'povray.h' listed within it. You
need to customize DISTRIBUTION_MESSAGE_2 as required. Note that if you do not
do this you will get compile errors.

Once you have taken whatever steps are needed as set out above, select your 
desired build (e.g. Win32 release - anything except SSE2|x64), hit F7, and 
wait. We recommend that you read the rest of this document while you are 
waiting.

If all goes well, you should end up with the POV-Ray for Windows executable as 
well as (if you selected to build them) the two editor DLL's. All 32-bit 
binaries should end up in windows\vs8\bin32, and the 64-bit ones should be in
windows\vs8\bin64.

Note: if you are building a DEBUG version of POV-Ray, be aware that that the 
executable will attempt to load the debug version of the DLL's. This will be an 
issue if you did not build them, since POV-Ray will complain (but will still 
work - you just won't have the editor). There is however a simple solution to 
this that doesn't require you to modify the source or build the DLL's: simply 
copy the standard editor DLL's that come with the official beta distribution to 
their debug equivalent names (e.g. copy cmedit32.dll to cmedit32d.dll, etc).

Note that the copied cmedit32.dll will still attempt to load povcmax32.dll
(i.e. the non-debug version), so it's not necessary to copy povcmax32 to its
debug equivalent.

NB you should never attempt to build the 'x64 SSE2' configuration: apart from 
the fact that this is by default excluded from the build in the configuration 
manager, it simply won't work. The only reason it is there at all is that 
Visual Studio 2005 insists on cloning the Win32 SSE2 project, no matter how 
hard we try to get rid of it. SSE2 is always enabled for x64 targets (it can't 
be turned off as it's a standard feature of all x64 CPU's) and thus the x64 
release project is all that is needed.


           ====================================================

FINALLY: please read the rest of this document while you're waiting for your
compile to finish, particularly the 'other stuff to keep in mind' at the end.

------------------------------------------------------------------------------
                             ABOUT THE EDITOR DLL's
------------------------------------------------------------------------------

You really don't need to worry about any of the following section unless you 
want to do editor hacking ; the DLL's provided with the POV-Ray for Windows 
binaries are sufficient, and therefore you don't need to compile them at all
if you don't want to.

The editor used in POV-Ray for Windows is based around a custom control called 
CodeMax, supplied courtesy of Barry Allyn. Our implementation consists of two
DLL's: cmedit32.dll and povcmax32.dll (in this case, as for the rest of the 
instructions, we will refer to the 32-bit versions; if building for Win64 then 
just replace the '32' with '64'). If you are building debug versions, the DLL's 
will be suffixed with a 'd' (for example, 'cmedit32d.dll').

The editor control itself is povcmax32.dll, and is built by the 'codemax' 
project in povray.sln. The other DLL, cmedit32, consists of support code that 
wraps and enhances the custom control, and provides services such as file I/O,
menus, state storage/restore, and many other things. This DLL is built by the
'cmedit' project.

For reference, while most of the POV-Ray-specific customization is done within 
cmedit, there are some POV-Ray specific modifications made to codemax itself, 
particularly with respect to the code completion support. However, for the most
part, if you are intending to modify some aspect of the POV-Ray interface to
the editor, you will find you will want to modify the contents of the cmedit 
project (or, possibly, pvedit.cpp in the windows directory - this implements 
the API between the POV-Ray executable and cmedit32.dll). Note that if you
alter this API at all, you must change the editor version (EDITDLLVERSION in
windows\pvedit.h).

By default (as of 3.7 beta 25b), POV-Ray will attempt to load the editor DLL's 
from the directory in which the EXE resides first. The previous strategy was to 
look in the current working directory first. POV-Ray no longer checks the CWD 
by default, though you can force that behaviour if you wish by using the switch 
mentioned below.

If a DLL with the right name is found with the EXE it will be used; otherwise,
the default binary directory is used (e.g. c:\program files\pov-ray for windows v3.7\bin,
depending on how you installed the beta). If you are not sure where it's 
looking, run pvengine with the /debug switch, then have a look at c:\povdebug.txt.
It will list the search paths attempted.

There is a switch available on the command-line which can alter the search 
path. If you specify /EDITDLLPATH on the command-line and follow it with a 
path, that path will be the only one checked. To force POV-Ray to look in the 
current directory (i.e. the one the EXE is launched from, which may not be the 
one the EXE is stored in), you can pass "." as the edit DLL path.

NOTE: currently POV-Ray for Windows has no way of differentiating the official 
editor DLL's from custom ones. We may at a future point provide a means for 
unofficial DLL's to be loaded by the official PVENGINE binary. In the meantime,
if you want to make absolutely sure that your unofficial binary doesn't load 
the official DLL's, and vice-versa, you can rename the DLL's. Doing this 
requires you to tell the EXE of course - to do this, open windows\pvengine.h 
and look for where EDITDLLNAME is defined. Just change that to suit, re-compile,
and rename the DLL's manually (or change the project to output different names).

------------------------------------------------------------------------------
                  OTHER STUFF YOU MIGHT WANT TO KEEP IN MIND
------------------------------------------------------------------------------

OTHER COMPILERS
===============

If porting POV-Ray for Windows to another compiler, or even if you're just 
writing a makefile for the Visual Studio 2005 version, be aware that there is 
some special configuration in the project settings. The most critical one to 
replicate is the entry point - POVWIN uses a custom entry point, and unless you 
adjust the code, it is essential this is called prior to the C run-time library 
startup code. It's also highly likely that you will need to change the code 
that calls the RTL from within POV-Ray as well, unless you are using the 
Microsoft RTL (or a compatible one).

CUSTOM ENTRY POINT
==================

Currently, the entry point is POVWINStartup, which is declared in pvmem.cpp.
We use this to set up a private heap prior to any memory allocation occurring
(including even allocations done to construct any global or static classes).
If WIN_MEM_TRACKING is defined (which it is by default), pvmem.cpp replaces
the standard new, new[], delete, and delete[] operators with its own ones. The
POV-Ray code already uses custom malloc and free functions which also pass
through pvmem.cpp.

MEMORY TRACKING AND DEBUGGING
=============================

Apart from tracking the amount of memory used and freed, the above tracking 
code, when _DEBUG is defined, will also provide a custom wrapper around each 
memory block which records where the new or malloc occurred. By default, _DEBUG 
also causes EXTRA_VALIDATION to be defined. When this is present, each block 
allocated has, in addition to the standard extra fields added to the start,
a single field of length sizeof(ptrdiff_t) added to the *end* of the block.
This is then initialized with a simple hash made up from various aspects of
the block, including its address, length, and the source line it was allocated
from. This is able to be checked at any time using the Validate() method to see 
if it has been altered since the block was allocated (e.g. by an overrun).

Additionally, while it has not yet been implemented, the memory hooks give 
us the opportunity to provide access to a low-fragmentation heap or other useful 
memory allocation techniques (e.g. handling allocations differently during 
renders, if we want) for the purpose of improving performance.

------------------------------------------------------------------------------
                                    THANKS
------------------------------------------------------------------------------

The POV-Team would like to thank all those who have assisted in bringing
POV-Ray 3.7 and its predecessors to the public - you know who you are, and we 
salute you.

