Crystal Space VC++ Win32 Development Readme
This is up to date as of July 30th, 1999

Written by Dan Ogles
Updated by Noote (Nathaniel Saint Martin)
Updated by Thomas Hieber

If you have any questions, contact me at thieber@gmx.net 
(or dogles@peachtree.com or noote@bigfoot.com).

Contents:
1.  Quickstart
2.  Working with the Workspace.
3.  Frequently Asked Questions.

---------[1] Quickstart - for the impatient -------------

To compile Crystal Space, you'll have to perform the following steps:
(Using Microsoft Visual C++ 6.0)

1. Load mk/visualc/csall.dsw

2. if you have not installed A3D SDK: unload SoundRenderA3D 
   (Files tab, right mouse button on SoundRenderA3D)

3. if you have not installed EAX SDK: unload SoundRenderEAX

4. if you have not installed Glide2x SDK: unload Glide2xRender

5. Make "All Files" you active project.

6. Select Menu "Build" "Rebuild All"

7. After a while you should finish with almost no warnings and no errors.

8. Change your settings in cryst.cfg (included in the Configuration Files folder
   in the CrystalSpace project) to the following (or whatever you like more):

     DRIVER = crystalspace.graphics3d.software
     WORLDFILE = data/large.zip

   This will set up CrystalSpace to run in software mode using the worldfile
   "large.zip". Make sure that you have downloaded a worldfile from the 
   Crystal Space Website before this. These files are in ZIP format and should
   be downloaded to the $/CS/data directory. Do not attempt to extract this 
   archive - Crystal Space decompresses the ZIP file at run time.

9. Open "Project", "Settings", select walktest on the left list. Select the 
   "Debug" tab in the register, select category "general" and enter the the 
   same directory the exe sits in as workdirectory. If the executable would be 
   in "E:\cvs\Cs\walktest.exe", you should select "E:\cvs\Cs\" as working 
   directory. Make sure you do these settings for "Win32 Debug" and 
   "Win32 Release" (Using the combobox on top of the left list).
   Then confirm the settings by pressing OK. Now select "WalkTest files" in 
   the Workspace files tab, click the right mouse button and select "Set as 
   active project". Now call "Build", "execute walktest.exe"

   alternatively, you can switch to the windows explorer and call walktest. 
   
10. Enjoy :-)

(Or see the FAQ section below)

---------[2] WORKING WITH THE WORKSPACE-------------------

The Crystal Space workspace is divided into several projects. They
all exist as separate project files (*.dsp). All of them are being bound
together by a workkspace. You can choose either csall.dsw or cssimple.dsw.
This workspace will also ensure correct linking between the various projects,
so you need to use a predefined workspace or, if you create your own,
you will have to set project dependencies right.

Currently the project files are created by using MS Visual C++ 6.0. I can't
tell you anything about other compilers or other versions of MSVC, because
6.0 is the only version I have at home. (It was reported, that for using
MSVC 5.0 you could use the project files, but would have to create a new
workspace.)


The libraries :
* Com -- the statically linked library which includes all the
  definitions for the interface IDs used in all the projects. This is linked
  into all of the projects.
* CsWs -- the window manager library (need for Mazed editor)
* CSpace - the static linked library, which includes the majority of the code

The drivers :
* SoftwareRender - the SoftwareRender DLL, which includes the 3D graphics
  driver for software rasterization. This is loaded by the CrystalSpace EXE.
* Direct3D5Render - the Direct3D Dx5 Render DLL, which includes the 3D graphics
  driver for Direct3D-accelerated rasterization. This is loaded by the
  CrystalSpace EXE.
* Direct3D6Render - the Direct3D Dx6 Render DLL, which includes the 3D graphics
  driver for Direct3D-accelerated rasterization. This is loaded by the
  CrystalSpace EXE.
* Glide2xRender - the Glide2x Render DLL, which includes the 3D graphics
  driver for Glide-accelerated rasterization. This is loaded by the
  CrystalSpace EXE.
* Glide3xRender - the Glide3x Render DLL, which includes the 3D graphics
  driver for Glide-accelerated rasterization. This is loaded by the
  CrystalSpace EXE. (Not yet working, and therefore not included in 
  csall workspace)
* OpenGLRender - the OpenGLRender DLL, which includes the 3D graphics
  driver for OpenGL-accelerated rasterization. This is loaded by the
  CrystalSpace EXE.
* DirectDraw2D - the DirectDraw Dx3 Graphics DLL, which includes the 2D graphics
  layer for DirectDraw screen devices. This is loaded by the CrystalSpace
  EXE.
* DirectDraw2D6 - the DirectDraw Dx6 Graphics DLL, which includes the 2D graphics
  layer for DirectDraw screen devices. This is loaded by the CrystalSpace
  EXE. it's Dx6 compatible and used by Direct3D Dx6 Render. (Not yet working, 
  and therefore not included in csall workspace)

* SoundDriverNull - A dummy sound driver
* SoundDriverWaveOut - A simple sound driver
* SoundRenderNull - A dummy 3D sound render
* SoundRenderA3D - A special 3D sound render. To use this, you will need
  the according SDK, which I don't have, so I don't know if this project
  will even compile. Normally you will unload that project.
* SoundRenderEAX - A special 3D sound render. To use this, you will need
  the according SDK, which I don't have, so I don't know if this project
  will even compile. Normally you will unload that project.
* SoundRenderDS3D - A DirectX 3D sound driver. 

* NetworkDriverNull - the null network Driver, This is loaded by the CrystalSpace
  EXE.
* NetworkDriverSock - the BSD Sockets network Driver, This is loaded by the CrystalSpace
  EXE.
* NetworkManagerNull - Dummy Network Manager. (The network manager is an layer
  above simple network services and offers more game oriented functions)
* NetworkManagerSimple - Dummy Network Manager. (The network manager is an layer
  above simple network services and offers more game oriented functions)

The applications :
* WalkTest -- a walktest application, which includes key handling and such.
* MazeD -- an editor. (Almost working, but progressing much slower, than 
  the CS engine.)
* PrimEdit -- an editor. (No project file inlcuded, because that project
  is dead. You might want to reanmite it anyway.)
* Simple -- a simple (minimum) CyrstalSpace application.

Note : Direct3DDx6 and Glide3x render currently don't work.

---------[3] FREQUENTLY ASKED QUESTIONS-------------------

Written by Xavier Trochu.
Updated by NooTe (Nathaniel Saint Martin)
Updated by Thomas Hieber

- How do I compile Crystal Space using Visual C++ 5.0?

MSVC 5.0 should work, if you have installed the latest Service Release, 
and the necessary SDK's (esp. DirectX. You will need at least the 
DirectX 5.0 SDK. The DirectX runtime version, that is usually bundled
with games will not be enough!). It should be enough to follow the
steps described in this doc. If you have further questions,
you might want to contact  "Brad 'GreyBear' Davis" <jbdavis@uswest.net>,
as he has recently reported successful compilation of CS, using MSVC 5.0.

- How do I compile Crystal Space using Visual C++ 6.0?

see section 1: Quickstart. Be sure to do exactly what is written there.
If that doesn't work, read on. :-)

I. COMPILATION TIME:

- Where are those damn zlib.h, png.h or jpeglib.h files?

Those files are not part of the Crystal Space project, but they are required
to build it. You must get a version of the following packages: ZLIB and LIBPNG.
Those packages can be easily found on the net. 
the latest version of the ZLIB sources are at:
    ftp://ftp.uu.net/graphics/png/src/zlib???.zip
the latest version of the LIBPNG sources are at:
    ftp://ftp.uu.net/graphics/png/src/lpng???.zip
the latest version of the JPEGLIB sources are at:
    ftp://ftp.uu.net/graphics/png/src/jpeglib???.zip

To make things easier you can download precompiled DLL's and lib's for
Windows at Jorrit Tyberghein's homepage:
    http://crystal.linuxgames.com
Check for libdlls.zip and read the included readme. This is the recommended way.
For CS Version 0.13 the locatation for the zlib files has changed. But there
are still some old versions of libdlls.zip floating around. You can either
download an up to date version from my homepage:
http://members.xoom.com/thieber/libdlls13.zip
If everything works alright the files should be in the following places:

CS\libs\libjpeg.dll
CS\libs\png.dll
CS\libs\zlib.dll
CS\include\cssys\win32\jconfig.h
CS\include\cssys\win32\jerror.h
CS\include\cssys\win32\jinclude.h
CS\include\cssys\win32\jmorecfg.h
CS\include\cssys\win32\jpeglib.h
CS\include\cssys\win32\png.h
CS\include\cssys\win32\pngconf.h
CS\include\cssys\win32\zconf.h
CS\include\cssys\win32\zlib.h
CS\libs\cssys\win32\zlib.lib
CS\libs\cssys\win32\png.lib
CS\libs\cssys\win32\libjpeg.lib

This is in fact the most common reason for not being able to compile CS,
so make sure, that you installed the files to the right places.

- Will I need to install additional SDK's?

If you are using MSVC 6.0 (as I highly recommend), you have all needed
headers and libraries for DirectX 5 and OpenGL installed. If you want
to use Glide, EAX, A3D or DirectX 6, you will have to download the SDK's
from their according sites.
If you want just to build Crystal Space using those API', but don't need
any docs or samples, you can get a mimum version of these API's from
NooTe's homepage. Take a look at:
http://www.multimania.com/noote/CrystalSpace 
in the Sources section. 
You will need a3d 2.0, eax 1.0 and Glide2x.
Of course, you can also get the full SDK at 
Aureal (A3D), CreativeLabs (EAX) and 3D/FX (Glide).

and the most current DirectX SDK from
http://www.microsoft.com 
(But they sometimes remove it after a while, so you can't be sure)


II. LINKING TIME:

- Where are the file png.lib and zlib.lib?

Just look above at the question about zlib.h and pnb.h! It's the same problem,
and if you have already done what is told there, I can't do much for you!


- I've got unresolved symbols!

What kind of symbols?
  _png_... : That means that you don't link the project with png.lib. Just
      take a look below where it is explained how to do so.
  _inflate... and _deflate... : Well, it seems to your project lacks
      zlib.lib. The trick is explained just below, so hang on.
  _DirectDraw... : Idem, but for ddraw.lib (DirectX component), look below.
  others        : Well, I always have a solution, but this one is more
      difficult. It seems that there is a missing source file in your
      project. But the question is, which source file? If it isn't obvious
      by the name of the functions, just to the following: In the menu
      "Edit", select the option "Find in Files...". Put the name of the
      function in the field "Find what", Check that the "In folder" field
      content is the CrystalSpace src directory and press "Find". You should
      get a bunch of files, many of them just making a call to the function.
      But there is surely one which contains the definition of the function.
      Look at the position of the file where it is defined, and add it to the
      project (Menu "Project"|"Add To Project"|"Files").

In order to add (or remove) a library for the link process, Let's go in the
menu "Project"|"Settings", "Link" Tab, "General" category. There is a field
called "Object/library modules" that lists all the libraries added to the
project at link time. 

OK, Now, it should link. So you should have an executable file called
"walktest.exe" in your src directory. Let's run it!


III. MISCELLANEOUS THINGS:

- When I want to launch Walktest I got an 'standard.zip not found' error!

Make sure you placed standard.zip into the same directory as the exe file
and have not unzipped it. If it is there, make sure, that walktest will
use the proper working directory. See Section [1] quickstart step 9 for
details on how to do this.

- When I start walktest I just get a black screen, maybe with some
  text output, but after a few seconds it drops back to the normal
  windows screen without an error

This shouldn't happen any more, because in most cases now, walktest
will display proper error messages. Anyway, you should make 
sure you have set an appropriate directory set. (see above)
Make sure you have the level given in cryst.cfg as WORLDFILE=
at the exact location available (also keep in mind, that your 
current directory is, where the executable sits.)

- I don't care about png support, what can I do?

It's easy. In the "Project"|"Settings" panel, choose the "C/C++" tab,
"General" Category, select the field "Preprocessor definitions" and remove
DO_PNG. Be sure to remove the png.lib from the modules added during link
time (see above).

- I don't care about Direct3D support.

Right click on the Direct3DRender project, and click "Unload project". It 
won't be compiled any longer after that. To reload it, right click on it and
click "Load Project".

- I have a working jpeg library, how can I let CrystalSpace use it?

Add DO_JPEG in the same place as above. Be sure to create the libjpeg
directory (with libjpeg.lib, jpeg.h, jerror.h, jmorecfg.h and jconfig.h in
it). 

- My last update did compile, but now I got a new version and everthing 
  seems to be broken.

When working with Crystal Space, always keep in mind, that this is a 
multiplatform project. So sometimes not all features will work correct
on all platforms. Sometimes a specific port may even be broken due to
changes in other ports. Since the introduction of CVS this is usually
only for a short time, so if you got your version out of CVS, it usually
pays off, to post a message describing the problems to the Crystal 
Space Mailing List (crystal@lists.linux.it) describing you problem and
enclude the exact error messages. If you wait a while, this will probably
be fixed, or at least be worked around.

- I compile for the first time, and I have a problem that you haven't 
  solved here!

Mail me at thieber@gmx.net. You can also try to reach Dan Ogles or Noote or
send a note to Crystal Space Mailing List (crystal@lists.linux.it). 
Don't forget to tell us if you're not a member of that list so that we can 
then send you a personal reply.

Hope this helps you!

Thomas Hieber
thieber@gmx.net
Xavier TROCHU
xtrochu@yahoo.com
NooTe (Nathaniel Saint Martin)
noote@bigfoot.com


