[Freeciv-Dev] [Update] Corecleanup_11 uploaded to incoming

["Ross W. Wetmore" <rwetmore@xxxxxxxxxxxx>]

                                                                  2001/12/28

                         ReadMe for Corecleanup11 

General Caveats

While in many cases the code is cleaner and more general than the 
generalized topology patch, the main goal of these changes was to complete 
the client changes necessary to handle the standard and isometric wrapped 
topology sets in the GUI-GTK case (which is complex enough, thank you :-).

This should provide useful review discussion and a base for extending
this to other windowing systems or more generalized topologies when this
is required. In the meantime this provides a workable and useful Freeciv
playing environment for all current needs, as well as some improvments 
in documentation and algorithmic guidelines in code comments.

Included in the corecleanups besides robustness and standardization fixes 
are features such as multiple topologies, improved map generation, the 
river estuary movement patch, warmap and AI updates,


Native Isometric Maps

Native rectangular isometric maps with X and/or Y wrap topologies viewable
in trident (aka standard) or isometric GUI windows are possible with the
corecleanup_11-Dec27 patch to CVS. There are thus 8 topologies in two views
for 16 different flavours.

A key concept is the introduction of "native" coordinates. Present gaming 
coordinates use a standard map representation in which local operations 
such as adjacent iteration and distance computations are both convenient 
and hardcoded into Freeciv. Native isometric maps produce pi/4 rotated 
isometric rectangles and other topologies produce similar odd shapes which 
are not particularly intuitive or easy to work with in standard coordinates. 
For example, global operations such as whole_map_iterate, savegame, or debug 
printouts are more conveniently handled in a "native" 2-D rectangular format. 
Iterating in native coordinates avoids the need for complex loop conditions
or grossly inefficient bounding box hacks to cover the iteration set. It
also simplifies normalization in wrapping topologies.

It should be noted, that for the forseeable future the Freeciv map is 2-D.
Wrapping operations and global views are easiest to manage in a rectangular
format composed of lines and rows. This is even true for "filtered" 
topologies like ellipses, as there is still an underlying rectangular set
of points, some of which are real and some unreal depending on the filter
mask overlayed on this base representation.

It is also the case that a strict native representation may not be the most
economical format for storage or other purposes. For native isometric the
strict native grid only occupies every other point, i.e. all points lie on
a diagonal grid thus have indicies that are either all odd or all even. 
Compressed native is a format in which the x-axis is compressed by a factor 
of two. Uncompressing means doubling this value and adding the lowest y bit 
(for even diagonal grid), or complement y bit (for odd diagonal grid).

Thus all storage and global operations in corecleanup_11 are updated to use 
or loop over compressed even native coordinates with transformation to 
"standard" format where required.

In addition, GUI views and native or game coordinate calculations are 
completely separated and layered with conversion routines to move back and
forth. In addition to simplifying the logic in various complex nested
transformations this also means it is much easier to add a new GUI view
or mix and match GUI views/perspectives with different underlying map
topologies.

As a final, point, "native" isometric is really just a specific case of
pi/4 rotated topologies. Most of the native changes are suitable for use
in other cases in the same way the standard set can be used for those
that are "aligned" with the standard internal game coordinates.


Key Features or changes

Overview map

The rectangular overview map has been converted to use native coordinates.
If X-wrapping is present in the underlying map, the window will adjust to
centre the view-rectangle representing the GUI window. While Y-wrap could
also be used in the appropriate cases, this is not done as there is then 
effectively no orientation cues in the overview. This can be changed.

For code convenience, isometric is displayed in compressed native in the 
overview. This is not really distinguishable from an expanded version,
even though a fine eye might notice that the 2x2 pixel points were off
slightly on every other row. 

There is also no limit to overview scrolling in wrapped coordinates. One
can effectively orbit in a given wrapped direction ad nauseum.

GUI views

There is a black-tile border around all GUI views, though in some cases
it will be completely clipped by the canvas edges. In part this is to 
allow for an EXTRA_BOTTOM_ROW (and actually righthand column) where 
scrollbars eclipse some of the tiles. 

It is also the case that iso-tiles do not have rectangular edges. Thus
a little extra is required to manage the serrated effect, and fact that
some sprites extend beyond the top of their tile. 

In the worst case, where the tileset and the native map are not aligned,
it is necessary to have the GUI window project into the black rather than
just touch the edge tile, so that tiles along the edge can be viewed. In
the corners this can become a problem. Should your current viewing window
not allow you to see a corner tile, shrink its dimensions slightly so 
that the diagonal edge is smaller and fits further into the corner space.

Map generation

Map generation can be set to produce standard or isometric maps. Trident
tilesets are best used for viewing standard maps, as the "native" and
GUI axes are aligned. Similarly, isometric tilesets are best used for
isometric maps for the same reasons. 

It is however possible to view either map shape in the alternate tileset
which will cause the "N" direction to be rotated 45 degrees to lie along 
a diagonal axis.

Some additional cleanups have been added to the starting position selection
to attempt to reduce the number of cases where insufficient starting points
are found that match various "fairness" conditions. In particular, it is
now more likely that starting positions will span more than one large 
continent when there are two or more of roughly the same size, although
not enough to put every player on a separate private continent with equal
goodie richness.

Polar continents and Polar Passages

There is a control variable "separatepoles" which can be set prior to map
generation which will cause standard Civ polar continents and a polar E-W
passage to be created during map generation. The default is to do this.
There are slight additions to Karen's version. For example, there is no
icewall across the entire top/bottom of the map when this is turned off.

Especially in Y-wrapped (including Torus) maps, it is usually desirable 
to not produce a continental icewall across the map, but rather to let 
the continents fall where they may. This can produce polar islands which 
are split across the top and bottom of the map, but still permit ocean 
passage in these directions as well.

Note, without the forced icewall, Freeciv maps are quite temperate in
composition :-).

Civworld

A compatible version of civworld is available. It is not extensively
debugged, but was mostly used for map viewing in all the various flavours.
For compatible updates to civworld, contact rwetmore@xxxxxxxxxxxx.

Performance

There is some slowdown, which is much more noticable in Torus-World
maps. However, the corecleanup server is still faster than CVS in most
cases. Partly this is due to more extensive use of macros for the key
map functions (see map.h). Only unnormalize is typically called in its
functional form, though these forms exist for all in map.c

Testing

This has undergone several days of final continuous server autogames in 
all map flavours in addition to debug testing of feature functionality.
Several days overall have been spent in client autogame testing with
multiple windows running simultaneously showing different factions and 
views. Several partial games have been played as well. While heavily
laced with asserts, none appear to be triggered by any of the test runs
at this point.

Enjoy,
RossW
=====


This patch updates the corecleanup sets of changes to Dec 27, 2001,
i.e. it merges CVS changes to that point and should be applied to
the freeciv-cvs-Dec-27 snapshot.


Subject:  [Update] Corecleanup_11 patch
Date:     Dec 27, 2001
Author:   Ross Wetmore
Status:   Tested, fully functional and playable 
State:    Development snapshot

Description
  This patch upgrades the corecleanup patch set to CVS-Dec-27, plus
completes core and GUI coordinate handling for multiple wrap map topologies
for both standarad and native isometric maps.

Dependencies
  none

Recommended Use
  Apply the patch to a clean Dec 27 CVS snapshot in an alternate build
location. `sh configure` and `make` to build. Run either server autogame
or autogame with one or more client observers to get a feel for the
system changes. Compare code with current CVS using side-by-side editors
or side-by-side diff program (that ignores whitespace if possible). 

Examine client/{citydlg_common.c,mapview_common.c,gui-gtk/mapview.c}
for update_canvas, and map_to_canvas_pos() or canvas_to_map_pos()
coordinate handling algorithms, plus common/{map.c, map.h) for native
coordinate handling.

Files Changed:

freeciv/ai/advdomestic.c
freeciv/ai/advmilitary.c
freeciv/ai/aicity.c
freeciv/ai/aihand.c
freeciv/ai/aitech.c
freeciv/ai/aitools.c
freeciv/ai/aitools.h
freeciv/ai/aiunit.c
freeciv/client/citydlg_common.c
freeciv/client/citydlg_common.h
freeciv/client/climisc.c
freeciv/client/control.c
freeciv/client/goto.c
freeciv/client/gui-gtk/citydlg.c
freeciv/client/gui-gtk/mapctrl.c
freeciv/client/gui-gtk/mapview.c
freeciv/client/gui-gtk/mapview.h
freeciv/client/gui-mui/graphics.c
freeciv/client/gui-mui/mapclass.c
freeciv/client/gui-mui/mapview.c
freeciv/client/gui-mui/overviewclass.c
freeciv/client/gui-win32/citydlg.c
freeciv/client/gui-win32/mapview.c
freeciv/client/gui-xaw/mapctrl.c
freeciv/client/gui-xaw/mapview.c
freeciv/client/mapview_common.c
freeciv/client/mapview_common.h
freeciv/client/packhand.c
freeciv/client/tilespec.c
freeciv/client/tilespec.h
freeciv/common/city.c
freeciv/common/city.h
freeciv/common/game.c
freeciv/common/improvement.c
freeciv/common/packets.c
freeciv/common/player.c
freeciv/common/unit.c
freeciv/common/unit.h
freeciv/common/unittype.c
freeciv/server/autoattack.c
freeciv/server/citytools.c
freeciv/server/cityturn.c
freeciv/server/gamehand.c
freeciv/server/gamelog.c
freeciv/server/gotohand.c
freeciv/server/gotohand.h
freeciv/server/maphand.c
freeciv/server/maphand.h
freeciv/server/plrhand.c
freeciv/server/ruleset.c
freeciv/server/sanitycheck.c
freeciv/server/savegame.c
freeciv/server/settlers.c
freeciv/server/srv_main.c
freeciv/server/stdinhand.c
freeciv/server/unithand.c
freeciv/server/unittools.c
freeciv/common/map.c
freeciv/common/map.h
freeciv/server/mapgen.c
freeciv/server/mapgen.h