# mapzone.h

Go to the documentation of this file.
00001 /*
00002  * mapzone.h
00003  *
00004  * Copyright (C) 2008,2009  Thomas A. Vaughan
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  *
00031  * Entry point for the mapzone library.  See the aesop-map headers.
00032  * Basically, this is a particular implementation of maps + zones.
00033  */
00034
00035 #ifndef AESOP_MAPZONE_H__
00036 #define AESOP_MAPZONE_H__
00037
00038 // includes --------------------------------------------------------------------
00039 #include "aesop-map/map.h"
00040
00041
00042 namespace mapzone {
00043
00044 ////////////////////////////////////////////////////////////////////////////////
00045 ///
00046 /// \ingroup aesop_map_mgmt
00047 /// \defgroup mapzone Reference Map/Zone Implemenation
00048 ///
00049 /// \n
00050 /// This is a reference implementation of \ref aesop::Map and
00051 /// \ref aesop::Zone objects.  The main design objectives of this
00052 /// implementation are:
00053 ///  - Easy for humans to read and write the raw map/zone data files.
00054 ///  - Easy for scripts to autogenerate raw map/zone data files.
00055 ///  - Easy to parse the raw map/zone data files.
00056 ///  - Decent (but not great!) performance.  Loads in particular still have
00057 ///     a high amount of text parsing and allocations that could be avoided.
00058 ///
00059 /// Note that there are some explicit non-goals:
00060 ///  - No support for auto-creation of zones (that is, no support for auto
00061 ///     space partitioning).  Zone creators will have to do that themselves.
00062 ///  - Not designed to be blazingly fast for loads/saves.
00063 ///  - Not designed to be blazingly fast for queries (but a map/zone creator
00064 ///     who is smart about partitioning their zones should be fine).
00065 ///
00066 /// This is supposed to be a reference implementation to illustrate how some
00067 /// of these interfaces can be built, and to be useful to storytellers that are
00068 /// willing to trade some performance for usability.
00069 ///
00070 ////////////////////////////////////////////////////////////////////////////////
00071
00072 /*@{*/
00073
00074
00075 ////////////////////////////////////////////////////////////////////////////////
00076 //
00077 //      public API
00078 //
00079 ////////////////////////////////////////////////////////////////////////////////
00080
00081 /// factory method to create mapzone map format readers
00083
00084
00085
00086 ////////////////////////////////////////////////////////////////////////////////
00087 //
00088 //      internals
00089 //
00090 //      Don't use these outside of the mapzone library!
00091 //
00092 ////////////////////////////////////////////////////////////////////////////////
00093
00094 /// data type: maps from zone ID --> zone object
00095 typedef std::map<std::string, smart_ptr<aesop::Zone> > zone_map_t;
00096
00097
00098 // load maps + zones from streams (don't use these!  Use getMapFormatReader()
00099 smart_ptr<aesop::Map> loadMap(IN const char * id,
00100                                 IN std::istream& stream);
00101
00103                                 IN aesop::Zone::eType type);
00104
00105 // again, internal only.  After all zones are loaded, zones can resolve IDs
00106 void resolveZoneIds(IN aesop::Zone * zone,
00107                                 IN zone_map_t& map);
00108