------------------------------------------------------------------------------
$Id: //depot/povray/3.5/windows/readme.txt#1 $
------------------------------------------------------------------------------

NOTE: Use of the POV-Ray source code is governed by the conditions laid
out in POVLEGAL.DOC. Be sure you read that file (which is included in this
source archive, and also at http://www.povray.org/povlegal.html) before
doing anything with this source.

In summary, if you are only going to be compiling this source for your
own education, and will not be distributing the resulting EXE or DLL's,
then basically you're OK.

Distributing any binaries, or modified source, requires that you comply with 
POVLEGAL.

Use of our source code in any other project (other than a fully-functional 
custom version of POV-Ray) is prohibited. See POVLEGAL.

The POV-Team provides no assistance with compiling POV-Ray. The POV-Ray
news server at http://news.povray.org/ and news://news.povray.org/ provides 
the best means for support with relation to this subject. We recommend you 
visit the povray.programming group there.

------------------------------------------------------------------------------

NOTE: Be sure to read this document before attempting a compile ! Folks who
come complaining to the povray news groups about not being to compile because
of a missing 'htmlhelp.h' will be given very short shrift !

------------------------------------------------------------------------------

This archive contains all the code needed to compile the Windows version
of POV-Ray v3.5 (excluding any compiler or operating-specific header files
and libraries that are supplied by Microsoft). You will need either Visual
Studio v6, or the Intel C++ compiler v5 or 6. Other versions of these
compilers may work but have not been tested. Other compilers (e.g. watcom,
borland) may or may not work, we haven't tested these either.

NOTE: to avoid some confusion, please remember this: POV-Ray v3.5 requires
a C++ compiler (NOT a plain C compiler, as per previous versions). While most 
of the source code is still 'C', we have used some C++ features in a few 
places. The core source code files have been renamed using the extension 'cpp',
but the windows ones HAVE NOT. Even though the windows files use '.c', you 
still need to compile in C++ mode! The included projects handle that for you,
but if you are building a makefile from scratch you would do well to remember
this.

NOTE: you must have already installed the POV-Ray for Windows v3.5 binary
files from the povray website to be able to use the resulting EXE. This source 
on its own won't be a lot of use to you (unless you only want to study it).

The directory tree is as follows:

+--source .................. Generic POV-Ray core renderer code.
  +--jpeg-6b ................ JPEG library
  +--lpng121 ................ PNG library
  +--tiff-v3.5.7 ............ TIFF library
  +--zlib ................... ZLIB libary (needed for PNG support)
+--windows ................. Windows-specific platform support code
   +--bitmaps ................ BMP files used as windows resources
   +--codemax ................ Editor wrapper source code files
     +--component ............. C++Builder v3 source for codemax component
     +--source ................ Actual source code for editor itself
   +--guiext ................. Sample source code for POVWIN GUI Extension
   +--icons .................. Icon resources
   +--vc6 .................... Visual Studio 6 projects, also ICL makefile
   +--ztimer ................. Precision timer library

In the WINDOWS\VC6 subdirectory you will find a file called povray-icl.mak.
This is only of use if you have the Intel C++ compiler v5 or 6 installed.
The POV-Team uses this compiler when making release builds. If you use the
ICL compiler, the SSE2 code in WINDOWS\INTELSSE2.H will be built and activated,
resulting in a significant improvement in the speed of the noise and dnoise
functions on Intel Pentium 4 CPU's. (Note: when compiling this binary, you
may get a complaint from the linker that the symbol _main is undefined. You 
may safely ignore this).

The VC6 workspace contains the following projects -

  00 README
    A utility project that contains this README file.

  cmedit
    A utility project that contains the codemax editor wrapper files.
            NOTE: YOU CANNOT COMPILE THIS PROJECT FROM VC6.
    The project is included as a convenient way for the POV-Ray developers to
    get access to these files while editing other parts of the POV-Ray source.

    To compile this source code you need Borland's C++Builder, version 3 (or
    possibly later versions). You also need to build and install the cmpkg
    component to C++Builder first.

  cmpkg
    A utility project that contains the codemax C++Builder interface source.
              NOTE: YOU CANNOT COMPILE THIS PROJECT FROM VC6.
    The project is included as a convenient way for the POV-Ray developers to
    get access to these files while editing other parts of the POV-Ray source.

    To compile this source code you need Borland's C++Builder, version 3 (or
    possibly later versions).

  codemax
    This is the source code for Winmain's Codemax editor custom control, with
    Nathan Lewis's codelist addition and modifications made by the POV-Team.

  guidemo
    This project builds a demonstation GUIEXT (gui extension) for POVWIN. Note
    that it will not compile as-is; you need to modify guiext.c in all places
    indicated (where there are #error directives). You don't need to compile
    this unless you want to make a GUIEXT (most people don't). GUIEXT's are
    special DLL's that allow other programs to communicate with POV-Ray for
    Windows and obtain output from it. (For example, the popular Moray modeller
    uses this technique ; see http://www.stmuc.com/moray/).

  jpeg
    The JPEG library source. You don't need to compile this manually.

  libpng
    The PNG library source. You don't need to compile this manually.

  povray
    The main POVWIN project. Building this will automatically build the jpeg,
    libpng, tiff and zlib projects. You don't need to build any other projects
    as the compiled DLL's needed for POVWIN will have been installed when you
    installed the normal POV-Ray for Windows v3.5 binaries.

  tiff
    The TIFF library source. You don't need to compile this manually.

  zlib
    The ZLIB library source. You don't need to compile this manually.

All you need to do to get a working POV-Ray for Windows binary is to edit the
files WINDOWS\PVENGINE.C, to define your class name prefix (search for 
CLASSNAMEPREFIX), WINDOWS\PVENGINE.H (search for UNOFFICIALCOMPILE), and 
SOURCE\OPTOUT.H to define your name and email address in the distribution 
message (search for DISTRIBUTION_MESSAGE). Then, activate the POVRAY project 
and hit F7. Assuming you have the requisite libraries, you should end up with 
the file WINDOWS\VC6\BIN\PVENGINE.EXE.

NOTE: you will need the Microsoft HTMLHELP library and header files, which are
not distributed with VC6 by default. You can download this from the Microsoft
www server (we won't give you the URL since Microsoft seems to think that
moving the location of files every few months is a good way to run a web site).

ABOUT THE EDITOR
----------------

The editor used in POV-Ray for Windows is a custom control called CodeMax. It
provides the core editing functionality that you see in the edit windows. 
However, there is a lot more to the editor than that, as we will explain.

The custom control (project codemax in the workspace) produces a DLL called 
POVCMAX2.DLL. This DLL is loaded by another DLL, CMEDIT.DLL. CMEDIT.DLL is 
produced from the source code in the WINDOWS\CODEMAX subdirectory, using 
Borland's C++Builder compiler, version 3 (or possibly later versions, though 
this has not been tested). POVCMAX2.DLL is never loaded directly by PVENGINE
itself.

CMEDIT contains the support code needed to turn the custom control in POVCMAX2 
into a fully-featured editor, as well as adding some extra functionality. 

If you want to change the editor core code, all you need to do is to modify  
and recompile POVCMAX2. If you need to modify the way the wrapper code or 
enhancements work, then you need to rebuild CMEDIT, and for that you need 
Borland's compiler installed.

The CMEDIT project uses a custom package to encapsulate the codemax DLL into 
a C++Builder run-time component. (Note that this is NOT a visual component, 
you won't see it on your palette). The code for this package is in the 
WINDOWS\CODEMAX\COMPONENT subdirectory. You must build this and install the 
resulting package into C++Builder before compining CMEDIT. Instructions as to 
how to do this are beyond the scope of this document, see the C++Builder 
manuals.

If all this sounds complicated, well, it kind of is, but it's not ;)

You really don't need to worry about any of the above unless you want to do
editor hacking ; the DLL's are provided with the POV-Ray for Windows binaries
are sufficient, and therefore you don't need to compile this stuff at all if 
you don't want to. And if all you want to do is compile the codemax DLL itself
then you don't need C++Builder.

Be aware that if you do compile new DLL's, you'll need to put them somewhere
useful for them to be loaded. The best place is the <installdir>\bin directory 
of the POV-Ray for Windows binary install (make sure you back up the original 
DLL's first).

If you define the macro DEVELOPMENT in WINDOWS\PVENGINE.C (just search for 
this, it's commented out by default, and is near the top of the file), the 
resulting PVENGINE.EXE will use a different search strategy for the editor 
DLL's. Just look at the source for details.

THANKS
------

The POV-Team would like to thank Perforce software for supplying the turbo-
studly revision control system we used in developing POV-Ray v3.5. It saved
us numerous headaches. Also thanks to Wise Solutions for supplying the copy
of the Wise installation system we used in making the setup program, and of
course to Winmain software for supplying us with the editor that has been
included in POVWIN since version 3.1 (CodeMax was at that time a commercial
product ; it is now freeware, thus allowing us to include its source with
POVWIN for the first time). Finally thanks to Intel Corporation for the
compilers we use to generate our release compiles.
