diff --git a/algorithm_8hpp_source.html b/algorithm_8hpp_source.html index a5e59259a..7f7d52b53 100644 --- a/algorithm_8hpp_source.html +++ b/algorithm_8hpp_source.html @@ -22,7 +22,7 @@
| ▼Nentt | EnTT default namespace |
| CActor | Dedicated to those who aren't confident with entity-component systems |
| Cbreak_t | Break type used to disambiguate overloads |
| CContinuousLoader | Utility class for continuous loading |
| CDelegate | Basic delegate implementation |
| CDelegate< Ret(Args...)> | Utility class to send around functions and member functions |
| CDispatcher | Basic dispatcher implementation |
| ▼CEmitter | General purpose event emitter |
| CConnection | Generic connection type for events |
| Centt_traits | Entity traits |
| Centt_traits< std::uint16_t > | Entity traits for a 16 bits entity identifier |
| Centt_traits< std::uint32_t > | Entity traits for a 32 bits entity identifier |
| Centt_traits< std::uint64_t > | Entity traits for a 64 bits entity identifier |
| CFamily | Dynamic identifier generator |
| CHashedString | Zero overhead resource identifier |
| CIdentifier | Types identifiers |
| CInsertionSort | Function object for performing insertion sort |
| CMonostate | Minimal implementation of the monostate pattern |
| COneShotBubbleSort | Function object for performing bubble sort (single iteration) |
| Cpersistent_t | Persistent view type used to disambiguate overloads |
| CPersistentView | Persistent view |
| CProcess | Base class for processes |
| CProcessAdaptor | Adaptor for lambdas and functors to turn them into processes |
| CPrototype | Prototype container for concepts |
| Craw_t | Raw view type used to disambiguate overloads |
| CRawView | Raw view |
| CRegistry | Fast and reliable entity-component system |
| CResourceCache | Simple cache for resources of a given type |
| CResourceHandle | Shared resource handle |
| CResourceLoader | Base class for resource loaders |
| CRuntimeView | Runtime view |
| CScheduler | Cooperative scheduler for processes |
| CServiceLocator | Service locator, nothing more |
| CSigH | Unmanaged signal handler declaration |
| CSigH< Ret(Args...), Collector > | Unmanaged signal handler definition |
| CSink | Sink implementation |
| CSink< Ret(Args...)> | Sink implementation |
| CSnapshot | Utility class to create snapshots from a registry |
| CSnapshotLoader | Utility class to restore a snapshot as a whole |
| CSparseSet | Sparse set |
| CSparseSet< Entity > | Basic sparse set implementation |
| CSparseSet< Entity, Type > | Extended sparse set implementation |
| CStdSort | Function object to wrap std::sort in a class type |
| Ctag_t | Tag class type used to disambiguate overloads |
| CView | Multi component view |
| CView< Entity, Component > | Single component view specialization |
| CAttachee | Attachee |
| CAttachee< Entity > | Basic attachee implementation |
| CAttachee< Entity, Type > | Extended attachee implementation |
| CContinuousLoader | Utility class for continuous loading |
| CDelegate | Basic delegate implementation |
| CDelegate< Ret(Args...)> | Utility class to send around functions and member functions |
| CDispatcher | Basic dispatcher implementation |
| ▼CEmitter | General purpose event emitter |
| CConnection | Generic connection type for events |
| Centt_traits | Entity traits |
| Centt_traits< std::uint16_t > | Entity traits for a 16 bits entity identifier |
| Centt_traits< std::uint32_t > | Entity traits for a 32 bits entity identifier |
| Centt_traits< std::uint64_t > | Entity traits for a 64 bits entity identifier |
| CFamily | Dynamic identifier generator |
| CHashedString | Zero overhead resource identifier |
| CIdentifier | Types identifiers |
| CInsertionSort | Function object for performing insertion sort |
| CMonostate | Minimal implementation of the monostate pattern |
| COneShotBubbleSort | Function object for performing bubble sort (single iteration) |
| Cpersistent_t | Persistent view type used to disambiguate overloads |
| CPersistentView | Persistent view |
| CProcess | Base class for processes |
| CProcessAdaptor | Adaptor for lambdas and functors to turn them into processes |
| CPrototype | Prototype container for concepts |
| Craw_t | Raw view type used to disambiguate overloads |
| CRawView | Raw view |
| CRegistry | Fast and reliable entity-component system |
| CResourceCache | Simple cache for resources of a given type |
| CResourceHandle | Shared resource handle |
| CResourceLoader | Base class for resource loaders |
| CRuntimeView | Runtime view |
| CScheduler | Cooperative scheduler for processes |
| CServiceLocator | Service locator, nothing more |
| CSigH | Unmanaged signal handler declaration |
| CSigH< Ret(Args...), Collector > | Unmanaged signal handler definition |
| CSink | Sink implementation |
| CSink< Ret(Args...)> | Sink implementation |
| CSnapshot | Utility class to create snapshots from a registry |
| CSnapshotLoader | Utility class to restore a snapshot as a whole |
| CSparseSet | Sparse set |
| CSparseSet< Entity > | Basic sparse set implementation |
| CSparseSet< Entity, Type > | Extended sparse set implementation |
| CStdSort | Function object to wrap std::sort in a class type |
| Ctag_t | Tag class type used to disambiguate overloads |
| CView | Multi component view |
| CView< Entity, Component > | Single component view specialization |
|
+ EnTT
+ 2.7.3
+
+ |
+
+Generated by +
+ 1.8.13
+
+
+
diff --git a/autotoc_md0.html b/autotoc_md0.html
index d051bcbbe..a88903a50 100644
--- a/autotoc_md0.html
+++ b/autotoc_md0.html
@@ -22,7 +22,7 @@
|
+ EnTT
+ 2.7.3
+
+ |
+
+Introduction
+EnTT comes with a bunch of core functionalities mostly used by the other parts of the library itself.
+ Hardly users will include these features in their code, but it's worth describing what EnTT offers so as not to reinvent the wheel in case of need.
+Compile-time identifiers
+Sometimes it's useful to be able to give unique identifiers to types at compile-time.
+ There are plenty of different solutions out there and I could have used one of them. However, I decided to spend my time to define a compact and versatile tool that fully embraces what the modern C++ has to offer.
The result of my efforts is the Identifier class template:
This is all what the class template has to offer: a static get member function that returns a numerical identifier for the given type. It can be used in any context where constant expressions are required.
As long as the list remains unchanged, identifiers are also guaranteed to be the same for every run. In case they have been used in a production environment and a type has to be removed, one can just use a placeholder to left the other identifiers unchanged:
+A bit ugly to see, but it works at least.
++Runtime identifiers
+Sometimes it's useful to be able to give unique identifiers to types at runtime.
+ There are plenty of different solutions out there and I could have used one of them. In fact, I adapted the most common one to my requirements and used it extensively within the entire library.
It's the Family class. Here is an example of use directly from the entity-component system:
This is all what a family has to offer: a type member function that returns a numerical identifier for the given type.
Please, note that identifiers aren't guaranteed to be the same for every run. Indeed it mostly depends on the flow of execution.
++Hashed strings
+A hashed string is a zero overhead resource identifier. Users can use human-readable identifiers in the codebase while using their numeric counterparts at runtime, thus without affecting performance.
+ The class has an implicit constexpr constructor that chews a bunch of characters. Once created, all what one can do with it is getting back the original string or converting it into a number.
+ The good part is that a hashed string can be used wherever a constant expression is required and no string-to-number conversion will take place at runtime if used carefully.
Example of use:
+There is also a user defined literal dedicated to hashed strings to make them more user-friendly:
++Conflicts
+The hashed string class uses internally FNV-1a to compute the numeric counterpart of a string. Because of the pigeonhole principle, conflicts are possible. This is a fact.
+ There is no silver bullet to solve the problem of conflicts when dealing with hashing functions. In this case, the best solution seemed to be to give up. That's all.
+ After all, human-readable resource identifiers aren't something strictly defined and over which users have not the control. Choosing a slightly different identifier is probably the best solution to make the conflict disappear in this case.
+Monostate
+The monostate pattern is often presented as an alternative to a singleton based configuration system. This is exactly its purpose in EnTT. Moreover, this implementation is thread safe by design (hopefully).
+ Keys are represented by hashed strings, values are basic types like ints or bools. Values of different types can be associated to each key, even more than one at a time. Because of this, users must pay attention to use the same type both during an assignment and when they try to read back their data. Otherwise, they will probably incur in unexpected results.
Example of use:
++Generated by +
+ 1.8.13
+
+
+
diff --git a/autotoc_md41.html b/autotoc_md41.html
new file mode 100644
index 000000000..9cf9e38a1
--- /dev/null
+++ b/autotoc_md41.html
@@ -0,0 +1,84 @@
+
+
+
+
+
+
+
+|
+ EnTT
+ 2.7.3
+
+ |
+
+Introduction
+Usually service locators are tightly bound to the services they expose and it's hard to define a general purpose solution. This template based implementation tries to fill the gap and to get rid of the burden of defining a different specific locator for each application.
+ This class is tiny, partially unsafe and thus risky to use. Moreover it doesn't fit probably most of the scenarios in which a service locator is required. Look at it as a small tool that can sometimes be useful if users know how to handle it.
+Service locator
+The API is straightforward. The basic idea is that services are implemented by means of interfaces and rely on polymorphism.
+ The locator is instantiated with the base type of the service if any and a concrete implementation is provided along with all the parameters required to initialize it. As an example:
The locator can also be queried to know if an active service is currently set and to retrieve it if necessary (either as a pointer or as a reference):
+A common use is to wrap the different locators in a container class, creating aliases for the various services:
++Generated by +
+ 1.8.13
+
+
+
diff --git a/autotoc_md44.html b/autotoc_md44.html
new file mode 100644
index 000000000..b7c8c9452
--- /dev/null
+++ b/autotoc_md44.html
@@ -0,0 +1,133 @@
+
+
+
+
+
+
+
+|
+ EnTT
+ 2.7.3
+
+ |
+
+Introduction
+Sometimes processes are a useful tool to work around the strict definition of a system and introduce logic in a different way, usually without resorting to the introduction of other components.
+EnTT offers a minimal support to this paradigm by introducing a few classes that users can use to define and execute cooperative processes.
+The process
+A typical process must inherit from the Process class template that stays true to the CRTP idiom. Moreover, derived classes must specify what's the intended type for elapsed times.
A process should expose publicly the following member functions whether required (note that it isn't required to define a function unless the derived class wants to override the default behavior):
+-
+
+void update(Delta, void *);It's invoked once per tick until a process is explicitly aborted or it terminates either with or without errors. Even though it's not mandatory to declare this member function, as a rule of thumb each process should at least define it to work properly. The
+void *parameter is an opaque pointer to user data (if any) forwarded directly to the process during an update.
+
+void init(void *);It's invoked at the first tick, immediately before an update. The
+void *parameter is an opaque pointer to user data (if any) forwarded directly to the process during an update.
+
+void succeeded();It's invoked in case of success, immediately after an update and during the same tick.
+
+
+void failed();It's invoked in case of errors, immediately after an update and during the same tick.
+
+
+void aborted();It's invoked only if a process is explicitly aborted. There is no guarantee that it executes in the same tick, this depends solely on whether the process is aborted immediately or not.
+
+
Derived classes can also change the internal state of a process by invoking succeed and fail, as well as pause and unpause the process itself. All these are protected member functions made available to be able to manage the life cycle of a process from a derived class.
Here is a minimal example for the sake of curiosity:
++Adaptor
+Lambdas and functors can't be used directly with a scheduler for they are not properly defined processes with managed life cycles.
+ This class helps in filling the gap and turning lambdas and functors into full featured processes usable by a scheduler.
The function call operator has a signature similar to the one of the update function of a process but for the fact that it receives two extra arguments to call whenever a process is terminated with success or with an error:
Parameters have the following meaning:
+-
+
deltais the elapsed time.
+datais an opaque pointer to user data if any,nullptrotherwise.
+succeedis a function to call when a process terminates with success.
+failis a function to call when a process terminates with errors.
+
Both succeed and fail accept no parameters at all.
Note that usually users shouldn't worry about creating adaptors at all. A scheduler creates them internally each and every time a lambda or a functor is used as a process.
++The scheduler
+A cooperative scheduler runs different processes and helps managing their life cycles.
+Each process is invoked once per tick. If it terminates, it's removed automatically from the scheduler and it's never invoked again. Otherwise it's a good candidate to run once more the next tick.
+ A process can also have a child. In this case, the process is replaced with its child when it terminates if it returns with success. In case of errors, both the process and its child are discarded. This way, it's easy to create chain of processes to run sequentially.
Using a scheduler is straightforward. To create it, users must provide only the type for the elapsed times and no arguments at all:
+It has member functions to query its internal data structures, like empty or size, as well as a clear utility to reset it to a clean state:
To attach a process to a scheduler there are mainly two ways:
+-
+
- If the process inherits from the
Processclass template, it's enough to indicate its type and submit all the parameters required to construct it to theattachmember function:
+
-
+
- Otherwise, in case of a lambda or a functor, it's enough to provide an instance of the class to the
attachmember function:
+
In both cases, the return value is an opaque object that offers a then member function to use to create chains of processes to run sequentially.
+ As a minimal example of use:
To update a scheduler and thus all its processes, the update member function is the way to go:
In addition to these functions, the scheduler offers an abort member function that can be used to discard all the running processes at once:
+Generated by +
+ 1.8.13
+
+
+
diff --git a/autotoc_md49.html b/autotoc_md49.html
new file mode 100644
index 000000000..dc39051cc
--- /dev/null
+++ b/autotoc_md49.html
@@ -0,0 +1,124 @@
+
+
+
+
+
+
+
+|
+ EnTT
+ 2.7.3
+
+ |
+
+Introduction
+Resource management is usually one of the most critical part of a software like a game. Solutions are often tuned to the particular application. There exist several approaches and all of them are perfectly fine as long as they fit the requirements of the piece of software in which they are used.
+ Examples are loading everything on start, loading on request, predictive loading, and so on.
EnTT doesn't pretend to offer a one-fits-all solution for the different cases. Instead, it offers a minimal and perhaps trivial cache that can be useful most of the time during prototyping and sometimes even in a production environment.
+ For those interested in the subject, the plan is to improve it considerably over time in terms of performance, memory usage and functionalities. Hoping to make it, of course, one step at a time.
+The resource, the loader and the cache
+There are three main actors in the model: the resource, the loader and the cache.
+The resource is whatever users want it to be. An image, a video, an audio, whatever. There are no limits.
+ As a minimal example:
A loader is a class the aim of which is to load a specific resource. It has to inherit directly from the dedicated base class as in the following example:
+Where MyResource is the type of resources it creates.
+ A resource loader must also expose a public const member function named load that accepts a variable number of arguments and returns a shared pointer to a resource.
+ As an example:
In general, resource loaders should not have a state or retain data of any type. They should let the cache manage their resources instead.
+ As a side note, base class and CRTP idiom aren't strictly required with the current implementation. One could argue that a cache can easily work with loaders of any type. However, future changes won't be breaking ones by forcing the use of a base class today and that's why the model is already in its place.
Finally, a cache is a specialization of a class template tailored to a specific resource:
+The idea is to create different caches for different types of resources and to manage each one independently and in the most appropriate way.
+ As a (very) trivial example, audio tracks can survive in most of the scenes of an application while meshes can be associated with a single scene and then discarded when users leave it.
A cache offers a set of basic functionalities to query its internal state and to organize it:
+Besides these member functions, it contains what is needed to load, use and discard resources of the given type.
+ Before to explore this part of the interface, it makes sense to mention how resources are identified. The type of the identifiers to use is defined as:
Where resource_type is an alias for entt::HashedString. Therefore, resource identifiers are created explicitly as in the following example:
The class HashedString is described in a dedicated section, so I won't do in details here.
Resources are loaded and thus stored in a cache through the load member function. It accepts the loader to use as a template parameter, the resource identifier and the parameters used to construct the resource as arguments:
The return value can be used to know if the resource has been loaded correctly. In case the loader returns an invalid pointer or the resource already exists in the cache, a false value is returned:
+Unfortunately, in this case there is no way to know what was the problem exactly. However, before trying to load a resource or after an error, one can use the contains member function to know if a cache already contains a specific resource:
There exists also a member function to use to force a reload of an already existing resource if needed:
+As above, the function returns true in case of success, false otherwise. The sole difference in this case is that an error necessarily means that the loader has failed for some reasons to load the resource.
+ Note that the reload member function is a kind of alias of the following snippet:
Where the discard member function is used to get rid of a resource if loaded. In case the cache doesn't contain a resource for the given identifier, the function does nothing and returns immediately.
So far, so good. Resources are finally loaded and stored within the cache.
+ They are returned to users in the form of handles. To get one of them:
The idea behind a handle is the same of the flyweight pattern. In other terms, resources aren't copied around. Instead, instances are shared between handles. Users of a resource owns a handle and it guarantees that a resource isn't destroyed until all the handles are destroyed, even if the resource itself is removed from the cache.
+ Handles are tiny objects both movable and copyable. They returns the contained resource as a const reference on request:
-
+
- By means of the
getmember function:
+
-
+
- Using the proper cast operator: +
-
+
- Through the dereference operator: +
The resource can also be accessed directly using the arrow operator if required:
+To test if a handle is still valid, the cast operator to bool allows users to use it in a guard:
Finally, in case there is the need to load a resource and thus to get a handle without storing the resource itself in the cache, users can rely on the temp member function template.
+ The declaration is similar to the one of load but for the fact that it doesn't return a boolean value. Instead, it returns a (possibly invalid) handle for the resource:
Do not forget to test the handle for validity. Otherwise, getting the reference to the resource it points may result in undefined behavior.
++Generated by +
+ 1.8.13
+
+
+
diff --git a/autotoc_md52.html b/autotoc_md52.html
new file mode 100644
index 000000000..f6fb54a2e
--- /dev/null
+++ b/autotoc_md52.html
@@ -0,0 +1,84 @@
+
+
+
+
+
+
+
+|
+ EnTT
+ 2.7.3
+
+ |
+
To make sure that an application and a shared library that use both EnTT can interact correctly when symbols are hidden by default, there are some tricks to follow.
+ In particular and in order to avoid undefined behaviors, all the instantiation of the Family class template shall be made explicit along with the system-wide specifier to use to export them.
At the time I'm writing this document, the classes that use internally the above mentioned class template are Dispatcher, Emitter and Registry. Therefore and as an example, if you use the Registry class template in your shared library and want to set symbols visibility to hidden by default, the following lines are required to allow it to function properly with a client that also uses the Registry somehow:
-
+
- On GNU/Linux: +
-
+
- On Windows: +
Otherwise, the risk is that type identifiers are different between the shared library and the application and this will prevent the whole thing from functioning correctly for obvious reasons.
++Generated by +
+ 1.8.13
+
+
+
diff --git a/autotoc_md53.html b/autotoc_md53.html
new file mode 100644
index 000000000..66fc871f2
--- /dev/null
+++ b/autotoc_md53.html
@@ -0,0 +1,147 @@
+
+
+
+
+
+
+
+|
+ EnTT
+ 2.7.3
+
+ |
+
+Introduction
+Signals are usually a core part of games and software architectures in general.
+ Roughly speaking, they help to decouple the various parts of a system while allowing them to communicate with each other somehow.
The so called _modern C++_ comes with a tool that can be useful in these terms, the std::function. As an example, it can be used to create delegates.
+ However, there is no guarantee that an std::function does not perform allocations under the hood and this could be problematic sometimes. Furthermore, it solves a problem but may not adapt well to other requirements that may arise from time to time.
In case that the flexibility and potential of an std::function are not required or where you are looking for something different, EnTT offers a full set of classes to solve completely different problems.
+Signals
+Signal handlers work with naked pointers, function pointers and pointers to member functions. Listeners can be any kind of objects and users are in charge of connecting and disconnecting them from a signal to avoid crashes due to different lifetimes. On the other side, performance shouldn't be affected that much by the presence of such a signal handler.
+ A signal handler can be used as a private data member without exposing any publish functionality to the clients of a class. The basic idea is to impose a clear separation between the signal itself and its sink class, that is a tool to be used to connect and disconnect listeners on the fly.
The API of a signal handler is straightforward. The most important thing is that it comes in two forms: with and without a collector. In case a signal is associated with a collector, all the values returned by the listeners can be literally collected and used later by the caller. Otherwise it works just like a plain signal that emits events from time to time.
+
Note: collectors are allowed only in case of function types whose the return type isn't void for obvious reasons.
To create instances of signal handlers there exist mainly two ways:
+As expected, they offer all the basic functionalities required to know how many listeners they contain (size) or if they contain at least a listener (empty) and even to swap two signal handlers (swap).
Besides them, there are member functions to use both to connect and disconnect listeners in all their forms by means of a sink:
+Once listeners are attached (or even if there are no listeners at all), events and data in general can be published through a signal by means of the publish member function:
To collect data, the collect member function should be used instead. Below is a minimal example to show how to use it:
As shown above, a collector must expose a function operator that accepts as an argument a type to which the return type of the listeners can be converted. Moreover, it has to return a boolean value that is false to stop collecting data, true otherwise. This way one can avoid calling all the listeners in case it isn't necessary.
++Delegate
+A delegate can be used as general purpose invoker with no memory overhead for free functions and member functions provided along with an instance on which to invoke them.
+ It does not claim to be a drop-in replacement for an std::function, so do not expect to use it whenever an std::function fits well. However, it can be used to send opaque delegates around to be used to invoke functions as needed.
The interface is trivial. It offers a default constructor to create empty delegates:
+All what is needed to create an instance is to specify the type of the function the delegate will contain, that is the signature of the free function or the member function one wants to assign to it.
+Attempting to use an empty delegate by invoking its function call operator results in undefined behavior, most likely a crash actually. Before to use a delegate, it must be initialized.
+ There exist two functions to do that, both named connect:
It hasn't a disconnect counterpart. Instead, there exists a reset member function to clear it.
+ The empty member function can be used to know if a delegate is empty:
Finally, to invoke a delegate, the function call operator is the way to go as usual:
+Probably too much small and pretty poor of functionalities, but the delegate class can help in a lot of cases and it has shown that it is worth keeping it within the library.
++Event dispatcher
+The event dispatcher class is designed so as to be used in a loop. It allows users both to trigger immediate events or to queue events to be published all together once per tick.
+ This class shares part of its API with the one of the signal handler, but it doesn't require that all the types of events are specified when declared:
In order to register an instance of a class to a dispatcher, its type must expose one or more member functions of which the return types are void and the argument lists are const E &, for each type of event E.
+ To ease the development, member functions that are named receive are automatically detected and have not to be explicitly specified when registered. In all the other cases, the name of the member function aimed to receive the event must be provided to the connect member function of the sink bound to the specific event:
The disconnect member function follows the same pattern and can be used to selectively remove listeners:
The trigger member function serves the purpose of sending an immediate event to all the listeners registered so far. It offers a convenient approach that relieves users from having to create the event itself. Instead, it's enough to specify the type of event and provide all the parameters required to construct it.
+ As an example:
Listeners are invoked immediately, order of execution isn't guaranteed. This method can be used to push around urgent messages like an is terminating notification on a mobile app.
+On the other hand, the enqueue member function queues messages together and allows to maintain control over the moment they are sent to listeners. The signature of this method is more or less the same of trigger:
Events are stored aside until the update member function is invoked, then all the messages that are still pending are sent to the listeners at once:
This way users can embed the dispatcher in a loop and literally dispatch events once per tick to their systems.
++Event emitter
+A general purpose event emitter thought mainly for those cases where it comes to working with asynchronous stuff.
+ Originally designed to fit the requirements of uvw (a wrapper for libuv written in modern C++), it was adapted later to be included in this library.
To create a custom emitter type, derived classes must inherit directly from the base class as:
+The full list of accepted types of events isn't required. Handlers are created internally on the fly and thus each type of event is accepted by default.
+Whenever an event is published, an emitter provides the listeners with a reference to itself along with a const reference to the event. Therefore listeners have an handy way to work with it without incurring in the need of capturing a reference to the emitter itself.
+ In addition, an opaque object is returned each time a connection is established between an emitter and a listener, allowing the caller to disconnect them at a later time.
+ The opaque object used to handle connections is both movable and copyable. On the other side, an event emitter is movable but not copyable by default.
To create new instances of an emitter, no arguments are required:
+Listeners must be movable and callable objects (free functions, lambdas, functors, std::functions, whatever) whose function type is:
Where Event is the type of event they want to listen.
+ There are two ways to attach a listener to an event emitter that differ slightly from each other:
-
+
- To register a long-lived listener, use the
onmember function. It is meant to register a listener designed to be invoked more than once for the given event type.
+ As an example:
+
The connection object can be freely discarded. Otherwise, it can be used later to disconnect the listener if required.
+-
+
- To register a short-lived listener, use the
oncemember function. It is meant to register a listener designed to be invoked only once for the given event type. The listener is automatically disconnected after the first invocation.
+ As an example:
+
The connection object can be freely discarded. Otherwise, it can be used later to disconnect the listener if required.
+In both cases, the connection object can be used with the erase member function:
There are also two member functions to use either to disconnect all the listeners for a given type of event or to clear the emitter:
+To send an event to all the listeners that are interested in it, the publish member function offers a convenient approach that relieves users from having to create the event:
Finally, the empty member function tests if there exists at least either a listener registered with the event emitter or to a given type of event:
In general, the event emitter is a handy tool when the derived classes wrap asynchronous operations, because it introduces a nice-to-have model based on events and listeners that kindly hides the complexity behind the scenes. However it is not limited to such uses.
++Generated by +
+ 1.8.13
+
+
+
diff --git a/autotoc_md8.html b/autotoc_md8.html
new file mode 100644
index 000000000..699d95ad5
--- /dev/null
+++ b/autotoc_md8.html
@@ -0,0 +1,461 @@
+
+
+
+
+
+
+
+|
+ EnTT
+ 2.7.3
+
+ |
+
+Introduction
+EnTT is a header-only, tiny and easy to use entity-component system (and much more) written in modern C++.
+ The entity-component-system (also known as ECS) is an architectural pattern used mostly in game development.
+Design choices
++A bitset-free entity-component system
+EnTT is a bitset-free entity-component system that doesn't require users to specify the component set at compile-time.
+ This is why users can instantiate the core class simply like:
In place of its more annoying and error-prone counterpart:
++Pay per use
+EnTT is entirely designed around the principle that users have to pay only for what they want.
When it comes to using an entity-component system, the tradeoff is usually between performance and memory usage. The faster it is, the more memory it uses. However, slightly worse performance along non-critical paths are the right price to pay to reduce memory usage and I've always wondered why this kind of tools do not leave me the choice.
+ EnTT follows a completely different approach. It squeezes the best from the basic data structures and gives users the possibility to pay more for higher performance where needed.
+ The disadvantage of this approach is that users need to know the systems they are working on and the tools they are using. Otherwise, the risk to ruin the performance along critical paths is high.
So far, this choice has proven to be a good one and I really hope it can be for many others besides me.
++Vademecum
+The Registry to store, the views to iterate. That's all.
An entity (the E of an ECS) is an opaque identifier that users should just use as-is and store around if needed. Do not try to inspect an entity identifier, its format can change in future and a registry offers all the functionalities to query them out-of-the-box. The underlying type of an entity (either std::uint16_t, std::uint32_t or std::uint64_t) can be specified when defining a registry (actually the DefaultRegistry is nothing more than a Registry where the type of the entities is std::uint32_t).
+ Components (the C of an ECS) should be plain old data structures or more complex and movable data structures with a proper constructor. Actually, the sole requirement of a component type is that it must be both move constructible and move assignable. They are list initialized by using the parameters provided to construct the component itself. No need to register components or their types neither with the registry nor with the entity-component system at all.
+ Systems (the S of an ECS) are just plain functions, functors, lambdas or whatever users want. They can accept a Registry or a view of any type and use them the way they prefer. No need to register systems or their types neither with the registry nor with the entity-component system at all.
The following sections will explain in short how to use the entity-component system, the core part of the whole library.
+ In fact, the project is composed of many other classes in addition to those describe below. For more details, please refer to the inline documentation.
+The Registry, the Entity and the Component
+A registry can store and manage entities, as well as create views to iterate the underlying data structures.
+ Registry is a class template that lets users decide what's the preferred type to represent an entity. Because std::uint32_t is large enough for almost all the cases, there exists also an alias named DefaultRegistry for Registry<std::uint32_t>.
Entities are represented by entity identifiers. An entity identifier is an opaque type that users should not inspect or modify in any way. It carries information about the entity itself and its version.
+A registry can be used both to construct and destroy entities:
+Entities can also be destroyed by type, that is by specifying the types of the tags or components that identify them:
+When an entity is destroyed, the registry can freely reuse it internally with a slightly different identifier. In particular, the version of an entity is increased each and every time it's discarded.
+ In case entity identifiers are stored around, the registry offers all the functionalities required to test them and get out of the them all the information they carry:
Components can be assigned to or removed from entities at any time with a few calls to member functions of the registry. As for the entities, the registry offers also a set of functionalities users can use to work with the components.
+The assign member function template creates, initializes and assigns to an entity the given component. It accepts a variable number of arguments to construct the component itself if present:
If an entity already has the given component, the replace member function template can be used to replace it:
In case users want to assign a component to an entity, but it's unknown whether the entity already has it or not, accommodate does the work in a single call (there is a performance penalty to pay for this mainly due to the fact that it has to check if the entity already has the given component or not):
Note that accommodate is a slightly faster alternative for the following if/else statement and nothing more:
As already shown, if in doubt about whether or not an entity has one or more components, the has member function template may be useful:
On the other side, if the goal is to delete a single component, the remove member function template is the way to go when it's certain that the entity owns a copy of the component:
Otherwise consider to use the reset member function. It behaves similarly to remove but with a strictly defined behavior (and a performance penalty is the price to pay for this). In particular it removes the component if and only if it exists, otherwise it returns safely to the caller:
There exist also two other versions of the reset member function:
-
+
- If no entity is passed to it,
resetwill remove the given component from each entity that has it:
+
-
+
- If neither the entity nor the component are specified, all the entities still in use and their components are destroyed: +
Finally, references to components can be retrieved simply by doing this:
+The get member function template gives direct access to the component of an entity stored in the underlying data structures of the registry.
+Single instance components
+In those cases where all what is needed is a single instance component, tags are the right tool to achieve the purpose.
+ Tags undergo the same requirements of components. They can be either plain old data structures or more complex and movable data structures with a proper constructor.
+ Actually, the same type can be used both as a tag and as a component and the registry will not complain about it. It is up to users to properly manage their own types. In some cases, the tag tag_t must also be used in order to disambiguate overloads of member functions.
Attaching tags to entities and removing them is trivial:
+In case a tag already has an owner, its content can be updated by means of the replace member function template and the ownership of the tag can be transferred to another entity using the move member function template:
If in doubt about whether or not a tag already has an owner, the has member function template may be useful:
References to tags can be retrieved simply by doing this:
+The get member function template gives direct access to the tag as stored in the underlying data structures of the registry.
As shown above, in almost all the cases the entity identifier isn't required. Since a single instance component can have only one associated entity, it doesn't make much sense to mention it explicitly.
+ To find out who the owner is, just do the following:
Note that iterating tags isn't possible for obvious reasons. Tags give direct access to single entities and nothing more.
++Observe changes
+Because of how the registry works internally, it stores a couple of signal handlers for each pool in order to notify some of its data structures on the construction and destruction of components.
+ These signal handlers are also exposed and made available to users. This is the basic brick to build fancy things like dependencies and reactive systems.
To get a sink to be used to connect and disconnect listeners so as to be notified on the creation of a component, use the construction member function:
To be notified when components are destroyed, use the destruction member function instead.
The function type of a listener is the same in both cases:
+In other terms, a listener is provided with the registry that triggered the notification and the entity affected by the change. Note also that:
+-
+
- Listeners are invoked after components have been assigned to entities. +
- Listeners are invoked before components have been removed from entities. +
- The order of invocation of the listeners isn't guaranteed in any case. +
There are also some limitations on what a listener can and cannot do. In particular:
+-
+
- Connecting and disconnecting other functions from within the body of a listener should be avoided. It can lead to undefined behavior in some cases. +
- Assigning and removing components and tags from within the body of a listener that observes the destruction of instances of a given type should be avoided. It can lead to undefined behavior in some cases. This type of listeners is intended to provide users with an easy way to perform cleanup and nothing more. +
To a certain extent, these limitations do not apply. However, it is risky to try to force them and users should respect the limitations unless they know exactly what they are doing. Subtle bugs are the price to pay in case of errors otherwise.
+In general, events and therefore listeners must not be used as replacements for systems. They should not contain much logic and interactions with a registry should be kept to a minimum, if possible. Note also that the greater the number of listeners, the greater the performance hit when components are created or destroyed.
++Who let the tags out?
+As an extension, signals are also provided with tags. Although they are not strictly required internally, it makes sense that a user expects signal support even when it comes to tags actually.
+ Signals for tags undergo exactly the same requirements of those introduced for components. Also the function type for a listener is the same and it's invoked with the same guarantees discussed above.
To get the sinks for a tag just use tag tag_t to disambiguate overloads of member functions as in the following example:
Listeners for tags and components are managed separately and do not influence each other in any case. Therefore, note that the greater the number of listeners for a type, the greater the performance hit when a tag of the given type is created or destroyed.
++Runtime components
+Defining components at runtime is useful to support plugin systems and mods in general. However, it seems impossible with a tool designed around a bunch of templates. Indeed it's not that difficult.
+ Of course, some features cannot be easily exported into a runtime environment. As an example, sorting a group of components defined at runtime isn't for free if compared to most of the other operations. However, the basic functionalities of an entity-component system such as EnTT fit the problem perfectly and can also be used to manage runtime components if required.
+ All that is necessary to do it is to know the identifiers of the components. An identifier is nothing more than a number or similar that can be used at runtime to work with the type system.
In EnTT, identifiers are easily accessible:
Once the identifiers are made available, almost everything becomes pretty simple.
++A journey through a plugin
+EnTT comes with an example (actually a test) that shows how to integrate compile-time and runtime components in a stack based JavaScript environment. It uses Duktape under the hood, mainly because I wanted to learn how it works at the time I was writing the code.
The code is not production-ready and overall performance can be highly improved. However, I sacrificed optimizations in favor of a more readable piece of code. I hope I succeeded.
+ Note also that this isn't neither the only nor (probably) the best way to do it. In fact, the right way depends on the scripting language and the problem one is facing in general.
+ That being said, feel free to use it at your own risk.
The basic idea is that of creating a compile-time component aimed to map all the runtime components assigned to an entity.
+ Identifiers come in use to address the right function from a map when invoked from the runtime environment and to filter entities when iterating.
+ With a bit of gymnastic, one can narrow views and improve the performance to some extent but it was not the goal of the example.
+Sorting: is it possible?
+It goes without saying that sorting entities and components is possible with EnTT.
+ In fact, there are two functions that respond to slightly different needs:
-
+
- Components can be sorted directly: +
There exists also the possibility to use a custom sort function object, as long as it adheres to the requirements described in the inline documentation.
+ This is possible mainly because users can get much more with a custom sort function object if the pattern of usage is known. As an example, in case of an almost sorted pool, quick sort could be much, much slower than insertion sort.
-
+
- Components can be sorted according to the order imposed by another component: +
In this case, instances of Movement are arranged in memory so that cache misses are minimized when the two components are iterated together.
+Snapshot: complete vs continuous
+The Registry class offers basic support to serialization.
+ It doesn't convert components and tags to bytes directly, there wasn't the need of another tool for serialization out there. Instead, it accepts an opaque object with a suitable interface (namely an archive) to serialize its internal data structures and restore them later. The way types and instances are converted to a bunch of bytes is completely in charge to the archive and thus to final users.
The goal of the serialization part is to allow users to make both a dump of the entire registry or a narrower snapshot, that is to select only the components and the tags in which they are interested.
+ Intuitively, the use cases are different. As an example, the first approach is suitable for local save/restore functionalities while the latter is suitable for creating client-server applications and for transferring somehow parts of the representation side to side.
To take a snapshot of the registry, use the snapshot member function. It returns a temporary object properly initialized to save the whole registry or parts of it.
Example of use:
+It isn't necessary to invoke all these functions each and every time. What functions to use in which case mostly depends on the goal and there is not a golden rule to do that.
+The entities member function asks the registry to serialize all the entities that are still in use along with their versions. On the other side, the destroyed member function tells to the registry to serialize the entities that have been destroyed and are no longer in use.
+ These two functions can be used to save and restore the whole set of entities with the versions they had during serialization.
The component member function is a function template the aim of which is to store aside components. The presence of a template parameter list is a consequence of a couple of design choices from the past and in the present:
-
+
- First of all, there is no reason to force a user to serialize all the components at once and most of the times it isn't desiderable. As an example, in case the stuff for the HUD in a game is put into the registry for some reasons, its components can be freely discarded during a serialization step because probably the software already knows how to reconstruct the HUD correctly from scratch. +
- Furthermore, the registry makes heavy use of type-erasure techniques internally and doesn't know at any time what types of components it contains. Therefore being explicit at the call point is mandatory. +
There exists also another version of the component member function that accepts a range of entities to serialize. This version is a bit slower than the other one, mainly because it iterates the range of entities more than once for internal purposes. However, it can be used to filter out those entities that shouldn't be serialized for some reasons.
+ As an example:
The tag member function is similar to the previous one, apart from the fact that it works with tags and not with components.
+ Note also that both component and tag store items along with entities. It means that they work properly without a call to the entities member function.
Once a snapshot is created, there exist mainly two ways to load it: as a whole and in a kind of continuous mode.
+ The following sections describe both loaders and archives in details.
+Snapshot loader
+A snapshot loader requires that the destination registry be empty and loads all the data at once while keeping intact the identifiers that the entities originally had.
+ To do that, the registry offers a member function named restore that returns a temporary object properly initialized to restore a snapshot.
Example of use:
+It isn't necessary to invoke all these functions each and every time. What functions to use in which case mostly depends on the goal and there is not a golden rule to do that. For obvious reasons, what is important is that the data are restored in exactly the same order in which they were serialized.
+The entities and destroyed member functions restore the sets of entities and the versions that the entities originally had at the source.
The component member function restores all and only the components specified and assigns them to the right entities. Note that the template parameter list must be exactly the same used during the serialization. The same applies to the tag member function.
The orphans member function literally destroys those entities that have neither components nor tags. It's usually useless if the snapshot is a full dump of the source. However, in case all the entities are serialized but only few components and tags are saved, it could happen that some of the entities have neither components nor tags once restored. The best users can do to deal with them is to destroy those entities and thus update their versions.
+Continuous loader
+A continuous loader is designed to load data from a source registry to a (possibly) non-empty destination. The loader can accommodate in a registry more than one snapshot in a sort of continuous loading that updates the destination one step at a time.
+ Identifiers that entities originally had are not transferred to the target. Instead, the loader maps remote identifiers to local ones while restoring a snapshot. Because of that, this kind of loader offers a way to update automatically identifiers that are part of components or tags (as an example, as data members or gathered in a container).
+ Another difference with the snapshot loader is that the continuous loader does not need to work with the private data structures of a registry. Furthermore, it has an internal state that must persist over time. Therefore, there is no reason to create it by means of a registry, or to limit its lifetime to that of a temporary object.
Example of use:
+It isn't necessary to invoke all these functions each and every time. What functions to use in which case mostly depends on the goal and there is not a golden rule to do that. For obvious reasons, what is important is that the data are restored in exactly the same order in which they were serialized.
+The entities and destroyed member functions restore groups of entities and map each entity to a local counterpart when required. In other terms, for each remote entity identifier not yet registered by the loader, the latter creates a local identifier so that it can keep the local entity in sync with the remote one.
The component and tag member functions restore all and only the components and the tags specified and assign them to the right entities.
+ In case the component or the tag contains entities itself (either as data members of type entity_type or as containers of entities), the loader can update them automatically. To do that, it's enough to specify the data members to update as shown in the example.
The orphans member function literally destroys those entities that have neither components nor tags after a restore. It has exactly the same purpose described in the previous section and works the same way.
Finally, shrink helps to purge local entities that no longer have a remote conterpart. Users should invoke this member function after restoring each snapshot, unless they know exactly what they are doing.
+Archives
+Archives must publicly expose a predefined set of member functions. The API is straightforward and consists only of a group of function call operators that are invoked by the snapshot class and the loaders.
+In particular:
+-
+
- An output archive, the one used when creating a snapshot, must expose a function call operator with the following signature to store entities: +
Where Entity is the type of the entities used by the registry. Note that all the member functions of the snapshot class make also an initial call to this endpoint to save the size of the set they are going to store.
+ In addition, an archive must accept a pair of entity and either component or tag for each type to be serialized. Therefore, given a type T, the archive must contain a function call operator with the following signature:
The output archive can freely decide how to serialize the data. The register is not affected at all by the decision.
+-
+
- An input archive, the one used when restoring a snapshot, must expose a function call operator with the following signature to load entities: +
Where Entity is the type of the entities used by the registry. Each time the function is invoked, the archive must read the next element from the underlying storage and copy it in the given variable. Note that all the member functions of a loader class make also an initial call to this endpoint to read the size of the set they are going to load.
+ In addition, the archive must accept a pair of entity and either component or tag for each type to be restored. Therefore, given a type T, the archive must contain a function call operator with the following signature:
Every time such an operator is invoked, the archive must read the next elements from the underlying storage and copy them in the given variables.
++One example to rule them all
+EnTT comes with some examples (actually some tests) that show how to integrate a well known library for serialization as an archive. It uses Cereal C++ under the hood, mainly because I wanted to learn how it works at the time I was writing the code.
The code is not production-ready and it isn't neither the only nor (probably) the best way to do it. However, feel free to use it at your own risk.
+The basic idea is to store everything in a group of queues in memory, then bring everything back to the registry with different loaders.
++Prototype
+A prototype defines a type of an application in terms of its parts. They can be used to assign components to entities of a registry at once.
+ Roughly speaking, in most cases prototypes can be considered just as templates to use to initialize entities according to concepts. In fact, users can create how many prototypes they want, each one initialized differently from the others.
The following is an example of use of a prototype:
+To assign and remove components from a prototype, it offers two dedicated member functions named set and unset. The has member function can be used to know if a given prototype contains one or more components and the get member function can be used to retrieve the components.
Creating an entity from a prototype is straightforward:
+-
+
- To create a new entity from scratch and assign it a prototype, this is the way to go: It is equivalent to the following invokation:const auto entity = prototype();const auto entity = prototype.create();
+
- In case we want to initialize an already existing entity, we can provide the
operator()directly with the entity identifier:It is equivalent to the following invokation:prototype(entity);Note that existing components aren't overwritten in this case. Only those components that the entity doesn't own yet are copied over. All the other components remain unchanged.prototype.assign(entity);
+ - Finally, to assign or replace all the components for an entity, thus overwriting existing ones: prototype.accommodate(entity);
+
In the examples above, the prototype uses its underlying registry to create entities and components both for its purposes and when it's cloned. To use a different repository to clone a prototype, all the member functions accept also a reference to a valid registry as a first argument.
+Prototypes are a very useful tool that can save a lot of typing sometimes. Furthermore, the codebase may be easier to maintain, since updating a prototype is much less error prone than jumping around in the codebase to update all the snippets copied and pasted around to initialize entities and components.
++Helpers
+The so called helpers are small classes and functions mainly designed to offer built-in support for the most basic functionalities.
+ The list of helpers will grow longer as time passes and new ideas come out.
+Dependency function
+A dependency function is a predefined listener, actually a function template to use to automatically assign components to an entity when a type has a dependency on some other types.
+ The following adds components AType and AnotherType whenever MyType is assigned to an entity:
A component is assigned to an entity and thus default initialized only in case the entity itself hasn't it yet. It means that already existent components won't be overriden.
+ A dependency can easily be broken by means of the following function template:
+Labels
+There's nothing magical about the way labels can be assigned to entities while avoiding a performance hit at runtime. Nonetheless, the syntax can be annoying and that's why a more user-friendly shortcut is provided to do it.
+ This shortcut is the alias template entt::label.
If used in combination with hashed strings, it helps to use labels where types would be required otherwise. As an example:
++Null entity
+In EnTT, there exists a sort of null entity made available to users that is accessible via the entt::null variable.
+ The library guarantees that the following expression always returns false:
In other terms, a registry will reject the null entity in all cases because it isn't considered valid. It means that the null entity cannot own components or tags for obvious reasons.
+ The type of the null entity is internal and should not be used for any purpose other than defining the null entity itself. However, there exist implicit conversions from the null entity to identifiers of any allowed type:
Similarly, the null entity can be compared to any other identifier:
++View: to persist or not to persist?
+First of all, it is worth answering an obvious question: why views?
+ Roughly speaking, they are a good tool to enforce single responsibility. A system that has access to a registry can create and destroy entities, as well as assign and remove components. On the other side, a system that has access to a view can only iterate entities and their components, then read or update the data members of the latter.
+ It is a subtle difference that can help designing a better software sometimes.
There are mainly four kinds of views: standard (also known as View), persistent (also known as PersistentView), raw (also known as RawView) and runtime (also known as RuntimeView).
+ All of them have pros and cons to take in consideration. In particular:
-
+
Standard views:
+Pros:
-
+
- They work out-of-the-box and don't require any dedicated data structure. +
- Creating and destroying them isn't expensive at all because they don't have any type of initialization. +
- They are the best tool for iterating entities for a single component. +
- They are the best tool for iterating entities for multiple components when one of the components is assigned to a significantly low number of entities. +
- They don't affect any other operations of the registry. +
Cons:
-
+
- Their performance tend to degenerate when the number of components to iterate grows up and the most of the entities have all of them. +
+Persistent views:
+Pros:
-
+
- Once prepared, creating and destroying them isn't expensive at all because they don't have any type of initialization. +
- They are the best tool for iterating entities for multiple components when most entities have them all. +
Cons:
-
+
- They have dedicated data structures and thus affect the memory usage to a minimal extent. +
- If not previously prepared, the first time they are used they go through an initialization step that could take a while. +
- They affect to a minimum the creation and destruction of entities and components. In other terms: the more persistent views there will be, the less performing will be creating and destroying entities and components. +
+Raw views:
+Pros:
-
+
- They work out-of-the-box and don't require any dedicated data structure. +
- Creating and destroying them isn't expensive at all because they don't have any type of initialization. +
- They are the best tool for iterating components when it is not necessary to know which entities they belong to. +
- They don't affect any other operations of the registry. +
Cons:
-
+
- They can be used to iterate only one type of component at a time. +
- They don't return the entity to which a component belongs to the caller. +
+Runtime views:
+Pros:
-
+
- Their lists of components are defined at runtime and not at compile-time. +
- Creating and destroying them isn't expensive at all because they don't have any type of initialization. +
- They are the best tool for things like plugin systems and mods in general. +
- They don't affect any other operations of the registry. +
Cons:
-
+
- Their performances are definitely lower than those of all the other views, although they are still usable and sufficient for most of the purposes. +
+
To sum up and as a rule of thumb:
+-
+
- Use a raw view to iterate components only (no entities) for a given type. +
- Use a standard view to iterate entities and components for a single type. +
- Use a standard view to iterate entities and components for multiple types when the number of types is low. Standard views are really optimized and persistent views won't add much in this case. +
- Use a standard view to iterate entities and components for multiple types when a significantly low number of entities have one of the components. +
- Use a standard view in all those cases where a persistent view would give a boost to performance but the iteration isn't performed frequently. +
- Prepare and use a persistent view when you want to iterate only entities for multiple components. +
- Prepare and use a persistent view when you want to iterate entities for multiple components and each component is assigned to a great number of entities but the intersection between the sets of entities is small. +
- Prepare and use a persistent view in all the cases where a standard view wouldn't fit well otherwise. +
- Finally, in case you don't know at compile-time what are the components to use, choose a runtime view and set them during execution. +
To easily iterate entities and components, all the views offer the common begin and end member functions that allow users to use a view in a typical range-for loop. Almost all the views offer also a more functional each member function that accepts a callback for convenience.
+ Continue reading for more details or refer to the inline documentation.
+Standard View
+A standard view behaves differently if it's constructed for a single component or if it has been requested to iterate multiple components. Even the API is different in the two cases.
+ All that they share is the way they are created by means of a registry:
For all that remains, it's worth discussing them separately.
+
+Single component standard view
+Single component standard views are specialized in order to give a boost in terms of performance in all the situation. This kind of views can access the underlying data structures directly and avoid superfluous checks.
+ They offer a bunch of functionalities to get the number of entities they are going to return and a raw access to the entity list as well as to the component list. It's also possible to ask a view if it contains a given entity.
+ Refer to the inline documentation for all the details.
There is no need to store views around for they are extremely cheap to construct, even though they can be copied without problems and reused freely. In fact, they return newly created and correctly initialized iterators whenever begin or end are invoked.
+ To iterate a single component standard view, either use it in a range-for loop:
Or rely on the each member function to iterate entities and get all their components at once:
The each member function is highly optimized. Unless users want to iterate only entities, using each should be the preferred approach.
Note: prefer the get member function of a view instead of the get member function template of a registry during iterations, if possible. However, keep in mind that it works only with the components of the view itself.
+Multi component standard view
+Multi component standard views iterate entities that have at least all the given components in their bags. During construction, these views look at the number of entities available for each component and pick up a reference to the smallest set of candidates in order to speed up iterations.
+ They offer fewer functionalities than their companion views for single component. In particular, a multi component standard view exposes utility functions to get the estimated number of entities it is going to return and to know whether it's empty or not. It's also possible to ask a view if it contains a given entity.
+ Refer to the inline documentation for all the details.
There is no need to store views around for they are extremely cheap to construct, even though they can be copied without problems and reused freely. In fact, they return newly created and correctly initialized iterators whenever begin or end are invoked.
+ To iterate a multi component standard view, either use it in a range-for loop:
Or rely on the each member function to iterate entities and get all their components at once:
The each member function is highly optimized. Unless users want to iterate only entities or get only some of the components, using each should be the preferred approach.
Note: prefer the get member function of a view instead of the get member function template of a registry during iterations, if possible. However, keep in mind that it works only with the components of the view itself.
+Persistent View
+A persistent view returns all the entities and only the entities that have at least the given components. Moreover, it's guaranteed that the entity list is tightly packed in memory for fast iterations.
+ In general, persistent views don't stay true to the order of any set of components unless users explicitly sort them.
Persistent views can be used only to iterate multiple components. To create this kind of views, the tag persistent_t must also be used in order to disambiguate overloads of the view member function:
There is no need to store views around for they are extremely cheap to construct, even though they can be copied without problems and reused freely. In fact, they return newly created and correctly initialized iterators whenever begin or end are invoked.
+ That being said, persistent views perform an initialization step the very first time they are constructed and this could be quite costly. To avoid it, consider asking to the registry to prepare them when no entities have been created yet:
If the registry is empty, preparation is extremely fast. Moreover the prepare member function template is idempotent. Feel free to invoke it even more than once: if the view has been already prepared before, the function returns immediately and does nothing.
A persistent view offers a bunch of functionalities to get the number of entities it's going to return, a raw access to the entity list and the possibility to sort the underlying data structures according to the order of one of the components for which it has been constructed. It's also possible to ask a view if it contains a given entity.
+ Refer to the inline documentation for all the details.
To iterate a persistent view, either use it in a range-for loop:
+Or rely on the each member function to iterate entities and get all their components at once:
Performance are more or less the same. The best approach depends mainly on whether all the components have to be accessed or not.
+Note: prefer the get member function of a view instead of the get member function template of a registry during iterations, if possible. However, keep in mind that it works only with the components of the view itself.
+Raw View
+Raw views return all the components of a given type. This kind of views can access components directly and avoid extra indirections like when components are accessed via an entity identifier.
+ They offer a bunch of functionalities to get the number of instances they are going to return and a raw access to the entity list as well as to the component list.
+ Refer to the inline documentation for all the details.
Raw views can be used only to iterate components for a single type. To create this kind of views, the tag raw_t must also be used in order to disambiguate overloads of the view member function:
There is no need to store views around for they are extremely cheap to construct, even though they can be copied without problems and reused freely. In fact, they return newly created and correctly initialized iterators whenever begin or end are invoked.
+ To iterate a raw view, use it in a range-for loop:
Or rely on the each member function:
Performance are exactly the same in both cases.
+Note: raw views don't have a get member function for obvious reasons.
+Runtime View
+Runtime views iterate entities that have at least all the given components in their bags. During construction, these views look at the number of entities available for each component and pick up a reference to the smallest set of candidates in order to speed up iterations.
+ They offer more or less the same functionalities of a multi component standard view. However, they don't expose a get member function and users should refer to the registry that generated the view to access components. In particular, a runtime view exposes utility functions to get the estimated number of entities it is going to return and to know whether it's empty or not. It's also possible to ask a view if it contains a given entity.
+ Refer to the inline documentation for all the details.
Runtime view are extremely cheap to construct and should not be stored around in any case. They should be used immediately after creation and then they should be thrown away. The reasons for this go far beyond the scope of this document.
+ To iterate a runtime view, either use it in a range-for loop:
Or rely on the each member function to iterate entities:
Performance are exactly the same in both cases.
+Note: runtime views are meant for all those cases where users don't know at compile-time what components to use to iterate entities. This is particularly well suited to plugin systems and mods in general. Where possible, don't use runtime views, as their performance are slightly inferior to those of the other views.
++Give me everything
+Views are narrow windows on the entire list of entities. They work by filtering entities according to their components.
+ In some cases there may be the need to iterate all the entities still in use regardless of their components. The registry offers a specific member function to do that:
It returns to the caller all the entities that are still in use by means of the given function.
+ As a rule of thumb, consider using a view if the goal is to iterate entities that have a determinate set of components. A view is usually much faster than combining this function with a bunch of custom tests.
+ In all the other cases, this is the way to go.
There exists also another member function to use to retrieve orphans. An orphan is an entity that is still in use and has neither assigned components nor tags.
+ The signature of the function is the same of each:
To test the orphanity of a single entity, use the member function orphan instead. It accepts a valid entity identifer as an argument and returns true in case the entity is an orphan, false otherwise.
In general, all these functions can result in poor performance.
+ each is fairly slow because of some checks it performs on each and every entity. For similar reasons, orphans can be even slower. Both functions should not be used frequently to avoid the risk of a performance hit.
+Iterations: what is allowed and what is not
+Most of the ECS available out there have some annoying limitations (at least from my point of view): entities and components cannot be created nor destroyed during iterations.
+ EnTT partially solves the problem with a few limitations:
-
+
- Creating entities and components is allowed during iterations. +
- Deleting an entity or removing its components is allowed during iterations if it's the one currently returned by the view. For all the other entities, destroying them or removing their components isn't allowed and it can result in undefined behavior. +
Iterators are invalidated and the behavior is undefined if an entity is modified or destroyed and it's not the one currently returned by the view nor a newly created one.
+ To work around it, possible approaches are:
-
+
- Store aside the entities and the components to be removed and perform the operations at the end of the iteration. +
- Mark entities and components with a proper tag component that indicates they must be purged, then perform a second iteration to clean them up one by one. +
A notable side effect of this feature is that the number of required allocations is further reduced in most of the cases.
++Multithreading
+In general, the entire registry isn't thread safe as it is. Thread safety isn't something that users should want out of the box for several reasons. Just to mention one of them: performance.
+ Views and consequently the approach adopted by EnTT are the great exception to the rule. It's true that views and thus their iterators aren't thread safe by themselves. Because of this users shouldn't try to iterate a set of components and modify the same set concurrently. However:
-
+
- As long as a thread iterates the entities that have the component
Xor assign and removes that component from a set of entities, another thread can safely do the same with componentsYandZand everything will work like a charm. As a trivial example, users can freely execute the rendering system and iterate the renderable entities while updating a physic component concurrently on a separate thread.
+ - Similarly, a single set of components can be iterated by multiple threads as long as the components are neither assigned nor removed in the meantime. In other words, a hypothetical movement system can start multiple threads, each of which will access the components that carry information about velocity and position for its entities. +
This kind of entity-component systems can be used in single threaded applications as well as along with async stuff or multiple threads. Moreover, typical thread based models for ECS don't require a fully thread safe registry to work. Actually, users can reach the goal with the registry as it is while working with most of the common models.
+Because of the few reasons mentioned above and many others not mentioned, users are completely responsible for synchronization whether required. On the other hand, they could get away with it without having to resort to particular expedients.
++Generated by +
+ 1.8.13
+
+
+
diff --git a/cache_8hpp_source.html b/cache_8hpp_source.html
index 0c28e23d4..d81aec370 100644
--- a/cache_8hpp_source.html
+++ b/cache_8hpp_source.html
@@ -22,7 +22,7 @@
|
+ EnTT
+ 2.7.3
+
+ |
+
#include <attachee.hpp>
Detailed Description
+template<typename...>
+class entt::Attachee<... >
+
+
+Primary template isn't defined on purpose. All the specializations give a compile-time error, but for a few reasonable cases.
+ +Definition at line 22 of file attachee.hpp.
+The documentation for this class was generated from the following file:
-
+
- src/entt/entity/attachee.hpp +
+Generated by +
+ 1.8.13
+
+
+
diff --git a/classentt_1_1Attachee_3_01Entity_00_01Type_01_4-members.html b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4-members.html
new file mode 100644
index 000000000..535a49068
--- /dev/null
+++ b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4-members.html
@@ -0,0 +1,95 @@
+
+
+
+
+
+
+
+|
+ EnTT
+ 2.7.3
+
+ |
+
This is the complete list of members for entt::Attachee< Entity, Type >, including all inherited members.
+| Attachee() ENTT_NOEXCEPT=default | entt::Attachee< Entity, Type > | |
| Attachee(const Attachee &)=delete | entt::Attachee< Entity, Type > | |
| Attachee(Attachee &&)=delete | entt::Attachee< Entity, Type > | |
| construct(entity_type entity, Args &&... args) ENTT_NOEXCEPT | entt::Attachee< Entity, Type > | inline |
| entt::Attachee< Entity >::construct(const entity_type entity) ENTT_NOEXCEPT | entt::Attachee< Entity > | inline |
| destroy() ENTT_NOEXCEPT override | entt::Attachee< Entity, Type > | inlinevirtual |
| entity_type typedef | entt::Attachee< Entity, Type > | |
| get() const ENTT_NOEXCEPT | entt::Attachee< Entity, Type > | inline |
| get() ENTT_NOEXCEPT | entt::Attachee< Entity, Type > | inline |
| move(const entity_type entity) ENTT_NOEXCEPT | entt::Attachee< Entity, Type > | inline |
| object_type typedef | entt::Attachee< Entity, Type > | |
| operator=(const Attachee &)=delete | entt::Attachee< Entity, Type > | |
| operator=(Attachee &&)=delete | entt::Attachee< Entity, Type > | |
| ~Attachee() | entt::Attachee< Entity, Type > | inlinevirtual |
+Generated by +
+ 1.8.13
+
+
+
diff --git a/classentt_1_1Attachee_3_01Entity_00_01Type_01_4.html b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4.html
new file mode 100644
index 000000000..f865cf463
--- /dev/null
+++ b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4.html
@@ -0,0 +1,472 @@
+
+
+
+
+
+
+
+|
+ EnTT
+ 2.7.3
+
+ |
+
Extended attachee implementation. + More...
+ +#include <attachee.hpp>
+Public Types | |
| +using | object_type = Type |
| Type of the object associated to the attachee. | |
| +using | entity_type = typename underlying_type::entity_type |
| Underlying entity identifier. | |
 Public Types inherited from entt::Attachee< Entity > | |
| +using | entity_type = Entity |
| Underlying entity identifier. | |
+Public Member Functions | |
| + | Attachee () ENTT_NOEXCEPT=default |
| Default constructor. | |
| + | Attachee (const Attachee &)=delete |
| Copying an attachee isn't allowed. | |
| + | Attachee (Attachee &&)=delete |
| Moving an attachee isn't allowed. | |
| Attachee & | operator= (const Attachee &)=delete |
| Copying an attachee isn't allowed. More... | |
| Attachee & | operator= (Attachee &&)=delete |
| Moving an attachee isn't allowed. More... | |
| + | ~Attachee () |
| Default destructor. | |
| const Type & | get () const ENTT_NOEXCEPT |
| Returns the object associated to an attachee. More... | |
| Type & | get () ENTT_NOEXCEPT |
| Returns the object associated to an attachee. More... | |
| template<typename... Args> | |
| Type & | construct (entity_type entity, Args &&... args) ENTT_NOEXCEPT |
| Assigns an entity to an attachee and constructs its object. More... | |
| void | destroy () ENTT_NOEXCEPT override |
| Removes an entity from an attachee and destroies its object. More... | |
| void | move (const entity_type entity) ENTT_NOEXCEPT |
| Changes the owner of an attachee. More... | |
| Public Member Functions inherited from entt::Attachee< Entity > | |
| + | Attachee () ENTT_NOEXCEPT |
| Default constructor. | |
| + | Attachee (const Attachee &)=default |
| Default copy constructor. | |
| + | Attachee (Attachee &&)=default |
| Default move constructor. | |
| Attachee & | operator= (const Attachee &)=default |
| Default copy assignment operator. More... | |
| Attachee & | operator= (Attachee &&)=default |
| Default move assignment operator. More... | |
| entity_type | get () const ENTT_NOEXCEPT |
| Returns the owner of an attachee. More... | |
| void | construct (const entity_type entity) ENTT_NOEXCEPT |
| Assigns an entity to an attachee. More... | |
Detailed Description
+template<typename Entity, typename Type>
+class entt::Attachee< Entity, Type >
+
+Extended attachee implementation.
+This specialization of an attachee associates an object to an entity. The main purpose of this class is to use attachees to store tags in a Registry. It guarantees fast access both to the element and to the entity.
+- See also
- Attachee<Entity>
- Template Parameters
-
+
+
+Entity A valid entity type (see entt_traits for more details). Type Type of object assigned to the entity.
+
Definition at line 112 of file attachee.hpp.
+Member Function Documentation
+ +◆ construct()
+ +
+
|
+ +inline | +
Assigns an entity to an attachee and constructs its object.
+- Warning
- Attempting to assigns an entity to an attachee that already has an owner results in undefined behavior.
+ An assertion will abort the execution at runtime in debug mode in case the attachee already has an owner.
- Template Parameters
-
+
+
+Args Types of arguments to use to construct the object.
+
- Parameters
-
+
+
+entity A valid entity identifier. args Parameters to use to construct an object for the entity.
+
- Returns
- The object associated to the attachee.
Definition at line 185 of file attachee.hpp.
+ +◆ destroy()
+ +
+
|
+ +inlineoverridevirtual | +
Removes an entity from an attachee and destroies its object.
+- Warning
- Attempting to free an empty attachee results in undefined behavior.
+ An assertion will abort the execution at runtime in debug mode if the attachee is already empty.
Reimplemented from entt::Attachee< Entity >.
+ +Definition at line 199 of file attachee.hpp.
+ +◆ get() [1/2]
+ +
+
|
+ +inline | +
Returns the object associated to an attachee.
+- Warning
- Attempting to query an empty attachee results in undefined behavior.
+ An assertion will abort the execution at runtime in debug mode if the attachee is empty.
- Returns
- The object associated to the attachee.
Definition at line 151 of file attachee.hpp.
+ +◆ get() [2/2]
+ +
+
|
+ +inline | +
Returns the object associated to an attachee.
+- Warning
- Attempting to query an empty attachee results in undefined behavior.
+ An assertion will abort the execution at runtime in debug mode if the attachee is empty.
- Returns
- The object associated to the attachee.
Definition at line 166 of file attachee.hpp.
+ +◆ move()
+ +
+
|
+ +inline | +
Changes the owner of an attachee.
+The ownership of the attachee is transferred from one entity to another.
+- Warning
- Attempting to transfer the ownership of an attachee that hasn't an owner results in undefined behavior.
+ An assertion will abort the execution at runtime in debug mode in case the attachee hasn't an owner yet.
- Parameters
-
+
+
+entity A valid entity identifier.
+
Definition at line 217 of file attachee.hpp.
+ +◆ operator=() [1/2]
+ +
+
|
+ +delete | +
Copying an attachee isn't allowed.
+- Returns
- This attachee.
◆ operator=() [2/2]
+ +
+
|
+ +delete | +
Moving an attachee isn't allowed.
+- Returns
- This attachee.
The documentation for this class was generated from the following file:
-
+
- src/entt/entity/attachee.hpp +
+Generated by +
+ 1.8.13
+
+
+
diff --git a/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__coll__graph.map b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__coll__graph.map
new file mode 100644
index 000000000..d082ee3e2
--- /dev/null
+++ b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__coll__graph.map
@@ -0,0 +1,3 @@
+
diff --git a/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__coll__graph.md5 b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__coll__graph.md5
new file mode 100644
index 000000000..8ad7cbd0c
--- /dev/null
+++ b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__coll__graph.md5
@@ -0,0 +1 @@
+2fd30cf67acfb8c69efa7822cb51703e
\ No newline at end of file
diff --git a/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__coll__graph.png b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__coll__graph.png
new file mode 100644
index 000000000..c94746720
Binary files /dev/null and b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__coll__graph.png differ
diff --git a/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__inherit__graph.map b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__inherit__graph.map
new file mode 100644
index 000000000..d082ee3e2
--- /dev/null
+++ b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__inherit__graph.map
@@ -0,0 +1,3 @@
+
diff --git a/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__inherit__graph.md5 b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__inherit__graph.md5
new file mode 100644
index 000000000..42196e769
--- /dev/null
+++ b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__inherit__graph.md5
@@ -0,0 +1 @@
+cd0c4f7a89b236495fb5929f2aa13015
\ No newline at end of file
diff --git a/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__inherit__graph.png b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__inherit__graph.png
new file mode 100644
index 000000000..c94746720
Binary files /dev/null and b/classentt_1_1Attachee_3_01Entity_00_01Type_01_4__inherit__graph.png differ
diff --git a/classentt_1_1Attachee_3_01Entity_01_4-members.html b/classentt_1_1Attachee_3_01Entity_01_4-members.html
new file mode 100644
index 000000000..519157fd7
--- /dev/null
+++ b/classentt_1_1Attachee_3_01Entity_01_4-members.html
@@ -0,0 +1,91 @@
+
+
+
+
+
+
+
+|
+ EnTT
+ 2.7.3
+
+ |
+
This is the complete list of members for entt::Attachee< Entity >, including all inherited members.
+| Attachee() ENTT_NOEXCEPT | entt::Attachee< Entity > | inline |
| Attachee(const Attachee &)=default | entt::Attachee< Entity > | |
| Attachee(Attachee &&)=default | entt::Attachee< Entity > | |
| construct(const entity_type entity) ENTT_NOEXCEPT | entt::Attachee< Entity > | inline |
| destroy() ENTT_NOEXCEPT | entt::Attachee< Entity > | inlinevirtual |
| entity_type typedef | entt::Attachee< Entity > | |
| get() const ENTT_NOEXCEPT | entt::Attachee< Entity > | inline |
| operator=(const Attachee &)=default | entt::Attachee< Entity > | |
| operator=(Attachee &&)=default | entt::Attachee< Entity > | |
| ~Attachee() ENTT_NOEXCEPT=default | entt::Attachee< Entity > | virtual |
+Generated by +
+ 1.8.13
+
+
+
diff --git a/classentt_1_1Attachee_3_01Entity_01_4.html b/classentt_1_1Attachee_3_01Entity_01_4.html
new file mode 100644
index 000000000..741967c57
--- /dev/null
+++ b/classentt_1_1Attachee_3_01Entity_01_4.html
@@ -0,0 +1,324 @@
+
+
+
+
+
+
+
+|
+ EnTT
+ 2.7.3
+
+ |
+
Basic attachee implementation. + More...
+ +#include <attachee.hpp>
+Public Types | |
| +using | entity_type = Entity |
| Underlying entity identifier. | |
+Public Member Functions | |
| + | Attachee () ENTT_NOEXCEPT |
| Default constructor. | |
| + | Attachee (const Attachee &)=default |
| Default copy constructor. | |
| + | Attachee (Attachee &&)=default |
| Default move constructor. | |
| Attachee & | operator= (const Attachee &)=default |
| Default copy assignment operator. More... | |
| Attachee & | operator= (Attachee &&)=default |
| Default move assignment operator. More... | |
| +virtual | ~Attachee () ENTT_NOEXCEPT=default |
| Default destructor. | |
| entity_type | get () const ENTT_NOEXCEPT |
| Returns the owner of an attachee. More... | |
| void | construct (const entity_type entity) ENTT_NOEXCEPT |
| Assigns an entity to an attachee. More... | |
| virtual void | destroy () ENTT_NOEXCEPT |
| Removes an entity from an attachee. More... | |
Detailed Description
+template<typename Entity>
+class entt::Attachee< Entity >
+
+Basic attachee implementation.
+Convenience data structure used to store single instance components.
+- Template Parameters
-
+
+
+Entity A valid entity type (see entt_traits for more details).
+
Definition at line 33 of file attachee.hpp.
+Member Function Documentation
+ +◆ construct()
+ +
+
|
+ +inline | +
Assigns an entity to an attachee.
+- Warning
- Attempting to assigns an entity to an attachee that already has an owner results in undefined behavior.
+ An assertion will abort the execution at runtime in debug mode in case the attachee already has an owner.
- Parameters
-
+
+
+entity A valid entity identifier.
+
Definition at line 76 of file attachee.hpp.
+ +◆ destroy()
+ +
+
|
+ +inlinevirtual | +
Removes an entity from an attachee.
+- Warning
- Attempting to free an empty attachee results in undefined behavior.
+ An assertion will abort the execution at runtime in debug mode if the attachee is already empty.
Reimplemented in entt::Attachee< Entity, Type >.
+ +Definition at line 89 of file attachee.hpp.
+ +◆ get()
+ +
+
|
+ +inline | +
Returns the owner of an attachee.
+- Returns
- A valid entity identifier if an owner exists, the null entity identifier otherwise.
Definition at line 61 of file attachee.hpp.
+ +◆ operator=() [1/2]
+ +
+
|
+ +default | +
Default copy assignment operator.
+- Returns
- This attachee.
◆ operator=() [2/2]
+ +
+
|
+ +default | +
Default move assignment operator.
+- Returns
- This attachee.
The documentation for this class was generated from the following file:
-
+
- src/entt/entity/attachee.hpp +
+Generated by +
+ 1.8.13
+
+
+
diff --git a/classentt_1_1Attachee_3_01Entity_01_4__inherit__graph.map b/classentt_1_1Attachee_3_01Entity_01_4__inherit__graph.map
new file mode 100644
index 000000000..ef4fa59fd
--- /dev/null
+++ b/classentt_1_1Attachee_3_01Entity_01_4__inherit__graph.map
@@ -0,0 +1,3 @@
+
diff --git a/classentt_1_1Attachee_3_01Entity_01_4__inherit__graph.md5 b/classentt_1_1Attachee_3_01Entity_01_4__inherit__graph.md5
new file mode 100644
index 000000000..a89cd2b56
--- /dev/null
+++ b/classentt_1_1Attachee_3_01Entity_01_4__inherit__graph.md5
@@ -0,0 +1 @@
+8c21d26f3e6d0119d1531c2ad74b3eaf
\ No newline at end of file
diff --git a/classentt_1_1Attachee_3_01Entity_01_4__inherit__graph.png b/classentt_1_1Attachee_3_01Entity_01_4__inherit__graph.png
new file mode 100644
index 000000000..67ca68fa0
Binary files /dev/null and b/classentt_1_1Attachee_3_01Entity_01_4__inherit__graph.png differ
diff --git a/classentt_1_1ContinuousLoader-members.html b/classentt_1_1ContinuousLoader-members.html
index 972d2f3b7..53c15591f 100644
--- a/classentt_1_1ContinuousLoader-members.html
+++ b/classentt_1_1ContinuousLoader-members.html
@@ -22,7 +22,7 @@
Definition at line 430 of file snapshot.hpp.
+Definition at line 434 of file snapshot.hpp.
-
