# README.msvc.txt - 2011-10-02 - v0.4.9
# Commenced 2010-04-24 - v0.4.6

Atlas - http://atlas.sourceforge.net/

Compiling Atlas Source in native Windows, using MSVC8 Express (2005).

All projects, Atlas, Map, and win_util.lib are compiled using the
Multi-threads runtime, /MT (& /MTd), as are ALL the dependants.
Getting this wrong causes lots of hassles.

There is a general, hand crafted project/msvc/config.h file,
where you can adjust the version, and perhaps the default
location of the FlightGear data, set as C:\FG\29\data in
my case. See FGBASE_DIR, but this can be over-ridden on the
command line, so is not so important.

There are also some options macros in that file to explore.

Note the need to adjust the OpenSceneGraph (OSG), and Boost paths
below. These must be adjusted in the MSVC IDE BEFORE doing a build.

==========================================================================

Directory Arrangement:
---------------------

1. Using the '3rdparty' system
==============================
In this build, _ALL_ the dependant includes and libraries
are included in the [projects\3rdparty] folder. No other
sources are required if these headers and libraries
are used, except as noed below for OSG and Boost.

Build Set: Atlas.sln (Atlas.vcproj, Map.vcproj, GetMap.vcproj win_ulib.vcproj)
Build Set: Atlas.dsw (Atlas.dsp, Map.dsp, GetMap.dsp win_ulib.dsp)

NOTE WELL: TWO DEPENDENCY PATHS MUST BE ADJUSTED IN EITHER BUILD SET
********************************************************************
For OSG:   Uses: C:\Projects\OSG\OSG-3.0.1\include
For Boost: Uses: C:\FGCVS\boost-trunk
In both cases, only the HEADER includes are required. No libraries needed.

But if you wish to download, and build all the dependencies
yourself, then read on, else skip to Compiling:

2. External Sources
===================
Choose a folder for the Atlas source. I chose 'Atlas',
and I put most of the dependencies in the root of
Atlas. That is :-
<some root>\Atlas - Full source of Atlas/Map
           \simgear
           \PLIB
           \zlib-1.2.3
           \boost_1_42_0
           \lpng
           \etc...
although some are compiled in my C:\Projects folder,
such as :-
C:\Projects\jpeg-8a
           \glew-1.7.0 (no longer optional)

Naturally, any difference in the Directory Structure must
be adjusted in the MSVC IDE <project> Property Pages.

==========================================================================

Dependencies:
------------

Essentially, Atlas is sort of part of the FlightGear project,
so once you have compiled FlightGear, you will have most of
the following dependencies already.

FlightGear - binary, and at least the base 'data'
site: http://www.flightgear.org/
I used a recent git version, but there are release versions available.

Simgear - Simulator Construction Tools 
site: http://www.simgear.org/
I used a recent git version, downloaded, and compiled as part of FlightGear,
BUT it is highly recommended that you use a RELEASE version, last was 2.4
for linking with Atlas/Map.

PLIB - STEVE'S PORTABLE GAME LIBRARY
site: http://plib.sourceforge.net/index.html
I used the CVS version, downloaded, and compiled as part of FlightGear

GLUT - freeglut, OpenSource alternative to the OpenGL Utility Toolkit (GLUT) library
site: http://freeglut.sourceforge.net/
I used the SVN version, downloaded, and compiled as part of FlightGear

zlib - A Massively Spiffy Yet Delicately Unobtrusive Compression Library
site: http://www.zlib.net/
I used Version 1.2.3 (July 2005), although I note there is now a 1.2.4.
Downloaded: 08/20/2009  19:26 496,597 zlib-1.2.3.tar.gz
and compiled as part of FlightGear

OpenSceneGraph - open source high performance 3D graphics toolkit
site: http://www.openscenegraph.org/projects/osg
I used a relatively recent reelease 3.0.1 SVN version, compiled as part of FlightGear

libpng - Portable Network Graphics
site: http://www.libpng.org/
I used version lpng1232.zip, but note there is now a 1.4.1 (lpng141.zip)
Compiled as part of building OSG for FlightGear

Boost - portable C++ source libraries
site: http://www.boost.org/
I alternate between using the SVN trunk, and version 1.39.0 and 1.42.0
SVN trunk failed, but should perhaps be fixed by now.
ONLY the boost headers are required - no compiling.

Jpeg - Independent JPEG Group (IJG)
site: http://www.ijg.org/
Download and compile: 04/16/2010 11:14 1,037,823 jpegsr8a.zip, or later
I compile the libraries as jpeg32.lib and jpeg32d.lib

OpenGL Extensions
-----------------

GLew - The OpenGL Extension Wrangler Library
site: http://glew.sourceforge.net/
Download, unzip, and compile: glew-1.7.0.zip, or later...
Then include <GL/glew.h>, using a GLEW_STATIC macro, and link with glew32s.lib...
So I used this 'static' library, rather than the DLL approach.

See [projects/msvc/config.h] for some option macros to control this, but 
now the dependency on GLEW is in the base repo, so can NOT be turned off.

==========================================================================

Compiling:
----------

The folder 'projects/msvc' contains two types of MSVC build files,
and various other needed items. For full compatibility, there
is an Atlas.dsw, which can be loaded, and converted by any version
of MSVC. This is the recommended set. It is better to run
the delsln.bat before loading and converting the dsw/dsp files,
to avoid MSVC questions.

Aternatively there are 'solution' files, Atlas.sln, specifically
for MSVC8 (2005).

Loading one of these build file sets into your MSVC, and build.

Naturally, if you have put external dependencies in different folders,
other than projects\3rdparty\include, and projects\3rdparty\lib,
used in this build file set, then these will need to be adjusted.

As mentioned else where it is almost certain you will have to adjust the 
include paths for OpenSceneGrap (OSG), and Boost in the MSVC IDE 
before commencing a build.

The <project> Property Pages -> C/C++ -> General -> Additional
Include Directories (AID) _MUST_ be set right. Likewise for the
Linker -> General -> Additional Library Directories (ALD) must match
the library list in -> Input -> Additional Dependencies (AD)! And
these can vary between Debug and Release builds.

Especially see specific notes above about the path the OSG and Boost 
include files. No libraries of these are needed for Atlas/Map.

And REMEMBER to _ALWAYS_ carefully check the RUNTIME being used,
both for Atlas, Map, and _ALL_ the dependant components. I chose
Multi-threads (static) runtime, /MT, and /MTd for Debug. As stated,
using inconsistent runtimes causes lots of PAIN ;=().

==========================================================================

Running:
--------

1: Map: This need to be run first, to generate the MAPS to be used
by Atlas. The 'default' location is <FG_ROOT>\Atlas. Run
map.exe --help to see the input options...

This will scan the <FG_ROOT>\Scenery, and build 'map' for the
San Francisco area, and any other areas you have downloaded
and installed. These will be output into a series of folders
call 10, 9, 8, 6, 4,... depending...

These are the maps to be loaded by Atlas when it is run.

For example, my Map command line - all one line -
Map.exe --fg-root=C:\FG\32\data --atlas=C:\FG\32\data\Atlas \
--palette=C:\FG\32\data\Atlas\Palettes\default.ap  --fg-scenery=C:\FG\32\data\scenery

Or a verbose form, NOT using the frame buffer extensions - render in window, as before...
Map.exe --verbose  --render-to-window --fg-root=C:\FG\32\data \
--atlas=C:\FG\32\data\Atlas --palette=C:\FG\32\data\Atlas\Palettes\default.ap \
--fg-scenery=C:\FG\32\data\scenery

This source includes a runmap.bat batch file, to give it a try. If you use 
an output directory of 'temp', there is also a viewtemp.htm to view the 
generated map files in your default browser.

2: Atlas: Usually some setup of needed data must be done, in
addition to the above map generation, before Atlas is run.
It needs to be able to load -
(a) backgound.jpg - to provided a global world image.
(b) Palettes\default.ap - to desinate the colors
(c) Fonts\Helvetica-Bold.100.txf and Helvetica.100.txf
(d) And the 'maps' in 10, 9, 8, etc.

Atlas.exe --fg-root=C:\FG\32\data --atlas=C:\FG\32\data\Atlas\temp2 --palette=C:\FG\32\data\Atlas\Palettes\default.ap --fg-scenery=C:\FG\32\data\Scenery
Atlas.exe --fg-root=C:\FG\32\data --fg-scenery=C:\FG\32\data\Scenery --atlas=temp6 --palette=temp6\Palettes\default.ap

This source includes a runatlas.bat batch file, as a work in
progress, to give it a try after you have generated the maps.

I maintain a site specifically on building FlightGear, and related
projects - see : http://geoffair.org/fg/atlas-07.htm, and others...

Have fun ;=))

Geoff.
2011-10-04
2010-04-24

ATLAS Debug test string:
--fg-scenery=C:\FG\29\data\Scenery --atlas=temp --palette=default.ap

# EOF - README.msvc.txt
