Emergency 2017 Dokumentation  v3.0.1
qsf::Map Class Reference

Map class. More...

#include <Map.h>

Classes

class  EntityHashMapWrapper
 
struct  SerializationOptions
 

Public Types

typedef void(* CreateEntityIdMapCallback) (const std::vector< const Prototype * > &, UniqueIdMap &)
 
- Public Types inherited from qsf::BasePrototypeManager
typedef std::unordered_map< uint64, uint64UniqueIdMap
 Maps unique IDs, e.g. of prototypes in one prefab or object to another. More...
 

Public Member Functions

bool isRunning () const
 Return whether or not the map is currently up-and-running. More...
 
bool isSimulating () const
 Return whether or not the map is currently in simulating mode. More...
 
void setSimulatingMode (bool simulatingMode)
 Set the map and all running components inside to simulating mode. More...
 
bool isInServerMode () const
 Return whether or not the map is currently in server mode. More...
 
void setServerMode (bool serverMode)
 Set the map and all running components inside to server mode. More...
 
void clear ()
 Clear the map. More...
 
void performGarbageCollection ()
 Perform garbage collection. More...
 
bool loadByGlobalAssetId (GlobalAssetId globalAssetId, const SerializationOptions &serializationOptions)
 Load a map by using a global asset ID. More...
 
bool loadByFilename (const std::string &filename, const SerializationOptions &serializationOptions, GlobalAssetId globalAssetId)
 Load a map by using a given filename. More...
 
bool saveByFilename (const std::string &filename, const SerializationOptions &serializationOptions)
 Save the map by using a given filename. More...
 
GlobalAssetId getGlobalAssetId () const
 Return the global asset ID of the map. More...
 
void setGlobalAssetId (GlobalAssetId globalAssetId)
 Set the global asset ID of the map (gets overridden on every load and save so this is only useful in those cases where the map is directly deserialized from a buffer) More...
 
const std::string & getVersionString () const
 Return the version string of the map. More...
 
void setVersionString (const std::string &versionString)
 Set the version string of the map. More...
 
void setBuildDependentVersionString (const std::string &versionString)
 Set the version string of the map. More...
 
bool createMapBackup (MapBackup &mapBackup, const SerializationOptions &serializationOptions) const
 Serialize the map to a backup. More...
 
bool restoreMapBackup (const MapBackup &mapBackup, const SerializationOptions &serializationOptions)
 Deserialize the map from a backup. More...
 
void serialize (BinarySerializer &serializer)
 Serialize or deserialize the map using a binary serializer. More...
 
LayerManagergetLayerManager () const
 Return the layer manager. More...
 
GroundMapManagergetGroundMapManager () const
 Return the ground map manager. More...
 
DebugDrawManagergetDebugDrawManager () const
 Return the debug draw manager instance. More...
 
EntitygetCoreEntity ()
 Return the core entity. More...
 
const EntitygetCoreEntity () const
 
void reserveEntities (size_t numberOfEntities)
 Reserve entities. More...
 
EntitycreateEntity ()
 Create a new entity instance. More...
 
EntitycreateEntityById (uint64 id)
 Create a new entity instance with an enforced given unique entity identifier. More...
 
EntitycreateEntityByPrototypeReference (const Prototype &prototype)
 Create a new entity instance by cloning a prototype given by reference. More...
 
EntitycreateObjectByLocalPrefabAssetId (const StringHash &stringHash, CreateEntityIdMapCallback createEntityIdMapCallback=nullptr)
 Create a new entity instance by cloning a prototype given by ID generated by using the local prefab asset name. More...
 
bool destroyEntityById (uint64 id)
 Destroy an entity instance by using its unique identifier. More...
 
bool destroyObjectById (uint64 id)
 Destroy an object instance by using its unique identifier. More...
 
void destroyAllEntities ()
 Destroy all entities within this map. More...
 
EntitygetEntityById (uint64 id) const
 Return an entity instance by using its unique identifier. More...
 
const EntityHashMapWrappergetEntities () const
 Return the entity list. More...
 
void getEntitiesByIdArray (const std::vector< uint64 > &entityIds, std::vector< Entity * > &outEntities) const
 Get an array of entity instance pointers from an array of entity IDs. More...
 
template<typename T >
void getEntitiesByIds (const T &entityIds, std::vector< Entity * > &outEntities, bool filterNullPointers=false) const
 Get an array of entity instance pointers from a Vector/list/set (or other iteratable container) of entity IDs. More...
 
Ogre::SceneManager * getOgreSceneManager () const
 Return the encapsulated OGRE scene manager instance. More...
 
virtual bool containsEntities () const override
 
- Public Member Functions inherited from qsf::BasePrototypeManager
uint32 getId () const
 Return the unique prototype manager identifier. More...
 
ComponentManagergetComponentManager () const
 Return the component manager. More...
 
PrototypegetPrototypeById (uint64 id) const
 Return a prototype instance by using its local asset ID. More...
 
const PrototypeHashMapgetPrototypes () const
 Return the prototype list. More...
 
uint64 generatePrototypeId ()
 Generate a new unused prototype ID. More...
 
void applyIdMatchingMap (const Prototype &toPrototype, const UniqueIdMap &uniqueIdMap)
 Apply prototype ID matching map. More...
 
void buildIdMatchingMapWithGeneratedIds (const Prototype &fromPrototype, UniqueIdMap &outUniqueIdMap, std::vector< const Prototype * > *outFromPrototypes=nullptr, bool followAllLinks=false)
 Build prototype ID matching map with newly generated unique IDs as targets. More...
 
void buildIdMatchingMapWithUntranslatedIds (const Prototype &fromPrototype, UniqueIdMap &outUniqueIdMap, std::vector< const Prototype * > *outFromPrototypes=nullptr, bool followAllLinks=false)
 Build prototype ID matching map of all child prototype IDs to themselves. More...
 
virtual bool destroyPrototypeById (uint64 id)
 Destroy a prototype instance by using its ID. More...
 
virtual bool changePrototypeId (uint64 oldId, uint64 newId)
 Change a prototype's ID. More...
 

Public Attributes

boost::signals2::signal< void(const CameraComponent &)> PreCompositorWorkspaceUpdate
 This Boost signal is emitted before a compositor workspace gets updated; parameter: used camera component which is inside this map. More...
 
boost::signals2::signal< void()> PreMapSave
 This Boost signal is emitted before a map is going to be saved, don't do work before the map is saved until you really have to (in case of a crash the artist will lose the work while saving, total fail) More...
 
boost::signals2::signal< void()> PostMapSave
 This Boost signal is emitted after the map has been be saved. More...
 
boost::signals2::signal< void(uint64)> ObjectDestroyed
 This Boost signal is emitted when an object gets destroyed (via destroyObjectById) More...
 

Protected Member Functions

virtual PrototypecreatePrototypeInstance (uint64 id) override
 
virtual uint64 generatePrototypeIdInternal () override
 
- Protected Member Functions inherited from qsf::BasePrototypeManager
 BasePrototypeManager (uint32 id)
 Constructor. More...
 
virtual ~BasePrototypeManager ()
 Destructor. More...
 
void reservePrototypes (size_t numberOfPrototypes)
 Reserve prototypes. More...
 
PrototypecreatePrototype ()
 Create a new and empty prototype instance. More...
 
PrototypecreatePrototypeById (uint64 id)
 Create a new and empty prototype instance. More...
 
PrototypeunregisterPrototypeById (uint64 id)
 Unregister a prototype from this manager. More...
 
void unregisterAllPrototypes ()
 Unregister all prototypes, i.e. clear internal management. More...
 
void pushLastPrototypeToFront ()
 
- Protected Member Functions inherited from qsf::Manager
 Manager ()
 Default constructor. More...
 
virtual ~Manager ()
 Destructor. More...
 

Friends

class Layer
 
class Prototype
 
class MapSystem
 

Additional Inherited Members

- Static Public Member Functions inherited from qsf::BasePrototypeManager
static void fillIdMatchingMap (const Prototype &fromPrototype, const Prototype &toPrototype, UniqueIdMap &outUniqueIdMap)
 Fill prototype ID matching map. More...
 

Detailed Description

Map class.

Remarks
Usually, you create entity instances by using a prototype
// "QSF_MAINMAP" stands for "qsf::Qsf::instance()->getMapSystem().getMainMap()"
qsf::Entity* qsfEntity = QSF_MAINMAP.createObjectByLocalPrefabAssetId("sample/prefab/vehicle/ambulance");
// ... entity null pointer check would be a good idea ...
uint64 myPersonId = qsfEntity->getId(); // "qsf::getUninitialized<uint64>()" if invalid entity ID

The following example shows how to get the instance of a certain entity:

// uint64 myPersonId ...
qsf::Entity* qsfEntity = QSF_MAINMAP.getEntityById(myPersonId);
Note
  • In QSF terminology we're talking about "maps", not "scenes" or "worlds" (don't mix up a QSF map with "std::map")
  • On the QSF abstraction level, a map is not scene graph based, it's just a list of entities
  • An entity is a concrete prototype instance
  • Everything within a map is an entity
  • "Objects" are formed by linking entities together, prefab instances generate objects (linked entities)
  • A map system is a collection of maps
  • By concept there can be only one current map instance at one and the same time
  • The order of the entity instances inside the map does not matter
  • The map is responsible for the creation and destruction of entity instance, no one else
  • For performance and simplicity reasons, during runtime entities should only be addressed by using the unique entity identifiers
  • Depends on the renderer system ("qsf::RendererSystem")
  • Depends on the prototype system ("qsf::PrototypeSystem")
Todo:

Definition at line 93 of file Map.h.

Member Typedef Documentation

typedef void(* qsf::Map::CreateEntityIdMapCallback) (const std::vector< const Prototype * > &, UniqueIdMap &)

Definition at line 109 of file Map.h.

Member Function Documentation

void qsf::Map::clear ( )

Clear the map.

Note
  • Resets the map filename
  • Destroys all entities within this map
  • Destroys all layers within this map, except root and base layer
virtual bool qsf::Map::containsEntities ( ) const
inlineoverridevirtual

Reimplemented from qsf::BasePrototypeManager.

Definition at line 657 of file Map.h.

Entity* qsf::Map::createEntity ( )

Create a new entity instance.

Returns
The created entity instance, null pointer on error, do no destroy the returned instance and do need keep a reference to it outside the C runtime stack (use the unique entity ID instead)
Note
  • Use "createObjectByLocalPrefabAssetId()" instead of "createEntity()" whenever possible
Entity* qsf::Map::createEntityById ( uint64  id)

Create a new entity instance with an enforced given unique entity identifier.

Parameters
[in]idThe unique (inside the map the entity is in) entity identifier
Returns
The created entity instance, null pointer on error (e.g. ID already used), do no destroy the returned instance and do need keep a reference to it outside the C runtime stack (use the unique entity ID instead)
Note
  • Use "createObjectByLocalPrefabAssetId()" instead of "createEntityById()" whenever possible
  • Use "createEntity()" instead of "createEntityById()" whenever possible, do not enforce unique entity identifier if you can avoid it
Entity* qsf::Map::createEntityByPrototypeReference ( const Prototype prototype)

Create a new entity instance by cloning a prototype given by reference.

Parameters
[in]prototypePrototype instance to use
Returns
The created entity instance, null pointer on error, do no destroy the returned instance and do need keep a reference to it outside the C runtime stack (use the unique entity ID instead)
Todo:
  • TODO(co) Provide such methods or just enforce ID only. Might make it more complicated in case one already has the concrete reference.
bool qsf::Map::createMapBackup ( MapBackup mapBackup,
const SerializationOptions serializationOptions 
) const

Serialize the map to a backup.

Parameters
[in]mapBackupMap backup to save the map to
[in]serializationOptionsConfiguration for the serialization
Returns
"true" if all went fine, else "false"
Entity* qsf::Map::createObjectByLocalPrefabAssetId ( const StringHash stringHash,
CreateEntityIdMapCallback  createEntityIdMapCallback = nullptr 
)

Create a new entity instance by cloning a prototype given by ID generated by using the local prefab asset name.

Parameters
[in]stringHashThe local prefab asset name of the prototype to use, generated by "qsf::StringHash" (example: "sample/prefab/vehicle/ambulance")
[in]createEntityIdMapCallbackOptional callback which fills the map of prototype IDs to IDs of the created entities
Returns
The created entity instance, null pointer on error, do no destroy the returned instance and do need keep a reference to it outside the C runtime stack (use the unique entity ID instead)
virtual Prototype* qsf::Map::createPrototypeInstance ( uint64  id)
overrideprotectedvirtual
void qsf::Map::destroyAllEntities ( )

Destroy all entities within this map.

Note
  • Performs garbage collection at once after destroying all entities by calling "qsf::Map::performGarbageCollection()"
bool qsf::Map::destroyEntityById ( uint64  id)

Destroy an entity instance by using its unique identifier.

Parameters
[in]idThe unique (inside the map the entity is in) entity identifier
Returns
"true" if all went fine, else "false" (unknown entity identifier?)
bool qsf::Map::destroyObjectById ( uint64  id)

Destroy an object instance by using its unique identifier.

Parameters
[in]idThe unique (inside the map the entity is in) entity identifier
Returns
"true" if all went fine, else "false" (unknown entity identifier?)
virtual uint64 qsf::Map::generatePrototypeIdInternal ( )
overrideprotectedvirtual
Entity& qsf::Map::getCoreEntity ( )

Return the core entity.

Returns
Reference to the core entity, do not destroy the instance
Remarks
In order to be as flexible and reusable as possible, QSF is extensively using the entity/component architecture. As a result certain features, which other projects would hardcode into a framework/engine, are realized as entity components in QSF. This way new core features can be plugged into a map or be exchanged without rewriting QSF. Here are some examples for such core components which usually only have a single instance per map:
  • Map properties component
  • Sky component
  • Water plane component
  • Time of day component
  • Weather component

Beside the flexibility, other advantages of this approach are support for edit/undo/redo/cooperative work inside the QSF editor or automatic serialization just to mention a few. This support comes without the need to explicitly implement it for the core components listed above (or any other components, of course).

This "qsf::Map::getCoreEntity()"-method exists to have a common central entity for the core components and to provide comfortable access to it.

Note
  • It's guaranteed that there's a core entity, even if it means that it has to be created during the method call
const Entity& qsf::Map::getCoreEntity ( ) const
DebugDrawManager & qsf::Map::getDebugDrawManager ( ) const
inline

Return the debug draw manager instance.

Returns
The debug draw manager instance, don't destroy the returned instance

Definition at line 79 of file Map-inl.h.

const Map::EntityHashMapWrapper & qsf::Map::getEntities ( ) const
inline

Return the entity list.

Returns
Reference to the internal entity list, do not manipulate the list or destroy the entities

Definition at line 97 of file Map-inl.h.

void qsf::Map::getEntitiesByIdArray ( const std::vector< uint64 > &  entityIds,
std::vector< Entity * > &  outEntities 
) const

Get an array of entity instance pointers from an array of entity IDs.

Parameters
[in]entityIdsArray of entity IDs
[out]outEntitiesArray of entity instances, may contain null pointers; the array is automatically cleared
template<typename T >
void qsf::Map::getEntitiesByIds ( const T &  entityIds,
std::vector< Entity * > &  outEntities,
bool  filterNullPointers = false 
) const

Get an array of entity instance pointers from a Vector/list/set (or other iteratable container) of entity IDs.

Parameters
[in]entityIdsEntity IDs
[out]outEntitiesArray of entity instances; the array is automatically cleared
[in]filterNullPointersIf "true", all invalid entity IDs are ignored; if "false", the output will contains null pointers for those

Definition at line 103 of file Map-inl.h.

Entity * qsf::Map::getEntityById ( uint64  id) const
inline

Return an entity instance by using its unique identifier.

Parameters
[in]idThe unique (inside the map the entity is in) entity identifier
Returns
The requested entity instance, null pointer on error (maybe the ID is unknown?), do not destroy the instance

Definition at line 91 of file Map-inl.h.

GlobalAssetId qsf::Map::getGlobalAssetId ( ) const
inline

Return the global asset ID of the map.

Returns
The global asset ID of the map

Definition at line 35 of file Map-inl.h.

GroundMapManager & qsf::Map::getGroundMapManager ( ) const
inline

Return the ground map manager.

Returns
The ground map manager, do no destroy the returned instance

Definition at line 72 of file Map-inl.h.

LayerManager & qsf::Map::getLayerManager ( ) const
inline

Return the layer manager.

Returns
The layer manager, do no destroy the returned instance

Definition at line 65 of file Map-inl.h.

Ogre::SceneManager * qsf::Map::getOgreSceneManager ( ) const
inline

Return the encapsulated OGRE scene manager instance.

Returns
The encapsulated OGRE scene manager instance, can be a null pointer, do no destroy the returned instance
Note
  • Don't access the encapsulated OGRE scene manager instance if you don't have to

Definition at line 125 of file Map-inl.h.

const std::string & qsf::Map::getVersionString ( ) const
inline

Return the version string of the map.

Returns
The version string of the map

Definition at line 45 of file Map-inl.h.

bool qsf::Map::isInServerMode ( ) const
inline

Return whether or not the map is currently in server mode.

Returns
"true" if the map is currently in server mode, else "false"
Remarks
If the application is running in server mode, each map has this flag set.

Definition at line 30 of file Map-inl.h.

bool qsf::Map::isRunning ( ) const
inline

Return whether or not the map is currently up-and-running.

Returns
"true" if the map is currently up-and-running (meaning "qsf::Map::startup()" was called successfully), else "false"
Remarks
Maps which are currently up-and-running have e.g. audio visual representation as well as at least basic logic needed for the editor client. Not running maps are basically data storage.

Definition at line 20 of file Map-inl.h.

bool qsf::Map::isSimulating ( ) const
inline

Return whether or not the map is currently in simulating mode.

Returns
"true" if the map is currently in simulating mode, else "false"
Remarks
Maps which are currently in simulating mode have e.g. active AI and game logic. If a map is in simulating mode, this implies it is also up-and-running, see "isRunning()".

Definition at line 25 of file Map-inl.h.

bool qsf::Map::loadByFilename ( const std::string &  filename,
const SerializationOptions serializationOptions,
GlobalAssetId  globalAssetId 
)

Load a map by using a given filename.

Parameters
[in]filenameUTF-8 filename in platform-independent notation of the map to load
[in]serializationOptionsConfiguration for the serialization
[in]globalAssetIdGlobal asset ID of the map to load (only stored internally, not really used for loading)
Returns
"true" if all went fine, else "false" (file not found?)
Note
  • The current map will get lost (same effect as "qsf::Map::clear()"), so, you might want to save a manipulated map before loading a new one
  • On success, automatically makes the given filename to the internally stored map filename
Todo:
  • TODO(co) For now, we only support JSON, BIN and "OgreMax Scene Exporter" (www.ogremax.com) XML scene support
  • TODO(co) depreciated, don't use this method anymore, use "loadByGlobalAssetId()" instead
bool qsf::Map::loadByGlobalAssetId ( GlobalAssetId  globalAssetId,
const SerializationOptions serializationOptions 
)

Load a map by using a global asset ID.

Parameters
[in]globalAssetIdGlobal asset ID of the map to load
[in]serializationOptionsConfiguration for the serialization
Returns
"true" if all went fine, else "false" (asset not found?)
Note
  • The current map will get lost (same effect as "qsf::Map::clear()"), so, you might want to save a manipulated map before loading a new one
  • On success, automatically makes the given global asset ID to the internally stored map global asset ID
Todo:
  • TODO(co) For now, we only support JSON, BIN and "OgreMax Scene Exporter" (www.ogremax.com) XML scene support
void qsf::Map::performGarbageCollection ( )

Perform garbage collection.

Remarks
In order to avoid destruction related issues, entities and entity components are not destroyed immediately. Instead, they are removed from the "alife" data structures and are added to a "destroyed" list. Call this garbage collection method after important actions or for example once per frame.
void qsf::Map::reserveEntities ( size_t  numberOfEntities)
inline

Reserve entities.

Parameters
[in]numberOfEntitiesNumber of entities to reserve
Note
  • You might want to reserve entities before starting an insertion of entity masses (performance)

Definition at line 86 of file Map-inl.h.

bool qsf::Map::restoreMapBackup ( const MapBackup mapBackup,
const SerializationOptions serializationOptions 
)

Deserialize the map from a backup.

Parameters
[in]mapBackupMap backup tree to load the map from
[in]serializationOptionsConfiguration for the serialization
Returns
"true" if all went fine, else "false"
bool qsf::Map::saveByFilename ( const std::string &  filename,
const SerializationOptions serializationOptions 
)

Save the map by using a given filename.

Parameters
[in]filenameUTF-8 filename in platform-independent notation of the map to save
[in]serializationOptionsConfiguration for the serialization
Returns
"true" if all went fine, else "false"
Todo:
  • TODO(co) For now, we only support JSON and BIN
void qsf::Map::serialize ( BinarySerializer serializer)

Serialize or deserialize the map using a binary serializer.

Parameters
[in]serializerThe serializer, which can be either in read or write mode
void qsf::Map::setBuildDependentVersionString ( const std::string &  versionString)
inline

Set the version string of the map.

Parameters
[in]versionStringThe version string of the map
Note
  • Adds "retail_" if not enduser build

Definition at line 55 of file Map-inl.h.

void qsf::Map::setGlobalAssetId ( GlobalAssetId  globalAssetId)
inline

Set the global asset ID of the map (gets overridden on every load and save so this is only useful in those cases where the map is directly deserialized from a buffer)

Parameters
[in]globalAssetIdThe global asset ID of the map

Definition at line 40 of file Map-inl.h.

void qsf::Map::setServerMode ( bool  serverMode)

Set the map and all running components inside to server mode.

Remarks
If the application is running in server mode, each map has this flag set.
void qsf::Map::setSimulatingMode ( bool  simulatingMode)

Set the map and all running components inside to simulating mode.

Remarks
Maps which are currently in simulating mode have e.g. active AI and game logic. If a map is in simulating mode, this implies it is also up-and-running, see "isRunning()".
void qsf::Map::setVersionString ( const std::string &  versionString)
inline

Set the version string of the map.

Parameters
[in]versionStringThe version string of the map

Definition at line 50 of file Map-inl.h.

Friends And Related Function Documentation

friend class Layer
friend

Definition at line 100 of file Map.h.

friend class MapSystem
friend

Definition at line 102 of file Map.h.

friend class Prototype
friend

Definition at line 101 of file Map.h.

Member Data Documentation

boost::signals2::signal<void (uint64)> qsf::Map::ObjectDestroyed

This Boost signal is emitted when an object gets destroyed (via destroyObjectById)

Definition at line 171 of file Map.h.

boost::signals2::signal<void ()> qsf::Map::PostMapSave

This Boost signal is emitted after the map has been be saved.

Definition at line 168 of file Map.h.

boost::signals2::signal<void (const CameraComponent&)> qsf::Map::PreCompositorWorkspaceUpdate

This Boost signal is emitted before a compositor workspace gets updated; parameter: used camera component which is inside this map.

Definition at line 166 of file Map.h.

boost::signals2::signal<void ()> qsf::Map::PreMapSave

This Boost signal is emitted before a map is going to be saved, don't do work before the map is saved until you really have to (in case of a crash the artist will lose the work while saving, total fail)

Definition at line 167 of file Map.h.


The documentation for this class was generated from the following files: