Initial revision of animqueue

luprex/syscpp/planemap.hpp

@@ -1,40 +1,74 @@
+//////////////////////////////////////////////////////////////
 //
 // PLANEMAP
 //
-// Stores a map of the items that are on each plane.  Doesn't
-// store terrain, only items.
+// This module defines two classes: PlaneMap, and PlaneItem.  A
+// PlaneItem is an object that has a plane (a string) and an
+// XYZ position.  A PlaneMap keeps track of potentially thousands
+// of PlaneItem objects, allowing you to search for PlaneItems
+// by scanning a geographic region.
+//
+// CLASS SPRITE DERIVES FROM PLANEITEM
+//
+// A PlaneMap records the positions of PlaneItems.  The intent is
+// that class Sprite should derive from PlaneItem.  That way, the
+// PlaneMap can record the positions of sprites.
+//
+// When you put derived types like Sprite into a PlaneMap, the
+// PlaneMap will work fine.  However, when you scan the PlaneMap,
+// it will give return PlaneItem pointers, not Sprite pointers.
+//
+// If you're sure that the PlaneMap contains only sprites, then
+// you can use static_cast to convert those PlaneItem pointers to
+// Sprite pointers.  Sadly, there's no simple way to avoid the casting.
+//
+// THE SCANNABLE REGION IS FINITE
 //
 // A plane is a rectangle, with a finite size: if you stray more
-// than 80,000,000 meters from the origin, then you are beyond the
-// edge of the plane.
+// than 80,000,000 meters from the origin, then that PlaneItem
+// is beyond the scannable region.
 //
-// There's nothing stopping you from moving a PlaneItem farther
-// than that.  However, if you do move a PlaneItem farther than
-// that, then it won't show up in radius-scans.
+// There's nothing stopping you from moving a PlaneItem outside
+// the scannable region.  It is not an error to do so.
+// However, if you do move a PlaneItem outside the scannable
+// region, then that PlaneItem will not show up for scan_radius.
 //
-// The PlaneMap doesn't need you to "create" planes.  You just
-// set the plane of a PlaneItem to any string, and that plane will
-// pop into existence if it wasn't already there.
+// PLANES CANNOT BE DESTROYED BUT THEY CAN BE UNINHABITED
 //
-// If you use the empty string as a plane name, a special case is
+// You can't "create" or "destroy" planes.  Instead, we say
+// that a plane is "uninhabited" until you put a PlaneItem
+// there.  Initially, all possible planes exist, but they're
+// all uninhabited until you put a PlaneItem there.  Planes
+// that are uninhabited take no memory.
+//
+// THE NOWHERE PLANE
+//
+// If you use the literal "nowhere" as a plane name, a special case is
 // triggered: you're "nowhere."  Radius scans can never find items
-// whose plane is the empty string.
+// whose plane is "nowhere."  The same also applies when you use the
+// empty string as a plane name.
 //
-// INHERITANCE
+// THE Z COORDINATE IS IGNORED
 //
-// The intent is that class Sprite should derive from PlaneItem.
-// When you put sprites into a PlaneMap, it will work fine.  However,
-// when you scan the PlaneMap, it will give you PlaneItem pointers,
-// not Sprite pointers.  If you're sure that the PlaneMap contains
-// only sprites, then you can use static_cast to convert those
-// PlaneItem pointers to Sprite pointers.  Sadly, there's no simple
-// way to avoid the casting.
+// Class PlaneItem stores X, Y, and Z.  The Z coordinate is
+// ignored for all plane-scanning operations.  In other words,
+// planes are 2D.  The only reason we store a Z coordinate
+// is for the consistency of storing the model's X, Y, and Z
+// all in the same place.
 //
 // MEMORY MANAGEMENT
 //
-// The PlaneMap does not own the PlaneItems.  You need to create,
-// destroy, and manage the PlaneItems yourself.
+// PlaneMaps do not own PlaneItems.  This is a deliberate choice.
+// We assume that sprites will be owned by the sprite ID table.
+// So therefore, the PlaneMaps shouldn't own the sprites.
 //
+// So instead, we use this rule: a PlaneMap has a function 'track'
+// that causes it to start tracking the location of a PlaneItem.
+// However, the PlaneMap still doesn't own the PlaneItem.
+// If you destroy a PlaneMap, all the PlaneItems
+// will automatically be untracked, but they won't be deleted.
+//
+//////////////////////////////////////////////////////////////
 
 #ifndef PLANEMAP_HPP
 #define PLANEMAP_HPP
@@ -47,10 +81,12 @@ class PlaneMap;
 
 class PlaneItem {
     friend class PlaneMap;
+
 private:
-    PlaneMap *grid_;
+    PlaneMap *pmap_;
     std::string plane_;
     double x_, y_, z_;
+
 public:
     PlaneItem();
     ~PlaneItem();
@@ -60,32 +96,35 @@ public:
     const double y() const { return y_; }
     const double z() const { return z_; }
 
-    void use_map(PlaneMap *map);
+    void untrack();
     void set_pos(const std::string &plane, double x, double y, double z);
+    void set_xyz(double x, double y, double z) { set_pos(plane_, x, y, z); }
 };
 
 class PlaneMap {
     friend class PlaneItem;
-    friend int cunittests_planemap(lua_State *L);
-public:
-    using Elt = PlaneItem *;
-    using EltVec = std::vector<Elt>;
 private:
+    using EltVec = std::vector<PlaneItem *>;
     using Plane = std::map<int64_t, EltVec>;
     std::map<std::string, Plane> planes_;
     void remove(const std::string &plane, int64_t cell, PlaneItem *client);
     void insert(const std::string &plane, int64_t cell, PlaneItem *client);
-private:
-    // These functions are only used in unit tests.
-    EltVec get_cell(const std::string &plane, int64_t cell) const;
-    int total_cells() const;
-    void clear() { planes_.clear(); }
+
 public:
     PlaneMap();
     ~PlaneMap();
+    void track(PlaneItem *item);
     EltVec scan_radius(const std::string &plane, double x, double y, double radius) const;
+    
+private:
+    // unit testing stuff.
+    friend int cunittests_planemap(lua_State *L);
+    EltVec get_cell(const std::string &plane, int64_t cell) const;
+    int total_cells() const;
+    void clear() { planes_.clear(); }
 };
 
+
 #endif // PLANEMAP_HPP