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. If you are not sure where it's looking, create the directory c:\temp if it does not already exist and then run pvengine with the /debug switch. Once it has loaded have a look at c:\temp\povdebug.txt, which 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 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.

Standard Source Code Notice

/*********************************************************************************
 * 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.
 *
 *********************************************************************************/