# zone.h

Go to the documentation of this file.
00001 /*
00002  * zone.h
00003  *
00004  * Copyright (C) 2007-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  * Declaration of the basic Zone interfaces.  Anyone that wants to construct
00032  * aesop maps had better understand how these work.
00033  */
00034
00035 #ifndef AESOP_INTERFACE_ZONE_H__
00036 #define AESOP_INTERFACE_ZONE_H__
00037
00038 // includes --------------------------------------------------------------------
00039 #include "typeinst/typeinst.h"
00040
00041
00042 namespace aesop {
00043
00044
00045 // forward declarations
00046 class LeafZone;
00047
00048 /// \ingroup aesop_map
00049 /*@{*/
00050
00051
00052 ///     Any 3D map defines an arbitrary 3D region of space.  For efficient
00053 ///     rendering and AI, this space must be recursively partitioned into
00054 ///     subspaces.  Any internet search for "Space Partitioning" will reveal
00055 ///     popular and useful methods such as BSP trees, Octrees, kd trees, etc.
00056 ///
00057 ///     The aesop server doesn't care what partitioning strategy is used.  All
00058 ///     that is important is that the space is correctly partitioned into
00059 ///     disjoint sets.
00060 ///
00061 ///     A Zone is a 3D region of space which (in general) completely contains
00062 ///     a number of subzones, which contain subzones etc.
00063 ///
00064 ///     Zones are static.  That is, for a given map, the zone structure does
00065 ///     not change during gameplay.  However, objects can move around in and
00066 ///     between zones.
00067 ///
00068 ///     <b>Zones should never be aware of drawing or rendering.</b>  Other code
00069 ///     libraries can use Zone objects to draw.
00070 class Zone {
00071 public:
00072         // public typedefs -----------------------------------------------------
00073         enum eType {
00074                 eType_Parent            = 0x01, ///< contains subzones
00075                 eType_Leaf              = 0x02, ///< leaf zone (aesop::LeafZone)
00076                 eType_VirtualLeaf       = 0x12, ///< leaf zone, no 3D extent
00077
00078                 eType_Invalid           = 0x00  // keep this last
00079         };
00080
00081         // virtual destructor --------------------------------------------------
00082         virtual ~Zone(void) throw();
00083
00084         // aesop::Zone class interface methods ----------------------------------
00085
00086         /// get the unique ID of this zone (unique within map)
00087         virtual const char * getId(void) const throw() = 0;
00088
00089         /// what type of Zone is this?
00090         virtual eType getType(void) const throw() = 0;
00091
00092         /// returns axis-aligned bounding box for this zone
00093         virtual void getBoundingRect(OUT rect3d_t& r) const = 0;
00094
00095         /// does this zone contain the specified point?
00096         virtual bool containsPoint(IN const point3d_t& p) const throw() = 0;
00097
00098         /// return leaf zone within zone that contains specified point, or null
00099         virtual LeafZone * getLeafZone(IN const point3d_t& p) throw() = 0;
00100
00101         /// return leaf zone within zone that contains specified point, or null
00102         virtual const LeafZone * getLeafZone(IN const point3d_t& p) const throw() = 0;
00103
00104         // allow getting and setting of user data (client data)
00105         virtual void * getUserPointer(void) const throw() = 0;
00106         virtual void setUserPointer(void *) throw() = 0;
00107 };
00108
00109
00110
00111 /// \ingroup aesop_map
00112 /*@{*/
00113
00114
00115 /// callback used for the LeafZone::iterateVisibleZones() method
00116 typedef void (*leafzone_iteration_fn)(
00117                                 IN LeafZone * lz,
00118                                 IN void * context);
00119
00120
00121 /// \ingroup aesop_map
00122 /*@{*/
00123
00124 ///     A leaf zone is a special kind of Zone.  It is a leaf of the hierarchical
00125 ///     zone tree (no children), hence the name.  Leaf zones are strictly
00126 ///     disjoint (do not intersect any other zones except their parents).
00127 ///
00128 ///     Most importantly, only leaf zones are allowed to contain anything
00129 ///     interesting.  Only leaf zones can contain type instances (see
00130 ///     \ref typeinst).  In practice, leaf zones contain static type
00131 ///     instances only.  Dynamic (moving) instances are handled separately,
00132 ///     although the hierarchical zone space partitioning helps manage this.
00133 ///
00134 ///     Leaf zones are required to be convex.  The fact that any two points in
00135 ///     a leaf zone can be connected by a straight line is a big help to AI
00136 ///     engines that need to figure out how to get from A to B (crossing zones
00137 ///     is a different problem).
00138 ///
00139 ///     Leaf zones must contain a list of all other leaf zones that are
00140 ///     potentially visible.  This is used for efficient rendering.  Do an
00141 ///     internet search for "potentially visible set" for more information.
00142 ///
00143 ///     <b>LeafZone objects (like Zone and Map) should never be aware of
00144 ///     drawing or rendering.</b>  Other code libraries can use these objects to
00145 ///     render.
00146 ///
00147 ///     <b>LeafZone objects do not know anything about types!</b>  That is, a
00148 /// leaf zone will contain rich instances, but it won't know anything about
00149 /// the underlying type.  In particular, if you load a map with zones containing
00150 /// instances, you'll have to load the types yourself if necessary.
00151 ///
00152 /// Virtual leaf zones are regular LeafZone objects, with one difference: they
00153 /// have no real extent.  They can contain objects, but only for the purposes
00154 /// of rendering.  Commonly, virtual leaves are used to contain terrain and
00155 /// skybox objects.  These are the sorts of objects that need to be rendered,
00156 /// but don't interact with the player in the usual way.  (Skyboxes can never
00157 /// be reached, for instance, and terrain is very large and typically spans
00158 /// multiple real LeafZone objects).  Using virtual leaf zones let you take
00159 /// advantage of the visible leaf zone list to control when objects are
00160 /// rendered, but not worry about 3D extents.
00161 class LeafZone : public Zone {
00162 public:
00163         // virtual destructor --------------------------------------------------
00164         virtual ~LeafZone(void) throw();
00165
00166         // aesop::LeafZone class interface methods ----------------------------
00167
00168         /// iterate over other leaf zones visible from here (includes self!)
00169         virtual void iterateVisibleZones(IN leafzone_iteration_fn callback,
00170                                 IN void * context) = 0;
00171
00172         /// is the remote leaf zone visible to this leaf zone?  Implementers:
00173         ///     remember that a leaf should be visible to itself!
00174         virtual bool isLeafVisible(IN LeafZone * lzRemote) throw() = 0;
00175
00176         /// iterate over all static type instances in zone and call callback
00177         ///   (see the \ref typeinst library for instance information)
00178         virtual void iterateStaticInstances(IN instance_iteration_fn callback,
00179                                 IN void * context) = 0;
00180 };
00181
00182
00183
00184 };      // aesop namespace
00185
00186
00187 #endif  // AESOP_INTERFACE_ZONE_H__
00188