map.h

Go to the documentation of this file.

/*
 * map.h
 *
 * Copyright (C) 2007-2009  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Definition of the basic aesop::map object.
 */

#ifndef AESOP_MAP_MAP_H__
#define AESOP_MAP_MAP_H__

// includes --------------------------------------------------------------------
#include "zone.h"                       // zone objects

#include <iostream>


namespace aesop {

/// \ingroup aesop_map_mgmt
/// \defgroup aesop_map AESOP Map and Zone Interfaces
///
/// \n
/// These are the basic Map and Zone definitions.  The AESOP framework provides
/// default implementations of these, but developers are free to create their
/// own.
///
/// See the comments for the Map class.  Map and Zone objects are used for
/// static data only.  They define the 3D space and its partitioning.  They
/// provide the immobile objects in the world.  Dynamics within a map are
/// handled by a different software layer (\ref map_dynamics).
/*@{*/


/// a destination describes a location to which players can be safely moved
struct destination_t {
        // constructor, manipulators
        destination_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        id[0] = 0;
                        rect.clear();
                }

        // data fields
        char                    id[eAESOP_IdBufferSize];///< id of start point
        rect3d_t                rect;           ///< 3D rect in zone
};



/// used by the Map::iterateZones() function
typedef void (*zone_iteration_fn)(IN Zone * zone,
                                IN void * context);


///     This is the base object used to describe an AESOP map.  From a Map
///     interface, it is possible to traverse and find all zones, static
///     content, etc.
///
///     For the purposes of the AESOP framework, the map defines an arbitrary 3D
///     region of space.  That space should be recursively partitioned into Zone
///     objects (see zone.h).
///
///     Map and Zone objects are intended to be faithful in-memory
///     representations of the static map data as stored on disk.  Any dynamic
///     map/zone objects are managed by client objects (such as MapDynamics).
///
///     Maps need to be threadsafe.  In practice this isn't interesting because
///     maps are read-only after they are loaded.  Anything that changes (such
///     as objects being added or removed, moving around, etc.) is handled by
///     the MapDynamics library, not the base Map or Zone objects.
///
///     <b>Maps should never be aware of drawing or rendering!</b>  Other
///     code libraries should use map data to handle drawing.  See
///     \ref map_drawer for one example.  Map and Zone objects are used on the
///     client and server.
class Map {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Map(void) throw();

        // aesop::Map class interface methods -----------------------------------
        virtual const char * getId(void) const throw() = 0;
        virtual Zone * getRootZone(void) throw() = 0;
        virtual Zone * getZone(IN const char * zone_id) = 0;
        virtual void iterateZones(IN zone_iteration_fn,
                                IN void * context) = 0;
        virtual const char * getDefaultStartingPointId(void) const throw() = 0;
        virtual void getStartingPointIds(OUT VecString& ids) const = 0;
        virtual void getStartingPoint(IN const char * id,
                                OUT destination_t& start) const = 0;
};



/*@}*/
////////////////////////////////////////////////////////////////////////////////
///
/// \ingroup aesop_map
/// \defgroup loading_maps Loading Maps
///
///
///     To load a map, you must first register a MapFormatReader with the
///     MapLoader.  Then you can ask the MapLoader to load a map, and it will
///     work with the registered MapFormatReaders to make that happen.
///
///     See \ref mapzone for a reference implementation.  But any MapFormatReader
///     that supports the aesop-map interfaces should work with all other
///     components (server, client, etc.).
///
///     <b>Why all this indirection?</b>  Precisely so that other server code
///     (physics engines, AI, ...) can be kept insulated from map formats.  It
///     remains to be seen if that is actually practical!
///
///     <b>Registration of map format readers is static.</b>  That is, once you
///     register a map format reader, the entire process knows about it.  For
///     all known use cases, that is acceptable.
///
///     <b>Order of registration matters!</b>  The first reader to claim a map
///     is asked to load it.
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/


/// This is the map loading routine clients should use.  It routes
/// to the correct registered \ref MapFormatReader, and notifies the given
/// notification interface of any type IDs encountered.
smart_ptr<Map> loadMap(IN const char * id,
                                IN const char * path_to_map_file);



/// MapFormatReader: these have to be implemented elsewhere, and then registered
///   with the MapLoader below.
///
/// <b>The APIs on this interface can be called by multiple threads
/// simultaneously.</b>  Anyone who implements this interface must do so in a
/// threadsafe manner!  
class MapFormatReader {
public:
        // virtual destructor --------------------------------------------------
        virtual ~MapFormatReader(void) throw();

        // aesop::MapFormatReader class interface methods -----------------------
        virtual const char * getDescription(void) = 0;
        virtual bool isMyFormat(IN const char * mapId,
                                IN const char * path_to_map_file) = 0;
        virtual smart_ptr<Map> loadMap(IN const char * mapId,
                                IN const char * path_to_map_file) = 0;
};



/// This is how you can register a \ref MapFormatReader with the map loader.
void registerMapFormatReader(IN smart_ptr<MapFormatReader>& reader);



};      // aesop namespace

#endif  // AESOP_MAP_MAP_H__