UberPOV Raytracer version 1.37.
Portions Copyright 2013-2016 Christoph Lipka.

UberPOV 1.37 is an experimental unofficial branch of POV-Ray 3.7, and is subject to the same licensing terms and conditions.


Persistence of Vision Ray Tracer ('POV-Ray') version 3.7.
Copyright 1991-2016 Persistence of Vision Raytracer Pty. Ltd.

POV-Ray is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

POV-Ray 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 Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/

Building the UberPOV for Windows source

About this document

This document does not attempt to explain how UberPOV works or how to make modifications to it. Some of the internals of UberPOV 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 UberPOV 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

Please use the POV-Ray unofficial patches support group at http://news.povray.org/povray.unofficial.patches or news://news.povray.org/povray.unofficial.patches. This group provides the best means for support with relation to this subject.

Compilers

Visual Studio 2010 and 2012

Currently the only officially supported means of building the Windows version of UberPOV is via the provided Visual Studio 2010 project (you can also use it with VS 2012) with a full version of Visual Studio and the compilers provided with it or with the platform SDK.

The Visual Studio 2010 project is located in the "windows/vs10" subdirectory.

Visual Studio 2015

The Visual Studio 2010 projects should also build fine in Visual Studio 2015 after automatic conversion, as has been tested with the Visual Studio 2015 Community edition.

Note: By default, binaries generated by Visual Studio 2015 will be incompatible with Windows XP. If you need XP support, you will have to change the platform toolset from v140 to v140_xp, either by manually editing all project settings or by running the build from the command prompt with the environment variable PlatformToolset set to v140_xp.

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 UberPOV 1.37 requires a reasonably up-to-date C++ compiler and STL, and earlier versions of VC++ are not compatible. VS 2005 may work but as it is not used or tested against we do not recommend it. VS2008 should work as it was used for a portion of the development process of POV-Ray 3.7. In either case you will need to generate suitable project files, which is not as simple as just dropping all the source files into a new project and hitting F7. Please closely study the options applied to each project in the VS2010 solution if you wish to try to backport the projects.

Visual Studio Express

The express editions have been reported to work in building 32-bit executables but this is not officially supported, and additionally takes some effort to get set up. It is recommended to first try building POV-Ray 3.7, of which UberPOV 1.37 is an unofficial branch; a source distribution package of POV-Ray for Windows can be obtained from http://www.povray.org; once you are successful in building POV-Ray, it should be easy to adapt your build process to UberPOV.

Other Compilers

In order to build UberPOV with any other compiler, it is recommended to first try building POV-Ray 3.7, of which UberPOV 1.37 is an unofficial branch; a source distribution package of POV-Ray for Windows can be obtained from http://www.povray.org; once you are successful in building POV-Ray, it should be easy to adapt your build process to UberPOV.

Build Steps

  1. Make sure you have a working copy of the appropriate release binary installed. This ensures that the appropriate registry settings and support files are present. If you don't do this, your compiled code will probably not work on your machine.

  2. Open windows\vs10\povray.sln in Visual Studio 2010/2012. Set 'Windows Targets > GUI' as the start-up project if it is not already selected. Then, select the 'Generic POV-Ray > povbackend' project and expand 'Backend Headers', then open the file 'povray.h' listed within it. Please set DISTRIBUTION_MESSAGE_2 to your real name to make unofficial versions distinguishable from each other. Remove the #error directive afterwards to proceed with the build. Note that if you do not do this you will get compile errors.

    By default, the GUI project is built, and the Console project is excluded. If you wish to generate a simple console version of UberPOV, please modify the configuration as needed, edit vfe\win\syspovconfig.h to enable the definition of _CONSOLE as noted therein, and build.

    Note: The windows console project is intended to be a simple example of how to use the VFE library to make a console version of UberPOV with minimal code. It is not intended to be a fully-featured console build of UberPOV. If you wish to make a more comprehensive console version that runs on windows, please use the unix version as a guide - it uses the same principles (as it is also linked with VFE) but has more features.

  3. 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 UberPOV for Windows executable. All 32-bit binaries should end up in windows\vs10\bin32, and the 64-bit ones should be in windows\vs10\bin64.

    Note: if you are building a DEBUG version of UberPOV, be aware that the executable will attempt to load the debug version of POV-Ray's editor DLLs. In this case, if you want the editor to be available in the GUI, copy the standard editor DLLs that come with the official POV-Ray 3.7 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.dll to its debug equivalent. The same goes for povcmax64.dll.

NB you should never attempt to build the 'x64 SSE2' configuration (if it is present): 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 insists on cloning the Win32 SSE2 project every time it updates the solution file, 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.