sceneZoneSpace.h
Engine/source/scene/zones/sceneZoneSpace.h
Classes:
class
Abstract base class for an object that manages zones in a scene.
class
Link to another zone space.
Detailed Description
1 2//----------------------------------------------------------------------------- 3// Copyright (c) 2012 GarageGames, LLC 4// 5// Permission is hereby granted, free of charge, to any person obtaining a copy 6// of this software and associated documentation files (the "Software"), to 7// deal in the Software without restriction, including without limitation the 8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 9// sell copies of the Software, and to permit persons to whom the Software is 10// furnished to do so, subject to the following conditions: 11// 12// The above copyright notice and this permission notice shall be included in 13// all copies or substantial portions of the Software. 14// 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 21// IN THE SOFTWARE. 22//----------------------------------------------------------------------------- 23 24#ifndef _SCENEZONESPACE_H_ 25#define _SCENEZONESPACE_H_ 26 27#ifndef _SCENESPACE_H_ 28#include "scene/sceneSpace.h" 29#endif 30 31#ifndef _TVECTOR_H_ 32#include "core/util/tVector.h" 33#endif 34 35 36class SceneZoneSpaceManager; 37class SceneCullingState; 38 39 40/// Abstract base class for an object that manages zones in a scene. 41/// 42/// This class adds the ability to SceneSpace to define and manage zones within the object's 43/// space. Zones are used to determine visibility in a scene. 44/// 45/// Each zone space manages one or more zones in a scene. All the zones must be within the 46/// AABB of the zone space but within that AABB, the zone space is free to distribute and 47/// manage zones in arbitrary fashion. 48/// 49/// For scene traversal, zone spaces are interconnected. By default, zone spaces get a chance 50/// to connect to each other when being moved into each other's zones. An exception to this 51/// is the root zone since it is both immobile and without position and (limited) extents. If 52/// a zone space wants to connect to the root zone, it must do so manually (same goes for 53/// disconnecting). 54class SceneZoneSpace : public SceneSpace 55{ 56 public: 57 58 typedef SceneSpace Parent; 59 60 friend class SceneZoneSpaceManager; 61 friend class SceneRootZone; // mZoneFlags, connectZoneSpace, disconnectZoneSpace 62 63 enum 64 { 65 InvalidZoneGroup = 0 66 }; 67 68 enum ZoneFlags 69 { 70 /// Whether this zoning space is "closed off" or not. When connections between 71 /// zoning spaces are established, by default only spaces that are closed off are 72 /// connected to those that are *not* and vice versa. This defines a natural progression 73 /// where spaces that explicitly want to propagate traversals are connected to those 74 /// that want to contain it. 75 /// 76 /// This flag is set by default. 77 ZoneFlag_IsClosedOffSpace = BIT( 0 ), 78 }; 79 80 protected: 81 82 enum 83 { 84 ZoneGroupMask = Parent::NextFreeMask << 0, 85 NextFreeMask = Parent::NextFreeMask << 1 86 }; 87 88 /// The manager to which this zone space is registered. 89 SceneZoneSpaceManager* mManager; 90 91 /// ID of first zone defined by object. 92 U32 mZoneRangeStart; 93 94 /// Number of zones managed by #obj. IDs are consecutive 95 /// starting with #mZoneRangeStart. 96 U32 mNumZones; 97 98 /// Group which the zone is assigned to. Zone spaces that would normally not connect 99 /// do connect if they are assigned the same zone group. O to disable (default). 100 U32 mZoneGroup; 101 102 /// 103 BitSet32 mZoneFlags; 104 105 /// @name Occluders 106 /// 107 /// Zone spaces keep track of the occluders that get added to them so that during 108 /// traversal, they can be taken on board as early as possible. This allows traversals 109 /// themselves to take occlusion into account. 110 /// 111 /// @{ 112 113 /// Occluders in this space. Every object that is assigned to this space 114 /// and has the OccluderObjectType flag set, is added to this list. 115 Vector< SceneObject*> mOccluders; 116 117 /// Add the given object to the list of occluders in this zone space. 118 void _addOccluder( SceneObject* object ); 119 120 /// Remove the given object from the list of occluders in this zone space. 121 void _removeOccluder( SceneObject* object ); 122 123 /// Register the occluders in this zone with the given culling state. 124 void _addOccludersToCullingState( SceneCullingState* state ) const; 125 126 /// @} 127 128 /// @name Zone Space Connectivity 129 /// @{ 130 131 //TODO: we should have both automatic and manual connections; only automatic connections 132 // should get reset when a zone space moves 133 134 /// Link to another zone space. 135 struct ZoneSpaceRef 136 { 137 // We could be storing zone IDs here to connect individual zones rather than just 138 // the managers but since no one requires this at the moment, the code doesn't do it. 139 // However, it's trivial to add. 140 141 SceneZoneSpace* mZoneSpace; 142 ZoneSpaceRef* mNext; 143 }; 144 145 /// List of zone spaces that this space is connected to. This is used 146 /// for traversals. 147 ZoneSpaceRef* mConnectedZoneSpaces; 148 149 /// Allocator for ZoneSpaceRefs. 150 static ClassChunker< ZoneSpaceRef> smZoneSpaceRefChunker; 151 152 /// Disconnect all zone spaces currently connected to this space. 153 virtual void _disconnectAllZoneSpaces(); 154 155 /// Hand the traversal over to connected zone spaces. 156 virtual void _traverseConnectedZoneSpaces( SceneTraversalState* state ); 157 158 /// Return true if the given zone space, which has crossed into this space, should 159 /// be automatically connected. Note that event 160 virtual bool _automaticallyConnectZoneSpace( SceneZoneSpace* zoneSpace ) const; 161 162 /// @} 163 164 /// @name SceneManager Notifications 165 /// 166 /// These methods are called when SceneManager assigns or removes objects to/from our zones. 167 /// 168 /// @{ 169 170 /// Called by the SceneManager when an object is added to one or more zones that 171 /// are managed by this object. 172 virtual void _onZoneAddObject( SceneObject* object, const U32* zoneIDs, U32 numZones ); 173 174 /// Called by the SceneManager when an object that was previously added to one or more 175 /// zones managed by this object is now removed. 176 virtual void _onZoneRemoveObject( SceneObject* object ); 177 178 /// @} 179 180 // SceneObject. 181 virtual void onSceneRemove(); 182 183 public: 184 185 SceneZoneSpace(); 186 virtual ~SceneZoneSpace(); 187 188 /// Return true if this is the outdoor zone. 189 bool isRootZone() const { return ( getZoneRangeStart() == 0 ); } 190 191 /// Gets the index of the first zone this object manages in the collection of zones or 0xFFFFFFFF if the 192 /// object is not managing zones. 193 U32 getZoneRangeStart() const { return mZoneRangeStart; } 194 195 /// Return the number of zones that are managed by this object. 196 U32 getZoneRange() const { return mNumZones; } 197 198 /// Return the zone group that this zone space belongs to. 0 by default which means the 199 /// zone space is not allocated to a specific zone group. 200 U32 getZoneGroup() const { return mZoneGroup; } 201 202 /// Set the zone group of this zone space. Zone spaces in the same group will connect even if 203 /// not connecting by default. Set to 0 to deactivate. 204 void setZoneGroup( U32 group ); 205 206 /// Dump a listing of all objects assigned to this zone space to the console as well 207 /// as a list of all connected spaces. 208 /// 209 /// @param update Whether to update the zone contents before dumping. Since the zoning states of 210 /// SceneObjects are updated lazily, the contents of a zone can be outdated. 211 void dumpZoneState( bool update = true ); 212 213 /// Get the ambient light color of the given zone in this space or return false if the 214 /// given zone does not have an ambient light color assigned to it. 215 virtual bool getZoneAmbientLightColor( U32 zone, LinearColorF& outColor ) const { return false; } 216 217 /// @name Containment Tests 218 /// @{ 219 220 /// 221 virtual bool getOverlappingZones( const Box3F& aabb, U32* zones, U32& numZones ) = 0; 222 223 /// Find the zones in this object that @a obj is part of. 224 /// 225 /// @param obj Object in question. 226 /// @param outZones Indices of zones containing the object. Must have at least as many entries 227 /// as there as zones in this object or SceneObject::MaxObjectZones, whichever is smaller. 228 /// Note that implementations should never write more than SceneObject::MaxObjectZones entries. 229 /// @param outNumZones Number of elements in the returned array. 230 /// 231 /// @return Return true if the world box of @a obj is fully contained within the zones of this object or 232 /// false if it is at least partially outside of them. 233 virtual bool getOverlappingZones( SceneObject* obj, U32* outZones, U32& outNumZones ); 234 235 /// Returns the ID of the zone that are managed by this object that contains @a p. 236 /// @param p Point to test. 237 /// @return ID of the zone containing @a p or InvalidZoneId if none of the zones defined by this 238 /// object contain the point. 239 virtual U32 getPointZone( const Point3F& p ) = 0; 240 241 /// @} 242 243 /// @name Connectivity 244 /// @{ 245 246 /// Connect this zone space to the given zone space. 247 /// 248 /// @param zoneSpace A zone space. 249 /// 250 /// @note Connectivity is reset when a zone space is moved! 251 virtual void connectZoneSpace( SceneZoneSpace* zoneSpace ); 252 253 /// If the object is a zone space, then this method is called to instruct the object 254 /// to remove any zone connectivity to @a zoneSpace. 255 /// 256 /// @param zoneSpace A zone space which had previously been passed to connectZoneSpace(). 257 virtual void disconnectZoneSpace( SceneZoneSpace* zoneSpace ); 258 259 /// @} 260 261 /// @name Traversals 262 /// @{ 263 264 /// Traverse into the zones of this space. Set the render states of those zones and add the frustums 265 /// that lead into them. 266 /// 267 /// The traversal stack is expected to not be empty and the topmost entry on the stack should be the 268 /// zone of another manager from which traversal is handed over to this manager. 269 /// 270 /// @param state Scene traversal state. 271 /// 272 /// @note If the zone's of a zone space are reached via different traversal paths, this method 273 /// will be called multiple times on the same space. 274 virtual void traverseZones( SceneTraversalState* state ) = 0; 275 276 /// Traverse the zones in this space starting with the given zone. Where appropriate, traversal 277 /// should be handed off to connected spaces. 278 /// 279 /// @param state State which should be updated by the traversal. 280 /// @param startZoneId ID of zone in this manager in which to start traversal. 281 virtual void traverseZones( SceneTraversalState* state, U32 startZoneId ) = 0; 282 283 /// @} 284 285 // SimObject. 286 virtual bool writeField( StringTableEntry fieldName, const char* value ); 287 288 static void initPersistFields(); 289 290 // NetObject. 291 virtual U32 packUpdate( NetConnection* connection, U32 mask, BitStream* stream ); 292 virtual void unpackUpdate( NetConnection* connection, BitStream* stream ); 293 294 private: 295 296 static bool _setZoneGroup( void* object, const char* index, const char* data ); 297}; 298 299#endif // !_SCENEZONESPACE_H_ 300