1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
|
<html>
<head>
<title>Building the POV-Ray for Windows source</title>
<style type="text/css">
body { background-color: #ffffee; }
p { font-family: Helvetica, Arial, sans-serif ; margin-top: 0.5em ; margin-bottom: 0.3em; text-align: justify; padding-left: 10px; }
pre { font-family: Lucida Console, Monaco, Courier, monospace ; padding-left: 10px; }
code { color: #0000a0; font-size: 0.9em; }
h1,h2,h3,h4,h5,h6 { font-family: Helvetica, Arial, sans-serif ; margin-top: 0.5em ; margin-bottom: 0.5em; color: #2040c0 }
h2 { background: #c6d4df; color: black; text-align: center; font-size: 1.25em; color: #103080; border: 1px solid; }
h3 { background: #d6e4ef; color: black; font-weight: bold; padding:0px 10px; }
h4 { padding-left: 10px; }
ul,ol,dl { font-family: Helvetica, Arial, sans-serif ; margin-top: 0.1em ; margin-bottom: 0.1em }
.Highlighted { background: #ffff00; }
.Main { width: 800px; }
.Note { font-size: 0.8em; font-family: "Lucida Console,Lucida Sans Typewriter" ;color: #000000 ; background-color: #d6f4e0 ; border: 1px solid ; border-color: #cfdbe5 ; padding: 3pt; margin-top: 5px; margin-bottom: 5px; margin-left: 10px; text-align: justify; }
.Quick { background-color: #d6f4e0 ; border: 1px solid ; border-color: #cfdbe5 ; padding: 3pt; margin-top: 5px; margin-bottom: 5px; margin-left: 10px; text-align: justify; }
.Header { width: 800px; background: white; color: black; text-align: left; border: 1px solid; }
.Header p { padding-right: 1em }
</style>
</head>
<body>
<div class="Header">
<p>
Persistence of Vision Ray Tracer ('POV-Ray') version 3.7.<br>
Copyright 1991-2013 Persistence of Vision Raytracer Pty. Ltd.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <a href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>
</p>
</div>
<br>
<div class="Header">
<pre><code>$File: //depot/public/povray/3.x/windows/readme.html $
$Revision: #1 $
$Change: 6069 $
$DateTime: 2013/11/06 11:59:40 $
$Author: chrisc $
</code></pre>
</div>
<div class="Main">
<h2>Building the POV-Ray for Windows source</h2>
<h3>About this document</h3>
<p>
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).
</p>
<h3>Assistance</h3>
<p>
Please use our support groups at <a href="http://news.povray.org/" target="new">http://news.povray.org/</a> or
<a href="news://news.povray.org/" target="new">news://news.povray.org/</a>. These groups provide the best means for support with
relation to this subject.
</p>
<h2>Compilers</h2>
<h3>Visual Studio 2010 and 2012</h3>
<p>
Currently the only officially supported means of building the Windows version
of POV-Ray 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.
</p>
<p>
The Visual Studio 2010 project is located in the "windows/vs10" subdirectory.
</p>
<h3>Earlier Versions of Visual Studio</h3>
<p>
Note that versions of Visual Studio prior to 8.0 (VS 2005) are not supported at
all and furthermore <b>will not work</b>. 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. VS 2005 <i>may</i> work but as it is not used or tested against
we do not recommend it. VS2008 <i>should</i> work as it was used for a portion
of the development process of POV 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.
</p>
<h3>Visual Studio Express</h3>
<p>
The express editions have been reported to work in building 32-bit executables
but this is not officially supported by us. The following information relates to
building with an express edition as of the last time we looked into it; things may have
changed with later releases (e.g. VS2012) so please take this into account when
reading the below.
</p>
<p>
At the minimum, you will need to download and install the Platform SDK as this
is not supplied with VS Express. It has also been reported that to obtain the
shlwapi.h header file (which provides functions such as <code>GetDLLVersion</code> etc), you
will need to allow the SDK setup to install the "Microsoft Web Workshop Build
Environment".
</p>
<p>
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 (at least, not as of VS2010).
</p>
<h2>Including the Editor Support DLL (cmedit) in the Build</h2>
<p class="Note">
It is not necessary to build the editor support DLL (cmedit), as it is loaded via
<code>LoadLibrary()</code> and thus no import library is required. You can just
use the DLL's included with the official version 3.7 binary distribution. If
however you do wish to build it, either enable it in the configuration manager
or initiate a build of that specific project manually.
</p>
<p>
cmedit acts as an interface between POVWIN and the full editor DLL (povcmax),
which is supplied as a binary with the official POV-Ray for Windows distribution.
The source code for povcmax is based on the codemax code editor and is not part
of the AGPL3 POV-Ray source distribution. If you wish to know more about the
editors, please refer to the "about the editor DLL's" section below.
</p>
<p>
<b>Note:</b> The editor DLL's are <i>not</i> required for POVWIN to work. If
they are not present or cannot be loaded, POVWIN is designed to be able to
function quite happily without them. The editor and its related functions
will simply not be present.
</p>
<h2>Build Steps</h2>
<ol>
<li>
<p>
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.
</p>
</li>
<a name="build">
<li>
<p>
Open <code>windows\vs10\povray.sln</code> 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 <code>'povray.h'</code> listed within it. Please
set <code>DISTRIBUTION_MESSAGE_2</code> to your real name to make
unofficial versions distinguishable from each other. Remove the <code>#error</code>
directive afterwards to proceed with the build. Note that if you do not
do this you will get compile errors.
</p>
<p>
By default, the GUI project is built, and the Console project is excluded. If you
wish to generate a simple console version of POV-Ray, please modify the configuration
as needed, edit vfe\win\syspovconfig.h to enable the definition of _CONSOLE as noted
therein, and build.
</p>
<p class="note">
<b>Note:</b> The windows console project is intended to be a simple example of
how to use the VFE library to make a console version of POV-Ray with <i>minimal code</i>.
It is <b><i>not</i></b> intended to be a fully-featured console build of POV. 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.
</p>
</li>
<li>
<p>
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.
</p>
<p>
If all goes well, you should end up with the POV-Ray for Windows
executable. All 32-bit binaries should end up in <code>windows\vs10\bin32</code>, and
the 64-bit ones should be in <code>windows\vs10\bin64</code>.
</p>
<p>
Note: if you are building a DEBUG version of POV-Ray, 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 <code>cmedit32.dll</code> to
<code>cmedit32d.dll</code>, etc).
</p>
<p>
Note that the copied <code>cmedit32.dll</code> will still attempt to load
<code>povcmax32.dll</code> (i.e. the non-debug version), so it's not necessary to
copy <code>povcmax32.dll</code> to its debug equivalent. The same goes for
<code>povcmax64.dll</code>.
</p>
</li>
</ol>
<p>
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.
</p>
<p>
Please read the rest of this document while you're waiting for your
compile to finish, particularly the 'other things you may want to keep in mind'
at the end.
</p>
<h2>About the Editor DLL's</h2>
<p>
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.
</p>
<p>
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: <code>cmedit32.dll</code> and <code>povcmax32.dll</code> (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, <code>'cmedit32d.dll'</code>).
</p>
<p>
The editor control itself is <code>povcmax32.dll</code>. The source for povcmax
is not distributed with the AGPL3 version of POV-Ray. If you do wish to obtain
this source it may be found in prior releases (such as the version 3.7 release
candidates, which were not AGPL licensed). Please note however that codemax is
NOT AGPL and was only included with POV-Ray under the terms of the former
POV-Ray license.
</p>
<p>
The other DLL, <code>cmedit32</code>, consists of support code that wraps and
enhances povcmax, and provides services such as file I/O, menus, state storage/restore,
and many other things. This DLL is built by the 'cmedit' project (which is by default
disabled via configuration manager).
</p>
<p>
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 <code>cmedit32.dll</code>). Note that if you
alter this API at all, you must change the editor version (<code>EDITDLLVERSION</code> in
<code>windows\pvedit.h</code>).
</p>
<p>
By default, POV-Ray 3.7 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, though you can force that behaviour
if you wish by using the switch mentioned below).
</p>
<p>
If a DLL with the right name is found with the EXE it will be used; otherwise,
the default binary directory is used. If you are not sure where it's looking,
create the directory <code>c:\temp</code> if it does not already exist and then
run <code>pvengine</code> with the <code>/debug</code> switch. Once it has loaded
have a look at <code>c:\temp\povdebug.txt</code>, which will list the search paths attempted.
</p>
<p>
There is a switch available on the command-line which can alter the search
path. If you specify <code>/EDITDLLPATH</code> 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 <code>"."</code> as the edit DLL path.
</p>
<p>
<b>Note :</b> 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 <code>windows\pvengine.h</code>
and look for where <code>EDITDLLNAME</code> is defined. Just change that to suit, re-compile,
and rename the DLL's manually (or change the project to output different names).
</p>
<h2>Other Things you May Want to Keep in Mind</h2>
<h3>Other Compilers</h3>
<p>
If porting POV-Ray for Windows to another compiler, or even if you're just
writing a makefile for the Visual Studio 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).
</p>
<h3>Custom Entry Point</h3>
<p>
Currently, the entry point is <code>POVWINStartup</code>, which is declared in <code>pvmem.cpp</code>.
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 <code>WIN_MEM_TRACKING</code> is defined (which it is by default), <code>pvmem.cpp</code> replaces
the standard <code>new</code>, <code>new[]</code>, <code>delete</code>, and <code>delete[]</code> operators with its own ones.
</p>
<h3>Memory Tracking and Debugging</h3>
<p>
Apart from tracking the amount of memory used and freed, the above tracking
code, when <code>_DEBUG</code> is defined, will also provide a custom wrapper around each
memory block which records where the new or malloc occurred. By default, <code>_DEBUG</code>
also causes <code>EXTRA_VALIDATION</code> 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 <code>sizeof(ptrdiff_t)</code> added to the <i>end</i> 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 <code>Validate()</code> method to see
if it has been altered since the block was allocated (e.g. by an overrun).
</p>
<p>
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.
</p>
<h2>The VFE Library</h2>
<p>
The VFE library included with the source acts as a wrapper for the communications
system ('POVMS') that connects the POV-Ray front and backend code (which are logically
separate, and may even be on separate computers). POVMS is a message-passing system
that is platform-neutral, thus allowing the backend to run on a different architecture
than the frontend.
</p>
<p>
VFE provides a worker thread and various abstractions that handle most of the work
of hooking a frontend up to the backend, even to the point where a frontend may be
transient or stateless (i.e. HTTP, hence the term 'virtual'). The Windows and Unix
versions of POV-Ray use VFE to connect the frontend to the backend.
</p>
<p>
If you wish to integrate POV-Ray into your own software (subject of course to the
terms of the AGPL3), it is strongly recommended that you first study the source
of povconsole.cpp, which implements a minimal example of how to setup and run a
render. A more comprehensive example of console integration is in the unix support
code, and for a GUI version, the windows support code should be read.
</p>
<p>
In either case, be sure to read through <a href="../vfe/vfesession.h">vfesession.h</a>; it is heavily
commented and is intended to be the primary reference to the API.
</p>
<p>
If you have issues with getting VFE to work with your own custom frontend,
please visit our support forums and ask about it: if there are any bugs or
shortcomings we would like to fix them. We will also try to offer general
assistance where possible, subject to time limitations.
</p>
<p>
If your project is commercial and you wish to have dedicated support, some of
the POV-Ray developers may be available for contract work, depending on the
circumstance. Please contact us for more information.
</p>
<h2>Thanks</h2>
<p>
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.
</p>
</div>
</body>
</html>
|
