1359 lines
192 KiB
HTML
1359 lines
192 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
|
<meta name="generator" content="Doxygen 1.13.2"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>EnTT: Crash Course: entity-component system</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<script type="text/javascript" src="clipboard.js"></script>
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="resize.js"></script>
|
|
<script type="text/javascript" src="cookie.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr id="projectrow">
|
|
<td id="projectalign">
|
|
<div id="projectname">EnTT<span id="projectnumber"> 3.15.0</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.13.2 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
/* @license-end */
|
|
</script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function() { codefold.init(0); });
|
|
/* @license-end */
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search',false);
|
|
$(function() { init_search(); });
|
|
});
|
|
/* @license-end */
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function(){ initResizable(false); });
|
|
/* @license-end */
|
|
</script>
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<div id="MSearchResults">
|
|
<div class="SRPage">
|
|
<div id="SRIndex">
|
|
<div id="SRResults"></div>
|
|
<div class="SRStatus" id="Loading">Loading...</div>
|
|
<div class="SRStatus" id="Searching">Searching...</div>
|
|
<div class="SRStatus" id="NoMatches">No Matches</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</div><!-- top -->
|
|
<div id="doc-content">
|
|
<div><div class="header">
|
|
<div class="headertitle"><div class="title">Crash Course: entity-component system</div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p><a class="anchor" id="crash-course-entity-component-system"></a></p>
|
|
<h1><a class="anchor" id="table-of-contents-3"></a>
|
|
Table of Contents</h1>
|
|
<ul>
|
|
<li><a class="el" href="md_docs_2md_2config.html#introduction">Introduction</a></li>
|
|
<li><a class="el" href="#design-decisions">Design decisions</a><ul>
|
|
<li><a class="el" href="#type-less-and-bitset-free">Type-less and bitset-free</a></li>
|
|
<li><a class="el" href="#build-your-own">Build your own</a></li>
|
|
<li><a class="el" href="#pay-per-use">Pay per use</a></li>
|
|
<li><a class="el" href="#all-or-nothing">All or nothing</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#vademecum">Vademecum</a></li>
|
|
<li><a class="el" href="#the-registry-the-entity-and-the-component">The Registry, the Entity and the Component</a><ul>
|
|
<li><a class="el" href="#observe-changes">Observe changes</a><ul>
|
|
<li><a class="el" href="#entity-lifecycle">Entity lifecycle</a></li>
|
|
<li><a class="el" href="#listeners-disconnection">Listeners disconnection</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#they-call-me-reactive-storage">They call me reactive storage</a></li>
|
|
<li><a class="el" href="#sorting-is-it-possible">Sorting: is it possible?</a></li>
|
|
<li><a class="el" href="#helpers">Helpers</a><ul>
|
|
<li><a class="el" href="#null-entity">Null entity</a></li>
|
|
<li><a class="el" href="#tombstone">Tombstone</a></li>
|
|
<li><a class="el" href="#to-entity">To entity</a></li>
|
|
<li><a class="el" href="#dependencies">Dependencies</a></li>
|
|
<li><a class="el" href="#invoke">Invoke</a></li>
|
|
<li><a class="el" href="#connection-helper">Connection helper</a></li>
|
|
<li><a class="el" href="#handle">Handle</a></li>
|
|
<li><a class="el" href="#organizer">Organizer</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#context-variables">Context variables</a><ul>
|
|
<li><a class="el" href="#aliased-properties">Aliased properties</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#snapshot-complete-vs-continuous">Snapshot: complete vs continuous</a><ul>
|
|
<li><a class="el" href="#snapshot-loader">Snapshot loader</a></li>
|
|
<li><a class="el" href="#continuous-loader">Continuous loader</a></li>
|
|
<li><a class="el" href="#archives">Archives</a></li>
|
|
<li><a class="el" href="#one-example-to-rule-them-all">One example to rule them all</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#storage">Storage</a><ul>
|
|
<li><a class="el" href="#component-traits">Component traits</a></li>
|
|
<li><a class="el" href="#empty-type-optimization">Empty type optimization</a></li>
|
|
<li><a class="el" href="#void-storage">Void storage</a></li>
|
|
<li><a class="el" href="#entity-storage">Entity storage</a><ul>
|
|
<li><a class="el" href="#reserved-identifiers">Reserved identifiers</a></li>
|
|
<li><a class="el" href="#one-of-a-kind-to-the-registry">One of a kind to the registry</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#pointer-stability">Pointer stability</a><ul>
|
|
<li><a class="el" href="#in-place-delete">In-place delete</a></li>
|
|
<li><a class="el" href="#hierarchies-and-the-like">Hierarchies and the like</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#meet-the-runtime">Meet the runtime</a><ul>
|
|
<li><a class="el" href="#a-base-class-to-rule-them-all">A base class to rule them all</a></li>
|
|
<li><a class="el" href="#beam-me-up-registry">Beam me up, registry</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#views-and-groups">Views and Groups</a><ul>
|
|
<li><a class="el" href="#views">Views</a><ul>
|
|
<li><a class="el" href="#create-once-reuse-many-times">Create once, reuse many times</a></li>
|
|
<li><a class="el" href="#exclude-only">Exclude-only</a></li>
|
|
<li><a class="el" href="#view-pack">View pack</a></li>
|
|
<li><a class="el" href="#iteration-order">Iteration order</a></li>
|
|
<li><a class="el" href="#runtime-views">Runtime views</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#groups">Groups</a><ul>
|
|
<li><a class="el" href="#full-owning-groups">Full-owning groups</a></li>
|
|
<li><a class="el" href="#partial-owning-groups">Partial-owning groups</a></li>
|
|
<li><a class="el" href="#non-owning-groups">Non-owning groups</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#types-const-non-const-and-all-in-between">Types: const, non-const and all in between</a></li>
|
|
<li><a class="el" href="#give-me-everything">Give me everything</a></li>
|
|
<li><a class="el" href="#what-is-allowed-and-what-is-not">What is allowed and what is not</a><ul>
|
|
<li><a class="el" href="#more-performance-more-constraints">More performance, more constraints</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#multithreading">Multithreading</a><ul>
|
|
<li><a class="el" href="md_docs_2md_2core.html#iterators">Iterators</a></li>
|
|
<li><a class="el" href="#const-registry">Const registry</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="#beyond-this-document">Beyond this document</a></li>
|
|
</ul>
|
|
<h1><a class="anchor" id="introduction-3"></a>
|
|
Introduction</h1>
|
|
<p><code>EnTT</code> offers a header-only, tiny and easy to use entity-component system module written in modern C++.<br />
|
|
The entity-component-system (also known as <em>ECS</em>) is an architectural pattern used mostly in game development.</p>
|
|
<h1><a class="anchor" id="design-decisions"></a>
|
|
Design decisions</h1>
|
|
<h2><a class="anchor" id="type-less-and-bitset-free"></a>
|
|
Type-less and bitset-free</h2>
|
|
<p>The library implements a sparse set based model that does not require users to specify the set of components neither at compile-time nor at runtime.<br />
|
|
This is why users can instantiate the core class simply like:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a> registry;</div>
|
|
<div class="ttc" id="anamespaceentt_html_ab8c1f492841aeafa5e75422af3f0cdc4"><div class="ttname"><a href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a></div><div class="ttdeci">basic_registry<> registry</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00095">fwd.hpp:95</a></div></div>
|
|
</div><!-- fragment --><p>In place of its more annoying and error-prone counterpart:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a><comp_0, comp_1, ..., comp_n> registry;</div>
|
|
</div><!-- fragment --><p>Furthermore, it is not necessary to announce the existence of a component type. When the time comes, just use it and that is all.</p>
|
|
<h2><a class="anchor" id="build-your-own"></a>
|
|
Build your own</h2>
|
|
<p>The ECS module (as well as the rest of the library) is designed as a set of containers that are used as needed, just like a vector or any other container. It does not attempt in any way to take over on the user codebase, nor to control its main loop or process scheduling.<br />
|
|
Unlike other more or less well known models, it also makes use of independent pools that are extended via <em>static mixins</em>. The built-in signal support is an example of this flexible design: defined as a mixin, it is easily disabled if not needed. Similarly, the storage class has a specialization that shows how everything is customizable down to the smallest detail.</p>
|
|
<h2><a class="anchor" id="pay-per-use"></a>
|
|
Pay per use</h2>
|
|
<p>Everything is designed around the principle that users only have to pay for what they want.</p>
|
|
<p>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. Even worse, some approaches tend to heavily affect other functionalities like the construction and destruction of components to favor iterations, even when it is not strictly required. In fact, slightly worse performance along non-critical paths are the right price to pay to reduce memory usage and have overall better performance.<br />
|
|
<code>EnTT</code> follows a completely different approach. It gets the best out from the basic data structures and gives users the possibility to pay more for higher performance where needed.</p>
|
|
<h2><a class="anchor" id="all-or-nothing"></a>
|
|
All or nothing</h2>
|
|
<p>As a rule of thumb, a <code>T **</code> pointer (or whatever a custom pool returns) is always available to directly access all the instances of a given component type <code>T</code>.<br />
|
|
This is one of the corner stones of the library. Many of the tools offered are designed around this need and give the possibility to get this information.</p>
|
|
<h1><a class="anchor" id="vademecum"></a>
|
|
Vademecum</h1>
|
|
<p>The <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code> type implements the concept of <em>entity identifier</em>. An entity (the <em>E</em> of an <em>ECS</em>) is an opaque element to use as-is. Inspecting it is not recommended since its format can change in future.<br />
|
|
Components (the <em>C</em> of an <em>ECS</em>) are of any type, without any constraints, not even that of being movable. No need to register them nor their types.<br />
|
|
Systems (the <em>S</em> of an <em>ECS</em>) are plain functions, functors, lambdas and so on. It is not required to announce them in any case and have no requirements.</p>
|
|
<p>The next sections go into detail on how to use the entity-component system part of the <code>EnTT</code> library.<br />
|
|
This module is likely larger than what is described below. For more details, please refer to the inline documentation.</p>
|
|
<h1><a class="anchor" id="the-registry-the-entity-and-the-component"></a>
|
|
The Registry, the Entity and the Component</h1>
|
|
<p>A registry stores and manages entities (or <em>identifiers</em>) and components.<br />
|
|
The class template <code>basic_registry</code> lets users decide what the preferred type to represent an entity is. Because <code>std::uint32_t</code> is large enough for almost any case, there also exists the enum class <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code> that <em>wraps</em> it and the alias <code><a class="el" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4" title="Alias declaration for the most common use case.">entt::registry</a></code> for <code><a class="el" href="classentt_1_1basic__registry.html" title="Fast and reliable entity-component system.">entt::basic_registry</a><<a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a>></code>.</p>
|
|
<p>Entities are represented by <em>entity identifiers</em>. An entity identifier contains information about the entity itself and its version.<br />
|
|
User defined identifiers are allowed as enum classes and class types that define an <code>entity_type</code> member of type <code>std::uint32_t</code> or <code>std::uint64_t</code>.</p>
|
|
<p>A registry is used both to construct and to destroy entities:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// constructs a naked entity with no components and returns its identifier</span></div>
|
|
<div class="line"><span class="keyword">auto</span> entity = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a4ab0e3ed31fb0c455c07d0541941108a">create</a>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// destroys an entity and all its components</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a4849d0fe9d6008431239c93c57551d10">destroy</a>(entity);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a4849d0fe9d6008431239c93c57551d10"><div class="ttname"><a href="classentt_1_1basic__registry.html#a4849d0fe9d6008431239c93c57551d10">entt::basic_registry::destroy</a></div><div class="ttdeci">version_type destroy(const entity_type entt)</div><div class="ttdoc">Destroys an entity and releases its identifier.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00540">registry.hpp:540</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a4ab0e3ed31fb0c455c07d0541941108a"><div class="ttname"><a href="classentt_1_1basic__registry.html#a4ab0e3ed31fb0c455c07d0541941108a">entt::basic_registry::create</a></div><div class="ttdeci">entity_type create()</div><div class="ttdoc">Creates a new entity or recycles a destroyed one.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00499">registry.hpp:499</a></div></div>
|
|
</div><!-- fragment --><p>The <code>create</code> member function also accepts a hint. Moreover, it has an overload that gets two iterators to use to generate many entities at once efficiently. Similarly, the <code>destroy</code> member function also works with a range of entities:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// destroys all the entities in a range</span></div>
|
|
<div class="line"><span class="keyword">auto</span> view = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a563374eb952f575470291d2a574176dc">view</a><a_component, another_component>();</div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a4849d0fe9d6008431239c93c57551d10">destroy</a>(view.begin(), view.end());</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a563374eb952f575470291d2a574176dc"><div class="ttname"><a href="classentt_1_1basic__registry.html#a563374eb952f575470291d2a574176dc">entt::basic_registry::view</a></div><div class="ttdeci">basic_view< get_t< storage_for_type< const Type >, storage_for_type< const Other >... >, exclude_t< storage_for_type< const Exclude >... > > view(exclude_t< Exclude... >=exclude_t{}) const</div><div class="ttdoc">Returns a view for the given elements.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l01063">registry.hpp:1063</a></div></div>
|
|
</div><!-- fragment --><p>In addition to offering an overload to force the version upon destruction.<br />
|
|
This function removes all components from an entity before releasing it. There also exists a <em>lighter</em> alternative that does not query component pools, for use with orphaned entities:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// releases an orphaned identifier</span></div>
|
|
<div class="line">registry.release(entity);</div>
|
|
</div><!-- fragment --><p>As with the <code>destroy</code> function, also in this case entity ranges are supported and it is possible to force a <em>version</em>.</p>
|
|
<p>In both cases, when an identifier is released, the registry can freely reuse it internally. In particular, the version of an entity is increased (unless the overload that forces a version is used instead of the default one).<br />
|
|
Users can then <em>test</em> identifiers by means of a registry:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// returns true if the entity is still valid, false otherwise</span></div>
|
|
<div class="line"><span class="keywordtype">bool</span> b = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a40d41cd623d5bf7ad95d75aef5e70a65">valid</a>(entity);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// gets the actual version for the given entity</span></div>
|
|
<div class="line"><span class="keyword">auto</span> curr = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ad953b537b28f0f8d590e77b81faa1941">current</a>(entity);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a40d41cd623d5bf7ad95d75aef5e70a65"><div class="ttname"><a href="classentt_1_1basic__registry.html#a40d41cd623d5bf7ad95d75aef5e70a65">entt::basic_registry::valid</a></div><div class="ttdeci">bool valid(const entity_type entt) const</div><div class="ttdoc">Checks if an identifier refers to a valid entity.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00481">registry.hpp:481</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_ad953b537b28f0f8d590e77b81faa1941"><div class="ttname"><a href="classentt_1_1basic__registry.html#ad953b537b28f0f8d590e77b81faa1941">entt::basic_registry::current</a></div><div class="ttdeci">version_type current(const entity_type entt) const</div><div class="ttdoc">Returns the actual version for an identifier.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00491">registry.hpp:491</a></div></div>
|
|
</div><!-- fragment --><p>Or <em>inspect</em> them using some functions meant for parsing an identifier as-is, such as:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// gets the version contained in the entity identifier</span></div>
|
|
<div class="line"><span class="keyword">auto</span> version = <a class="code hl_function" href="namespaceentt.html#a4b7d8995ec3448ce5151309ef2281d33">entt::to_version</a>(entity);</div>
|
|
<div class="ttc" id="anamespaceentt_html_a4b7d8995ec3448ce5151309ef2281d33"><div class="ttname"><a href="namespaceentt.html#a4b7d8995ec3448ce5151309ef2281d33">entt::to_version</a></div><div class="ttdeci">constexpr entt_traits< Entity >::version_type to_version(const Entity value) noexcept</div><div class="ttdoc">Returns the version part once converted to the underlying type.</div><div class="ttdef"><b>Definition</b> <a href="entity_8hpp_source.html#l00199">entity.hpp:199</a></div></div>
|
|
</div><!-- fragment --><p>Components are assigned to or removed from entities at any time.<br />
|
|
The <code>emplace</code> member function template creates, initializes and assigns to an entity the given component. It accepts a variable number of arguments to use to construct the component itself:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#aa3cd5a28e32c30e5c69965c52781bf98">emplace</a><position>(entity, 0., 0.);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">auto</span> &vel = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#aa3cd5a28e32c30e5c69965c52781bf98">emplace</a><velocity>(entity);</div>
|
|
<div class="line">vel.dx = 0.;</div>
|
|
<div class="line">vel.dy = 0.;</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_aa3cd5a28e32c30e5c69965c52781bf98"><div class="ttname"><a href="classentt_1_1basic__registry.html#aa3cd5a28e32c30e5c69965c52781bf98">entt::basic_registry::emplace</a></div><div class="ttdeci">decltype(auto) emplace(const entity_type entt, Args &&...args)</div><div class="ttdoc">Assigns the given element to an entity.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00604">registry.hpp:604</a></div></div>
|
|
</div><!-- fragment --><p>The default storage <em>detects</em> aggregate types internally and exploits aggregate initialization when possible.<br />
|
|
Therefore, it is not strictly necessary to define a constructor for each type.</p>
|
|
<p>The <code>insert</code> member function works with <em>ranges</em> and is used to:</p>
|
|
<ul>
|
|
<li><p class="startli">Assign the same component to all entities at once when a type is specified as a template parameter or an instance is passed as an argument:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// default initialized type assigned by copy to all entities</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ae299b32827f0667903d8564e10ca6774">insert</a><position>(first, last);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// user-defined instance assigned by copy to all entities</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ae299b32827f0667903d8564e10ca6774">insert</a>(from, to, position{0., 0.});</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_ae299b32827f0667903d8564e10ca6774"><div class="ttname"><a href="classentt_1_1basic__registry.html#ae299b32827f0667903d8564e10ca6774">entt::basic_registry::insert</a></div><div class="ttdeci">void insert(It first, It last, const Type &value={})</div><div class="ttdoc">Assigns each entity in a range the given element.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00621">registry.hpp:621</a></div></div>
|
|
</div><!-- fragment --></li>
|
|
<li><p class="startli">Assign a set of components to the entities when a range is provided (the length of the range of components <b>must</b> be the same of that of entities):</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// first and last specify the range of entities, instances points to the first element of the range of components</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ae299b32827f0667903d8564e10ca6774">insert</a><position>(first, last, instances);</div>
|
|
</div><!-- fragment --></li>
|
|
</ul>
|
|
<p>If an entity already has the given component, the <code>replace</code> and <code>patch</code> member function templates are used to update it:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// replaces the component in-place</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a77c108caf74d8fcce9f3fb94906cd4db">patch</a><position>(entity, [](<span class="keyword">auto</span> &pos) { pos.x = pos.y = 0.; });</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// constructs a new instance from a list of arguments and replaces the component</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a1b4f1cccd495d17c550711fdc9606d4f">replace</a><position>(entity, 0., 0.);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a1b4f1cccd495d17c550711fdc9606d4f"><div class="ttname"><a href="classentt_1_1basic__registry.html#a1b4f1cccd495d17c550711fdc9606d4f">entt::basic_registry::replace</a></div><div class="ttdeci">decltype(auto) replace(const entity_type entt, Args &&...args)</div><div class="ttdoc">Replaces the given element for an entity.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00703">registry.hpp:703</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a77c108caf74d8fcce9f3fb94906cd4db"><div class="ttname"><a href="classentt_1_1basic__registry.html#a77c108caf74d8fcce9f3fb94906cd4db">entt::basic_registry::patch</a></div><div class="ttdeci">decltype(auto) patch(const entity_type entt, Func &&...func)</div><div class="ttdoc">Patches the given element for an entity.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00683">registry.hpp:683</a></div></div>
|
|
</div><!-- fragment --><p>When it is unknown whether an entity already owns an instance of a component, <code>emplace_or_replace</code> is the function to use instead:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a3ebfbe0d897e77cf0f24bc994a796b15">emplace_or_replace</a><position>(entity, 0., 0.);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a3ebfbe0d897e77cf0f24bc994a796b15"><div class="ttname"><a href="classentt_1_1basic__registry.html#a3ebfbe0d897e77cf0f24bc994a796b15">entt::basic_registry::emplace_or_replace</a></div><div class="ttdeci">decltype(auto) emplace_or_replace(const entity_type entt, Args &&...args)</div><div class="ttdoc">Assigns or replaces the given element for an entity.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00657">registry.hpp:657</a></div></div>
|
|
</div><!-- fragment --><p>This is a slightly faster alternative to the following snippet:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">if</span>(registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a463b15da6bfe18744e595c082ef70bac">all_of</a><velocity>(entity)) {</div>
|
|
<div class="line"> registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a1b4f1cccd495d17c550711fdc9606d4f">replace</a><velocity>(entity, 0., 0.);</div>
|
|
<div class="line">} <span class="keywordflow">else</span> {</div>
|
|
<div class="line"> registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#aa3cd5a28e32c30e5c69965c52781bf98">emplace</a><velocity>(entity, 0., 0.);</div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a463b15da6bfe18744e595c082ef70bac"><div class="ttname"><a href="classentt_1_1basic__registry.html#a463b15da6bfe18744e595c082ef70bac">entt::basic_registry::all_of</a></div><div class="ttdeci">bool all_of(const entity_type entt) const</div><div class="ttdoc">Check if an entity is part of all the given storage.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00852">registry.hpp:852</a></div></div>
|
|
</div><!-- fragment --><p>The <code>all_of</code> and <code>any_of</code> member functions may also be useful if in doubt about whether or not an entity has all the components in a set or any of them:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// true if entity has all the given components</span></div>
|
|
<div class="line"><span class="keywordtype">bool</span> all = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a463b15da6bfe18744e595c082ef70bac">all_of</a><position, velocity>(entity);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// true if entity has at least one of the given components</span></div>
|
|
<div class="line"><span class="keywordtype">bool</span> any = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a0bcc0d120d7bbe348242a1c3227af8fc">any_of</a><position, velocity>(entity);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a0bcc0d120d7bbe348242a1c3227af8fc"><div class="ttname"><a href="classentt_1_1basic__registry.html#a0bcc0d120d7bbe348242a1c3227af8fc">entt::basic_registry::any_of</a></div><div class="ttdeci">bool any_of(const entity_type entt) const</div><div class="ttdoc">Check if an entity is part of at least one given storage.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00869">registry.hpp:869</a></div></div>
|
|
</div><!-- fragment --><p>If the goal is to delete a component from an entity that owns it, the <code>erase</code> member function template is the way to go:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#afc89c98a7fdc0d6083b2ae23682bc4a9">erase</a><position>(entity);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_afc89c98a7fdc0d6083b2ae23682bc4a9"><div class="ttname"><a href="classentt_1_1basic__registry.html#afc89c98a7fdc0d6083b2ae23682bc4a9">entt::basic_registry::erase</a></div><div class="ttdeci">void erase(const entity_type entt)</div><div class="ttdoc">Erases the given elements from an entity.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00769">registry.hpp:769</a></div></div>
|
|
</div><!-- fragment --><p>When in doubt whether the entity owns the component, use the <code>remove</code> member function instead. It behaves similarly to <code>erase</code> but it drops the component if and only if it exists, otherwise it returns safely to the caller:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a7eb97ddee1a5ee98a722329fe39417ce">remove</a><position>(entity);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a7eb97ddee1a5ee98a722329fe39417ce"><div class="ttname"><a href="classentt_1_1basic__registry.html#a7eb97ddee1a5ee98a722329fe39417ce">entt::basic_registry::remove</a></div><div class="ttdeci">size_type remove(const entity_type entt)</div><div class="ttdoc">Removes the given elements from an entity.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00715">registry.hpp:715</a></div></div>
|
|
</div><!-- fragment --><p>The <code>clear</code> member function works similarly and is used to either:</p>
|
|
<ul>
|
|
<li><p class="startli">Erases all instances of the given components from the entities that own them:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a65ae6a29493a09a3c19e83748bae6a7e">clear</a><position>();</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a65ae6a29493a09a3c19e83748bae6a7e"><div class="ttname"><a href="classentt_1_1basic__registry.html#a65ae6a29493a09a3c19e83748bae6a7e">entt::basic_registry::clear</a></div><div class="ttdeci">void clear()</div><div class="ttdoc">Clears a whole registry or the pools for the given elements.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00960">registry.hpp:960</a></div></div>
|
|
</div><!-- fragment --></li>
|
|
<li><p class="startli">Or destroy all entities in a registry at once:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a65ae6a29493a09a3c19e83748bae6a7e">clear</a>();</div>
|
|
</div><!-- fragment --></li>
|
|
</ul>
|
|
<p>Finally, references to components are obtained simply as:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> &cregistry = registry;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// const and non-const reference</span></div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> &crenderable = cregistry.<a class="code hl_function" href="classentt_1_1basic__registry.html#abe347a879e04298df37c19b757f6ab08">get</a><renderable>(entity);</div>
|
|
<div class="line"><span class="keyword">auto</span> &renderable = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#abe347a879e04298df37c19b757f6ab08">get</a><renderable>(entity);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// const and non-const references</span></div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> [cpos, cvel] = cregistry.get<position, velocity>(entity);</div>
|
|
<div class="line"><span class="keyword">auto</span> [pos, vel] = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#abe347a879e04298df37c19b757f6ab08">get</a><position, velocity>(entity);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_abe347a879e04298df37c19b757f6ab08"><div class="ttname"><a href="classentt_1_1basic__registry.html#abe347a879e04298df37c19b757f6ab08">entt::basic_registry::get</a></div><div class="ttdeci">decltype(auto) get(const entity_type entt) const</div><div class="ttdoc">Returns references to the given elements for an entity.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00885">registry.hpp:885</a></div></div>
|
|
</div><!-- fragment --><p>If the existence of the component is not certain, <code>try_get</code> is the more suitable function instead.</p>
|
|
<h2><a class="anchor" id="observe-changes"></a>
|
|
Observe changes</h2>
|
|
<p>By default, each storage comes with a mixin that adds signal support to it.<br />
|
|
This allows for fancy things like dependencies and reactive systems.</p>
|
|
<p>The <code>on_construct</code> member function returns a <em>sink</em> (which is an object for connecting and disconnecting listeners) for those interested in notifications when a new instance of a given component type is created:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// connects a free function</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><position>().connect<&my_free_function>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// connects a member function</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><position>().connect<&my_class::member>(instance);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// disconnects a free function</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><position>().disconnect<&my_free_function>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// disconnects a member function</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><position>().disconnect<&my_class::member>(instance);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_ab68c1ba5692d30350d30121663203aea"><div class="ttname"><a href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">entt::basic_registry::on_construct</a></div><div class="ttdeci">auto on_construct(const id_type id=type_hash< Type >::value())</div><div class="ttdoc">Returns a sink object for the given element.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l01002">registry.hpp:1002</a></div></div>
|
|
</div><!-- fragment --><p>Similarly, <code>on_destroy</code> and <code>on_update</code> are used to receive notifications about the destruction and update of an instance, respectively.<br />
|
|
Because of how C++ works, listeners attached to <code>on_update</code> are only invoked following a call to <code>replace</code>, <code>emplace_or_replace</code> or <code>patch</code>.</p>
|
|
<p>Runtime pools are also supported by providing an identifier to the functions above:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><position>(<span class="stringliteral">"other"</span>_hs).connect<&my_free_function>();</div>
|
|
</div><!-- fragment --><p>Refer to the following sections for more information about runtime pools.<br />
|
|
In all cases, the function type of a listener is equivalent to the following:</p>
|
|
<div class="fragment"><div class="line">void(<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a> &, <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>);</div>
|
|
<div class="ttc" id="anamespaceentt_html_a0b54e231d069e8a231e14b223388808a"><div class="ttname"><a href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a></div><div class="ttdeci">entity</div><div class="ttdoc">Default entity identifier.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00014">fwd.hpp:14</a></div></div>
|
|
</div><!-- fragment --><p>All listeners are provided with the registry that triggered the notification and the involved entity. Note also that:</p>
|
|
<ul>
|
|
<li>Listeners for construction signals are invoked <b>after</b> components have been created.</li>
|
|
<li>Listeners designed to observe changes are invoked <b>after</b> components have been updated.</li>
|
|
<li>Listeners for destruction signals are invoked <b>before</b> components have been destroyed.</li>
|
|
</ul>
|
|
<p>There are also some limitations on what a listener can and cannot do:</p>
|
|
<ul>
|
|
<li>Connecting and disconnecting other functions from within the body of a listener should be avoided. It can lead to undefined behavior in some cases.</li>
|
|
<li>Removing the component from within the body of a listener that observes the construction or update of instances of a given type is not allowed.</li>
|
|
<li>Assigning and removing components 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.</li>
|
|
</ul>
|
|
<p>Please, refer to the documentation of the signal class to know about all the features it offers.<br />
|
|
There are many useful but less known functionalities that are not described here, such as the connection objects or the possibility to attach listeners with a list of parameters that is shorter than that of the signal itself.</p>
|
|
<h3><a class="anchor" id="entity-lifecycle"></a>
|
|
Entity lifecycle</h3>
|
|
<p>Observing entities is also possible. In this case, the user must use the entity type instead of the component type:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>>().connect<&my_listener>();</div>
|
|
</div><!-- fragment --><p>Since entity storage is unique within a registry, if a <em>name</em> is provided it is ignored and therefore discarded.<br />
|
|
As for the function signature, this is exactly the same as the components.</p>
|
|
<p>Entities support all types of signals: construct, destroy, and update. The latter is perhaps ambiguous as an entity is not truly <em>updated</em>. Rather, its identifier is created and finally released.<br />
|
|
Indeed, the update signal is meant to send <em>general notifications</em> regarding an entity. It can be triggered via the <code>patch</code> function, as is the case with components:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a77c108caf74d8fcce9f3fb94906cd4db">patch</a><<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>>(entity);</div>
|
|
</div><!-- fragment --><p>Destroying an entity and then updating the version of an identifier <b>does not</b> give rise to these types of signals under any circumstances instead.<br />
|
|
Finally, note that listeners that <em>observe</em> the destruction of an entity are invoked <b>after</b> all components have been removed, not <b>before</b>. This is because the entity would be invalidated before deleting its elements otherwise, making it difficult for the user to write component listeners.</p>
|
|
<h3><a class="anchor" id="listeners-disconnection"></a>
|
|
Listeners disconnection</h3>
|
|
<p>The destruction order of the storage classes and therefore the disconnection of the listeners is completely random.<br />
|
|
There are no guarantees today, and while the logic is easily discerned, it is not guaranteed that it will remain so in the future.</p>
|
|
<p>For example, a listener getting disconnected after a component is discarded as a result of pool destruction is most likely a recipe for problems.<br />
|
|
Rather, it is advisable to invoke the <code>clear</code> function of the registry before destroying it. This forces the deletion of all components and entities without ever discarding the pools.<br />
|
|
As a result, a listener that wants to access components, entities, or pools can safely do so against a still valid registry, while checking for the existence of the various elements as appropriate.</p>
|
|
<h2><a class="anchor" id="they-call-me-reactive-storage"></a>
|
|
They call me reactive storage</h2>
|
|
<p>Signals are the basic tools to construct reactive systems, even if they are not enough on their own. <code>EnTT</code> tries to take another step in that direction with its <em>reactive mixin</em>.<br />
|
|
In order to explain what reactive systems are, this is a slightly revised quote from the documentation of the library that first introduced this tool, <a href="https://github.com/sschmid/Entitas-CSharp">Entitas</a>:</p>
|
|
<blockquote class="doxtable">
|
|
<p>Imagine you have 100 fighting units on the battlefield, but only 10 of them changed their positions. Instead of using a normal system and updating all 100 entities depending on the position, you can use a reactive system which will only update the 10 changed units. So efficient. </p>
|
|
</blockquote>
|
|
<p>In <code>EnTT</code>, this means iterating over a reduced set of entities and components than what would otherwise be returned from a view or group.<br />
|
|
On these words, however, the similarities with the proposal of <code>Entitas</code> also end. The rules of the language and the design of the library obviously impose and allow different things.</p>
|
|
<p>A reactive mixin can be used on a standalone storage with any value type (perhaps using an alias to simplify its use):</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">using </span>reactive_storage = <a class="code hl_typedef" href="namespaceentt.html#a7d9d8ddc2e43b7cda372aa52cbcc2725">entt::reactive_mixin<entt::storage<void></a>>;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a> registry{};</div>
|
|
<div class="line">reactive_storage storage{};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e">storage</a>.<a class="code hl_function" href="classentt_1_1basic__sparse__set.html#a67b8e3f7cb0144bf663bcd6b9c6e131f">bind</a>(registry);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__sparse__set_html_a67b8e3f7cb0144bf663bcd6b9c6e131f"><div class="ttname"><a href="classentt_1_1basic__sparse__set.html#a67b8e3f7cb0144bf663bcd6b9c6e131f">entt::basic_sparse_set::bind</a></div><div class="ttdeci">void bind(Type &&value) noexcept</div><div class="ttdoc">Forwards variables to derived classes, if any.</div><div class="ttdef"><b>Definition</b> <a href="sparse__set_8hpp_source.html#l01095">sparse_set.hpp:1095</a></div></div>
|
|
<div class="ttc" id="anamespaceentt_html_a7d9d8ddc2e43b7cda372aa52cbcc2725"><div class="ttname"><a href="namespaceentt.html#a7d9d8ddc2e43b7cda372aa52cbcc2725">entt::reactive_mixin</a></div><div class="ttdeci">basic_reactive_mixin< Type, basic_registry< typename Type::entity_type, typename Type::base_type::allocator_type > > reactive_mixin</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00092">fwd.hpp:92</a></div></div>
|
|
<div class="ttc" id="anamespaceentt_html_aff8fd99fc1ff2432dcb0f6b017a9c60e"><div class="ttname"><a href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e">entt::storage</a></div><div class="ttdeci">basic_storage< Type > storage</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00078">fwd.hpp:78</a></div></div>
|
|
</div><!-- fragment --><p>In this case, it must be provided with a reference registry for subsequent operations.<br />
|
|
Alternatively, when using the value type provided by <code>EnTT</code>, it is also possible to create a reactive storage directly inside a registry:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a> registry{};</div>
|
|
<div class="line"><span class="keyword">auto</span> &storage = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a3ffe409b0f7201456b1c1d32c0850474">storage</a><<a class="code hl_struct" href="structentt_1_1reactive.html">entt::reactive</a>>(<span class="stringliteral">"observer"</span>_hs);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a3ffe409b0f7201456b1c1d32c0850474"><div class="ttname"><a href="classentt_1_1basic__registry.html#a3ffe409b0f7201456b1c1d32c0850474">entt::basic_registry::storage</a></div><div class="ttdeci">iterable storage() noexcept</div><div class="ttdoc">Returns an iterable object to use to visit a registry.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l00416">registry.hpp:416</a></div></div>
|
|
<div class="ttc" id="astructentt_1_1reactive_html"><div class="ttname"><a href="structentt_1_1reactive.html">entt::reactive</a></div><div class="ttdoc">Empty value type for reactive storage types.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00232">fwd.hpp:232</a></div></div>
|
|
</div><!-- fragment --><p>In the latter case, there is the advantage that, in the event of destruction of an entity, this storage is also automatically cleaned up.<br />
|
|
Also note that, unlike all other storage, these classes do not support signals by default (although they can be enabled if necessary).</p>
|
|
<p>Once it has been created and associated with a registry, the reactive mixin needs to be informed about what it should <em>observe</em>.<br />
|
|
Here the choice boils down to three main events affecting all elements (entities or components), namely creation, update or destruction:</p>
|
|
<div class="fragment"><div class="line">storage</div>
|
|
<div class="line"> <span class="comment">// observe position component construction</span></div>
|
|
<div class="line"> .on_construct<position>()</div>
|
|
<div class="line"> <span class="comment">// observe velocity component update</span></div>
|
|
<div class="line"> .on_update<velocity>()</div>
|
|
<div class="line"> <span class="comment">// observe renderable component destruction</span></div>
|
|
<div class="line"> .on_destroy<renderable>();</div>
|
|
</div><!-- fragment --><p>It goes without saying that it is possible to observe multiple events of the same type or of different types with the same storage.<br />
|
|
For example, to know which entities have been assigned or updated a component of a certain type:</p>
|
|
<div class="fragment"><div class="line">storage</div>
|
|
<div class="line"> .on_construct<my_type>()</div>
|
|
<div class="line"> .on_update<my_type>();</div>
|
|
</div><!-- fragment --><p>Note that all configurations are in <em>or</em> and never in <em>and</em>. Therefore, to track entities that have been assigned two different components, there are a couple of options:</p>
|
|
<ul>
|
|
<li><p class="startli">Create two reactive storage, then combine them in a view:</p>
|
|
<div class="fragment"><div class="line">first_storage.on_construct<position>();</div>
|
|
<div class="line">second_storage.on_construct<velocity>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> entity: <a class="code hl_class" href="classentt_1_1basic__view.html">entt::basic_view</a>{first_storage, second_storage}) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__view_html"><div class="ttname"><a href="classentt_1_1basic__view.html">entt::basic_view</a></div><div class="ttdoc">View implementation.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00047">fwd.hpp:47</a></div></div>
|
|
</div><!-- fragment --></li>
|
|
<li><p class="startli">Use a reactive storage with a non-<code>void</code> value type and a custom tracking function for the purpose:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">using </span>my_reactive_storage = <a class="code hl_typedef" href="namespaceentt.html#a7d9d8ddc2e43b7cda372aa52cbcc2725">entt::reactive_mixin<entt::storage<bool></a>>;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordtype">void</span> callback(my_reactive_storage &storage, <span class="keyword">const</span> <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a> &, <span class="keyword">const</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> entity) {</div>
|
|
<div class="line"> storage.<a class="code hl_function" href="classentt_1_1basic__sparse__set.html#a97b47cbaea3fc30442fa3e6366766c86">contains</a>(entity) ? (storage.<a class="code hl_function" href="classentt_1_1basic__storage.html#a3d5a1009a9e86a3bb051eaaf01864574">get</a>(entity) = <span class="keyword">true</span>) : storage.<a class="code hl_function" href="classentt_1_1basic__storage.html#ad53a7224b938b57f633b34af6d6c4621">emplace</a>(entity, <span class="keyword">false</span>);</div>
|
|
<div class="line">}</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line">my_reactive_storage storage{};</div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e">storage</a></div>
|
|
<div class="line"> .on_construct<position, &callback>()</div>
|
|
<div class="line"> .on_construct<velocity, &callback>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> [entity, both_were_added]: <a class="code hl_typedef" href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e">storage</a>.<a class="code hl_function" href="classentt_1_1basic__storage.html#acfe669358e8c68240dcc617c9d624d4c">each</a>()) {</div>
|
|
<div class="line"> <span class="keywordflow">if</span>(both_were_added) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line"> }</div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__sparse__set_html_a97b47cbaea3fc30442fa3e6366766c86"><div class="ttname"><a href="classentt_1_1basic__sparse__set.html#a97b47cbaea3fc30442fa3e6366766c86">entt::basic_sparse_set::contains</a></div><div class="ttdeci">bool contains(const entity_type entt) const noexcept</div><div class="ttdoc">Checks if a sparse set contains an entity.</div><div class="ttdef"><b>Definition</b> <a href="sparse__set_8hpp_source.html#l00721">sparse_set.hpp:721</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1basic__storage_html_a3d5a1009a9e86a3bb051eaaf01864574"><div class="ttname"><a href="classentt_1_1basic__storage.html#a3d5a1009a9e86a3bb051eaaf01864574">entt::basic_storage::get</a></div><div class="ttdeci">const value_type & get(const entity_type entt) const noexcept</div><div class="ttdoc">Returns the object assigned to an entity.</div><div class="ttdef"><b>Definition</b> <a href="storage_8hpp_source.html#l00648">storage.hpp:648</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1basic__storage_html_acfe669358e8c68240dcc617c9d624d4c"><div class="ttname"><a href="classentt_1_1basic__storage.html#acfe669358e8c68240dcc617c9d624d4c">entt::basic_storage::each</a></div><div class="ttdeci">iterable each() noexcept</div><div class="ttdoc">Returns an iterable object to use to visit a storage.</div><div class="ttdef"><b>Definition</b> <a href="storage_8hpp_source.html#l00762">storage.hpp:762</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1basic__storage_html_ad53a7224b938b57f633b34af6d6c4621"><div class="ttname"><a href="classentt_1_1basic__storage.html#ad53a7224b938b57f633b34af6d6c4621">entt::basic_storage::emplace</a></div><div class="ttdeci">value_type & emplace(const entity_type entt, Args &&...args)</div><div class="ttdoc">Assigns an entity to a storage and constructs its object.</div><div class="ttdef"><b>Definition</b> <a href="storage_8hpp_source.html#l00684">storage.hpp:684</a></div></div>
|
|
</div><!-- fragment --></li>
|
|
</ul>
|
|
<p>As highlighted in the last example, the reactive mixin tracks the entities that match the given conditions and saves them aside. However, this behavior can be changed.<br />
|
|
For example, it is possible to <em>capture</em> all and only the entities for which a certain component has been updated but only if a specific value is within a given range:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> callback(reactive_storage &storage, <span class="keyword">const</span> <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a> &registry, <span class="keyword">const</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> entity) {</div>
|
|
<div class="line"> storage.<a class="code hl_function" href="classentt_1_1basic__sparse__set.html#af02e5833d5edb2450303bd1c029213b8">remove</a>(entity);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">if</span>(<span class="keyword">const</span> <span class="keyword">auto</span> x = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#abe347a879e04298df37c19b757f6ab08">get</a><position>(entity).x; x >= min_x && x <= max_x) {</div>
|
|
<div class="line"> storage.<a class="code hl_function" href="classentt_1_1basic__storage.html#ad53a7224b938b57f633b34af6d6c4621">emplace</a>(entity);</div>
|
|
<div class="line"> }</div>
|
|
<div class="line">}</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ...</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e">storage</a>.on_update<position, &callback>();</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__sparse__set_html_af02e5833d5edb2450303bd1c029213b8"><div class="ttname"><a href="classentt_1_1basic__sparse__set.html#af02e5833d5edb2450303bd1c029213b8">entt::basic_sparse_set::remove</a></div><div class="ttdeci">bool remove(const entity_type entt)</div><div class="ttdoc">Removes an entity from a sparse set if it exists.</div><div class="ttdef"><b>Definition</b> <a href="sparse__set_8hpp_source.html#l00882">sparse_set.hpp:882</a></div></div>
|
|
</div><!-- fragment --><p>This makes reactive storage extremely flexible and usable in a large number of cases.<br />
|
|
Finally, once the entities of interest have been collected, it is possible to <em>visit</em> the storage like any other:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> entity: storage) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Wrapping it in a view and combining it with other views is another option:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> [entity, pos]: (<a class="code hl_namespace" href="namespaceentt.html">entt</a>:.basic_view{storage} | registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a563374eb952f575470291d2a574176dc">view</a><position>(<a class="code hl_variable" href="namespaceentt.html#a5b73210cef43c4db35ef8ce477cc38a6">entt::exclude<velocity></a>)).each()) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="anamespaceentt_html"><div class="ttname"><a href="namespaceentt.html">entt</a></div><div class="ttdoc">EnTT default namespace.</div><div class="ttdef"><b>Definition</b> <a href="dense__map_8hpp_source.html#l00022">dense_map.hpp:22</a></div></div>
|
|
<div class="ttc" id="anamespaceentt_html_a5b73210cef43c4db35ef8ce477cc38a6"><div class="ttname"><a href="namespaceentt.html#a5b73210cef43c4db35ef8ce477cc38a6">entt::exclude</a></div><div class="ttdeci">constexpr exclude_t< Type... > exclude</div><div class="ttdoc">Variable template for exclusion lists.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00150">fwd.hpp:150</a></div></div>
|
|
</div><!-- fragment --><p>In order to simplify this last use case, the reactive mixin also provides a specific function that returns a view of the storage already filtered according to the provided requirements:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> [entity, pos]: storage.view<position>(<a class="code hl_variable" href="namespaceentt.html#a5b73210cef43c4db35ef8ce477cc38a6">entt::exclude<velocity></a>).<a class="code hl_function" href="classentt_1_1basic__storage.html#acfe669358e8c68240dcc617c9d624d4c">each</a>()) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>The registry used in this case is the one associated with the storage and also available via the <code>registry</code> function.</p>
|
|
<p>It should be noted that a reactive storage never deletes its entities (and elements, if any). To process and then discard entities at regular intervals, refer to the <code>clear</code> function available by default for each storage type.<br />
|
|
Similarly, the reactive mixin does not disconnect itself from observed storages upon destruction. Therefore, users have to do this themselves:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a> = storage.registry();</div>
|
|
<div class="line"> </div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><position>().disconnect(&storage);</div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><velocity>().disconnect(&storage);</div>
|
|
</div><!-- fragment --><p>Destroying a reactive storage without disconnecting it from observed pools will result in undefined behavior.</p>
|
|
<h2><a class="anchor" id="sorting-is-it-possible"></a>
|
|
Sorting: is it possible?</h2>
|
|
<p>Sorting entities and components is possible using an in-place algorithm that does not require memory allocations and is therefore quite convenient.<br />
|
|
There are two functions that respond to slightly different needs:</p>
|
|
<ul>
|
|
<li><p class="startli">Components are sorted either directly:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a9f8467476bc59f55a9297bd4e93f4914">sort</a><renderable>([](<span class="keyword">const</span> renderable &lhs, <span class="keyword">const</span> renderable &rhs) {</div>
|
|
<div class="line"> <span class="keywordflow">return</span> lhs.z < rhs.z;</div>
|
|
<div class="line">});</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a9f8467476bc59f55a9297bd4e93f4914"><div class="ttname"><a href="classentt_1_1basic__registry.html#a9f8467476bc59f55a9297bd4e93f4914">entt::basic_registry::sort</a></div><div class="ttdeci">void sort(Compare compare, Sort algo=Sort{}, Args &&...args)</div><div class="ttdoc">Sorts the elements of a given element.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l01165">registry.hpp:1165</a></div></div>
|
|
</div><!-- fragment --><p class="startli">Or by accessing their entities:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a9f8467476bc59f55a9297bd4e93f4914">sort</a><renderable>([](<span class="keyword">const</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> lhs, <span class="keyword">const</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> rhs) {</div>
|
|
<div class="line"> <span class="keywordflow">return</span> entt::registry::entity(lhs) < entt::registry::entity(rhs);</div>
|
|
<div class="line">});</div>
|
|
</div><!-- fragment --><p class="startli">There exists also the possibility to use a custom sort function object for when the usage pattern is known.</p>
|
|
</li>
|
|
<li><p class="startli">Components are sorted according to the order imposed by another component:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a9f8467476bc59f55a9297bd4e93f4914">sort</a><movement, physics>();</div>
|
|
</div><!-- fragment --><p class="startli">In this case, instances of <code>movement</code> are arranged in memory so that cache misses are minimized when the two components are iterated together.</p>
|
|
</li>
|
|
</ul>
|
|
<p>As a side note, the use of groups limits the possibility of sorting pools of components. Refer to the specific documentation for more details.</p>
|
|
<h2><a class="anchor" id="helpers"></a>
|
|
Helpers</h2>
|
|
<p>The so-called <em>helpers</em> are small classes and functions mainly designed to offer built-in support for the most basic functionalities.</p>
|
|
<h3><a class="anchor" id="null-entity"></a>
|
|
Null entity</h3>
|
|
<p>The <code><a class="el" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b" title="Compile-time constant for null entities.">entt::null</a></code> variable models the concept of a <em>null entity</em>.<br />
|
|
The library guarantees that the following expression always returns false:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a40d41cd623d5bf7ad95d75aef5e70a65">valid</a>(<a class="code hl_variable" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b">entt::null</a>);</div>
|
|
<div class="ttc" id="anamespaceentt_html_a2f0c0a1c1d953ea991591748744cdd8b"><div class="ttname"><a href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b">entt::null</a></div><div class="ttdeci">constexpr null_t null</div><div class="ttdoc">Compile-time constant for null entities.</div><div class="ttdef"><b>Definition</b> <a href="entity_8hpp_source.html#l00375">entity.hpp:375</a></div></div>
|
|
</div><!-- fragment --><p>A registry rejects the null entity in all cases because it is not considered valid. It also means that the null entity cannot own components.<br />
|
|
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:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> null = <a class="code hl_variable" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b">entt::null</a>;</div>
|
|
</div><!-- fragment --><p>Similarly, the null entity compares to any other identifier:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> entity = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a4ab0e3ed31fb0c455c07d0541941108a">create</a>();</div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keywordtype">bool</span> null = (entity == <a class="code hl_variable" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b">entt::null</a>);</div>
|
|
</div><!-- fragment --><p>As for its integral form, the null entity only affects the entity part of an identifier and is instead completely transparent to its version.</p>
|
|
<p>Be aware that <code><a class="el" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b" title="Compile-time constant for null entities.">entt::null</a></code> and entity 0 are different. Likewise, a zero initialized entity is not the same as <code><a class="el" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b" title="Compile-time constant for null entities.">entt::null</a></code>. Therefore, although <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a>{}</code> is in some sense an alias for entity 0, none of them are used to create a null entity.</p>
|
|
<h3><a class="anchor" id="tombstone"></a>
|
|
Tombstone</h3>
|
|
<p>Similar to the null entity, the <code><a class="el" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862" title="Compile-time constant for tombstone entities.">entt::tombstone</a></code> variable models the concept of a <em>tombstone</em>.<br />
|
|
Once created, the integral form of the two values is the same, although they affect different parts of an identifier. In fact, the tombstone only uses the version part of it and is completely transparent to the entity part.</p>
|
|
<p>Also in this case, the following expression always returns false:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a40d41cd623d5bf7ad95d75aef5e70a65">valid</a>(<a class="code hl_variable" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862">entt::tombstone</a>);</div>
|
|
<div class="ttc" id="anamespaceentt_html_a674269102fdfe3fd6d7766210a828862"><div class="ttname"><a href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862">entt::tombstone</a></div><div class="ttdeci">constexpr tombstone_t tombstone</div><div class="ttdoc">Compile-time constant for tombstone entities.</div><div class="ttdef"><b>Definition</b> <a href="entity_8hpp_source.html#l00384">entity.hpp:384</a></div></div>
|
|
</div><!-- fragment --><p>Moreover, users cannot set the tombstone version when releasing an entity:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a4849d0fe9d6008431239c93c57551d10">destroy</a>(entity, <a class="code hl_variable" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862">entt::tombstone</a>);</div>
|
|
</div><!-- fragment --><p>In this case, a different version number is implicitly generated.<br />
|
|
The type of a tombstone is internal and can change at any time. However, there exist implicit conversions from a tombstone to identifiers of any allowed type:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> null = <a class="code hl_variable" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862">entt::tombstone</a>;</div>
|
|
</div><!-- fragment --><p>Similarly, the tombstone compares to any other identifier:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> entity = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a4ab0e3ed31fb0c455c07d0541941108a">create</a>();</div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keywordtype">bool</span> tombstone = (entity == <a class="code hl_variable" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862">entt::tombstone</a>);</div>
|
|
</div><!-- fragment --><p>Be aware that <code><a class="el" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862" title="Compile-time constant for tombstone entities.">entt::tombstone</a></code> and entity 0 are different. Likewise, a zero initialized entity is not the same as <code><a class="el" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862" title="Compile-time constant for tombstone entities.">entt::tombstone</a></code>. Therefore, although <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a>{}</code> is in some sense an alias for entity 0, none of them are used to create tombstones.</p>
|
|
<h3><a class="anchor" id="to-entity"></a>
|
|
To entity</h3>
|
|
<p>This function accepts a storage and an instance of a component of the storage type, then it returns the entity associated with the latter:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> entity = <a class="code hl_function" href="namespaceentt.html#a1202b4027d32db124efffdf1f2f8c5a2">entt::to_entity</a>(registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a3ffe409b0f7201456b1c1d32c0850474">storage</a><position>(), instance);</div>
|
|
<div class="ttc" id="anamespaceentt_html_a1202b4027d32db124efffdf1f2f8c5a2"><div class="ttname"><a href="namespaceentt.html#a1202b4027d32db124efffdf1f2f8c5a2">entt::to_entity</a></div><div class="ttdeci">constexpr entt_traits< Entity >::entity_type to_entity(const Entity value) noexcept</div><div class="ttdoc">Returns the entity part once converted to the underlying type.</div><div class="ttdef"><b>Definition</b> <a href="entity_8hpp_source.html#l00188">entity.hpp:188</a></div></div>
|
|
</div><!-- fragment --><p>Where <code>instance</code> is a component of type <code>position</code>. A null entity is returned in case the instance does not belong to the registry.</p>
|
|
<h3><a class="anchor" id="dependencies"></a>
|
|
Dependencies</h3>
|
|
<p>The <code>registry</code> class is designed to create short circuits between its member functions. This greatly simplifies the definition of a <em>dependency</em>.<br />
|
|
For example, the following adds (or replaces) the component <code>a_type</code> whenever <code>my_type</code> is assigned to an entity:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><my_type>().connect<&<a class="code hl_function" href="classentt_1_1basic__registry.html#a3ebfbe0d897e77cf0f24bc994a796b15">entt::registry::emplace_or_replace<a_type></a>>();</div>
|
|
</div><!-- fragment --><p>Similarly, the code below removes <code>a_type</code> from an entity whenever <code>my_type</code> is assigned to it:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><my_type>().connect<&<a class="code hl_function" href="classentt_1_1basic__registry.html#a7eb97ddee1a5ee98a722329fe39417ce">entt::registry::remove<a_type></a>>();</div>
|
|
</div><!-- fragment --><p>A dependency is easily <em>broken</em> as follows:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><my_type>().disconnect<&<a class="code hl_function" href="classentt_1_1basic__registry.html#a3ebfbe0d897e77cf0f24bc994a796b15">entt::registry::emplace_or_replace<a_type></a>>();</div>
|
|
</div><!-- fragment --><p>There are many other types of <em>dependencies</em>. In general, most of the functions that accept an entity as their first argument are good candidates for this purpose.</p>
|
|
<h3><a class="anchor" id="invoke"></a>
|
|
Invoke</h3>
|
|
<p>The <code>invoke</code> helper allows to <em>propagate</em> a signal to a member function of a component without having to <em>extend</em> it:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#ab68c1ba5692d30350d30121663203aea">on_construct</a><clazz>().connect<<a class="code hl_function" href="namespaceentt.html#ac25eea8903b4a5d58408cc2e9ecb1a2e">entt::invoke<&clazz::func></a>>();</div>
|
|
<div class="ttc" id="anamespaceentt_html_ac25eea8903b4a5d58408cc2e9ecb1a2e"><div class="ttname"><a href="namespaceentt.html#ac25eea8903b4a5d58408cc2e9ecb1a2e">entt::invoke</a></div><div class="ttdeci">void invoke(Registry &reg, const typename Registry::entity_type entt)</div><div class="ttdoc">Helper to create a listener that directly invokes a member function.</div><div class="ttdef"><b>Definition</b> <a href="helper_8hpp_source.html#l00108">helper.hpp:108</a></div></div>
|
|
</div><!-- fragment --><p>All it does is pick up the <em>right</em> component for the received entity and invoke the requested method, passing on the arguments if necessary.</p>
|
|
<h3><a class="anchor" id="connection-helper"></a>
|
|
Connection helper</h3>
|
|
<p>Connecting signals can quickly become cumbersome.<br />
|
|
This utility aims to simplify the process by grouping the calls:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_struct" href="structentt_1_1sigh__helper.html">entt::sigh_helper</a>{registry}</div>
|
|
<div class="line"> .with<position>()</div>
|
|
<div class="line"> .on_construct<&a_listener>()</div>
|
|
<div class="line"> .on_destroy<&another_listener>()</div>
|
|
<div class="line"> .with<velocity>(<span class="stringliteral">"other"</span>_hs)</div>
|
|
<div class="line"> .on_update<yet_another_listener>();</div>
|
|
<div class="ttc" id="astructentt_1_1sigh__helper_html"><div class="ttname"><a href="structentt_1_1sigh__helper.html">entt::sigh_helper</a></div><div class="ttdoc">Primary template isn't defined on purpose.</div><div class="ttdef"><b>Definition</b> <a href="helper_8hpp_source.html#l00144">helper.hpp:144</a></div></div>
|
|
</div><!-- fragment --><p>Runtime pools are also supported by providing an identifier when calling <code>with</code>, as shown in the previous snippet. Refer to the following sections for more information about runtime pools.<br />
|
|
Obviously, this helper does not make the code disappear but it should at least reduce the boilerplate in the most complex cases.</p>
|
|
<h3><a class="anchor" id="handle"></a>
|
|
Handle</h3>
|
|
<p>A handle is a thin wrapper around an entity and a registry. It <em>replicates</em> the API of a registry by offering functions such as <code>get</code> or <code>emplace</code>. The difference being that the entity is implicitly passed to the registry.<br />
|
|
It is default constructible as an invalid handle that contains a null registry and a null entity. When it contains a null registry, calling functions that delegate execution to the registry causes undefined behavior. It is recommended to test for validity with its implicit cast to <code>bool</code> if in doubt.<br />
|
|
A handle is also non-owning, meaning that it is freely copied and moved around without affecting its entity (in fact, handles happen to be trivially copyable). An implication of this is that mutability becomes part of the type.</p>
|
|
<p>There are two aliases that use <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code> as their default entity: <code><a class="el" href="namespaceentt.html#a4709e4ff444e7d9b73f97d9e471bf8af" title="Alias declaration for the most common use case.">entt::handle</a></code> and <code><a class="el" href="namespaceentt.html#aed8389b9073df462feead9ce84ceeddb" title="Alias declaration for the most common use case.">entt::const_handle</a></code>.<br />
|
|
Users can also easily create their own aliases for custom identifiers as:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">using </span>my_handle = <a class="code hl_class" href="classentt_1_1basic__handle.html">entt::basic_handle<entt::basic_registry<my_identifier></a>>;</div>
|
|
<div class="line"><span class="keyword">using </span>my_const_handle = <a class="code hl_class" href="classentt_1_1basic__handle.html">entt::basic_handle<const entt::basic_registry<my_identifier></a>>;</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__handle_html"><div class="ttname"><a href="classentt_1_1basic__handle.html">entt::basic_handle</a></div><div class="ttdoc">Non-owning handle to an entity.</div><div class="ttdef"><b>Definition</b> <a href="handle_8hpp_source.html#l00098">handle.hpp:98</a></div></div>
|
|
</div><!-- fragment --><p>Non-const handles are also implicitly convertible to const handles out of the box but not the other way around.</p>
|
|
<p>This class is intended to simplify function signatures. In case of functions that take a registry and an entity and do most of their work on that entity, users might want to consider using handles, either const or non-const.</p>
|
|
<h3><a class="anchor" id="organizer"></a>
|
|
Organizer</h3>
|
|
<p>The <code>organizer</code> class template offers support for creating an execution graph from a set of functions and their requirements on resources.<br />
|
|
The resulting tasks are not executed in any case. This is not the goal of this tool. Instead, they are returned to the user in the form of a graph that allows for safe execution.</p>
|
|
<p>All functions are added in order of execution to the organizer:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#a20330b209394a912be898c964f228327">entt::organizer</a> organizer;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// adds a free function to the organizer</span></div>
|
|
<div class="line">organizer.<a class="code hl_function" href="classentt_1_1basic__organizer.html#a813786d2c24e14f9f14d4a9c8799d868">emplace</a><&free_function>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// adds a member function and an instance on which to invoke it to the organizer</span></div>
|
|
<div class="line">clazz instance;</div>
|
|
<div class="line">organizer.<a class="code hl_function" href="classentt_1_1basic__organizer.html#a813786d2c24e14f9f14d4a9c8799d868">emplace</a><&clazz::member_function>(&instance);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// adds a decayed lambda directly</span></div>
|
|
<div class="line">organizer.<a class="code hl_function" href="classentt_1_1basic__organizer.html#a813786d2c24e14f9f14d4a9c8799d868">emplace</a>(+[](<span class="keyword">const</span> <span class="keywordtype">void</span> *, <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a> &) { <span class="comment">/* ... */</span> });</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__organizer_html_a813786d2c24e14f9f14d4a9c8799d868"><div class="ttname"><a href="classentt_1_1basic__organizer.html#a813786d2c24e14f9f14d4a9c8799d868">entt::basic_organizer::emplace</a></div><div class="ttdeci">void emplace(const char *name=nullptr)</div><div class="ttdoc">Adds a free function to the task list.</div><div class="ttdef"><b>Definition</b> <a href="organizer_8hpp_source.html#l00318">organizer.hpp:318</a></div></div>
|
|
<div class="ttc" id="anamespaceentt_html_a20330b209394a912be898c964f228327"><div class="ttname"><a href="namespaceentt.html#a20330b209394a912be898c964f228327">entt::organizer</a></div><div class="ttdeci">basic_organizer< registry > organizer</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00098">fwd.hpp:98</a></div></div>
|
|
</div><!-- fragment --><p>These are the parameters that a free function or a member function can accept:</p>
|
|
<ul>
|
|
<li>A possibly constant reference to a registry.</li>
|
|
<li>An <code><a class="el" href="classentt_1_1basic__view.html" title="View implementation.">entt::basic_view</a></code> with any possible combination of storage classes.</li>
|
|
<li>A possibly constant reference to any type <code>T</code> (that is, a context variable).</li>
|
|
</ul>
|
|
<p>The function type for free functions and decayed lambdas passed as parameters to <code>emplace</code> is <code>void(const void *, <a class="el" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4" title="Alias declaration for the most common use case.">entt::registry</a> &)</code> instead. The first parameter is an optional pointer to user defined data to provide upon registration:</p>
|
|
<div class="fragment"><div class="line">clazz instance;</div>
|
|
<div class="line">organizer.<a class="code hl_function" href="classentt_1_1basic__organizer.html#a813786d2c24e14f9f14d4a9c8799d868">emplace</a>(+[](<span class="keyword">const</span> <span class="keywordtype">void</span> *, <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a> &) { <span class="comment">/* ... */</span> }, &instance);</div>
|
|
</div><!-- fragment --><p>In all cases, it is also possible to associate a name with the task when creating it. For example:</p>
|
|
<div class="fragment"><div class="line">organizer.<a class="code hl_function" href="classentt_1_1basic__organizer.html#a813786d2c24e14f9f14d4a9c8799d868">emplace</a><&free_function>(<span class="stringliteral">"func"</span>);</div>
|
|
</div><!-- fragment --><p>When a function is registered with the organizer, everything it accesses is considered a <em>resource</em> (views are <em>unpacked</em> and their types are treated as resources). The <em>constness</em> of a type also dictates its access mode (RO/RW). In turn, this affects the resulting graph, since it influences the possibility of launching tasks in parallel.<br />
|
|
As for the registry, if a function does not explicitly request it or requires a constant reference to it, it is considered a read-only access. Otherwise, it is considered as read-write access. All functions have the registry among their resources.</p>
|
|
<p>When registering a function, users can also require resources that are not in the list of parameters of the function itself. These are declared as template parameters:</p>
|
|
<div class="fragment"><div class="line">organizer.<a class="code hl_function" href="classentt_1_1basic__organizer.html#a813786d2c24e14f9f14d4a9c8799d868">emplace</a><&free_function, position, velocity>(<span class="stringliteral">"func"</span>);</div>
|
|
</div><!-- fragment --><p>Similarly, users can override the access mode of a type again via template parameters:</p>
|
|
<div class="fragment"><div class="line">organizer.<a class="code hl_function" href="classentt_1_1basic__organizer.html#a813786d2c24e14f9f14d4a9c8799d868">emplace</a><&free_function, <span class="keyword">const</span> renderable>(<span class="stringliteral">"func"</span>);</div>
|
|
</div><!-- fragment --><p>In this case, even if <code>renderable</code> appears among the parameters of the function as not constant, it is treated as constant as regards the generation of the task graph.</p>
|
|
<p>To generate the task graph, the organizer offers the <code>graph</code> member function:</p>
|
|
<div class="fragment"><div class="line">std::vector<entt::organizer::vertex> graph = organizer.<a class="code hl_function" href="classentt_1_1basic__organizer.html#a540973737740605acac4c35d1176abde">graph</a>();</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__organizer_html_a540973737740605acac4c35d1176abde"><div class="ttname"><a href="classentt_1_1basic__organizer.html#a540973737740605acac4c35d1176abde">entt::basic_organizer::graph</a></div><div class="ttdeci">std::vector< vertex > graph()</div><div class="ttdoc">Generates a task graph for the current content.</div><div class="ttdef"><b>Definition</b> <a href="organizer_8hpp_source.html#l00403">organizer.hpp:403</a></div></div>
|
|
</div><!-- fragment --><p>A graph is returned in the form of an adjacency list. Each vertex offers the following features:</p>
|
|
<ul>
|
|
<li><code>ro_count</code> and <code>rw_count</code>: the number of resources accessed in read-only or read-write mode.</li>
|
|
<li><code>ro_dependency</code> and <code>rw_dependency</code>: type info objects associated with the parameters of the underlying function.</li>
|
|
<li><code>top_level</code>: true if a node is a top level one (it has no entering edges), false otherwise.</li>
|
|
<li><code>info</code>: type info object associated with the underlying function.</li>
|
|
<li><code>name</code>: the name associated with the given vertex if any, a null pointer otherwise.</li>
|
|
<li><code>callback</code>: a pointer to the function to execute and whose function type is <code>void(const void *, <a class="el" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4" title="Alias declaration for the most common use case.">entt::registry</a> &)</code>.</li>
|
|
<li><code>data</code>: optional data to provide to the callback.</li>
|
|
<li><code>children</code>: the vertices reachable from the given node, in the form of indices within the adjacency list.</li>
|
|
</ul>
|
|
<p>Since the creation of pools and resources within the registry is not necessarily thread safe, each vertex also offers a <code>prepare</code> function which is used to setup a registry for execution with the created graph:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> graph = organizer.<a class="code hl_function" href="classentt_1_1basic__organizer.html#a540973737740605acac4c35d1176abde">graph</a>();</div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">entt::registry</a> registry;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> &&node: graph) {</div>
|
|
<div class="line"> node.prepare(registry);</div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>The actual scheduling of the tasks is the responsibility of the user, who can use the preferred tool.</p>
|
|
<h2><a class="anchor" id="context-variables"></a>
|
|
Context variables</h2>
|
|
<p>Each registry has a <em>context</em> associated with it, which is an <code>any</code> object map accessible by both type and <em>name</em> for convenience. The <em>name</em> is not really a name though. In fact, it is a numeric id of type <code>id_type</code> used as a key for the variable. Any value is accepted, even runtime ones.<br />
|
|
The context is returned via the <code>ctx</code> functions and offers a minimal set of features including the following:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// creates a new context variable by type and returns it</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().emplace<my_type>(42, <span class="charliteral">'c'</span>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// creates a new named context variable by type and returns it</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().emplace_as<my_type>(<span class="stringliteral">"my_variable"</span>_hs, 42, <span class="charliteral">'c'</span>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// inserts or assigns a context variable by (deduced) type and returns it</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().insert_or_assign(my_type{42, <span class="charliteral">'c'</span>});</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// inserts or assigns a named context variable by (deduced) type and returns it</span></div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().insert_or_assign(<span class="stringliteral">"my_variable"</span>_hs, my_type{42, <span class="charliteral">'c'</span>});</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// gets the context variable by type as a non-const reference from a non-const registry</span></div>
|
|
<div class="line"><span class="keyword">auto</span> &var = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().get<my_type>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// gets the context variable by name as a const reference from either a const or a non-const registry</span></div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> &cvar = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().get<<span class="keyword">const</span> my_type>(<span class="stringliteral">"my_variable"</span>_hs);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// resets the context variable by type</span></div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().erase<my_type>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// resets the context variable associated with the given name</span></div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().erase<my_type>(<span class="stringliteral">"my_variable"</span>_hs);</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html_a063e7f4879b50fcd332702bc8cc0fa61"><div class="ttname"><a href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">entt::basic_registry::ctx</a></div><div class="ttdeci">context & ctx() noexcept</div><div class="ttdoc">Returns the context object, that is, a general purpose container.</div><div class="ttdef"><b>Definition</b> <a href="registry_8hpp_source.html#l01201">registry.hpp:1201</a></div></div>
|
|
</div><!-- fragment --><p>A context variable must be both default constructible and movable. If the supplied type does not match that of the variable when using a <em>name</em>, the operation fails.<br />
|
|
For all users who want to use the context but do not want to create elements, the <code>contains</code> and <code>find</code> functions are also available:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">bool</span> contains = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().contains<my_type>();</div>
|
|
<div class="line"><span class="keyword">const</span> my_type *value = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().find<<span class="keyword">const</span> my_type>(<span class="stringliteral">"my_variable"</span>_hs);</div>
|
|
</div><!-- fragment --><p>Also in this case, both functions support constant types and accept a <em>name</em> for the variable to look up, as does <code>at</code>.</p>
|
|
<h3><a class="anchor" id="aliased-properties"></a>
|
|
Aliased properties</h3>
|
|
<p>A context also supports creating <em>aliases</em> for existing variables that are not directly managed by the registry. Const and therefore read-only variables are also accepted.<br />
|
|
To do that, the type used upon construction must be a reference type and an lvalue is necessarily provided as an argument:</p>
|
|
<div class="fragment"><div class="line">time clock;</div>
|
|
<div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().emplace<time &>(clock);</div>
|
|
</div><!-- fragment --><p>Read-only aliased properties are created using const types instead:</p>
|
|
<div class="fragment"><div class="line">registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().emplace<<span class="keyword">const</span> time &>(clock);</div>
|
|
</div><!-- fragment --><p>Note that <code>insert_or_assign</code> does not support aliased properties and users must necessarily use <code>emplace</code> or <code>emplace_as</code> for this purpose.<br />
|
|
When <code>insert_or_assign</code> is used to update an aliased property, it <em>converts</em> the property itself into a non-aliased one.</p>
|
|
<p>From the point of view of the user, there are no differences between a variable that is managed by the registry and an aliased property. However, read-only variables are not accessible as non-const references:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// read-only variables only support const access</span></div>
|
|
<div class="line"><span class="keyword">const</span> my_type *ptr = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().find<<span class="keyword">const</span> my_type>();</div>
|
|
<div class="line"><span class="keyword">const</span> my_type &var = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a063e7f4879b50fcd332702bc8cc0fa61">ctx</a>().get<<span class="keyword">const</span> my_type>();</div>
|
|
</div><!-- fragment --><p>Aliased properties are erased as it happens with any other variable. Similarly, it is also possible to assign them a <em>name</em>.</p>
|
|
<h2><a class="anchor" id="snapshot-complete-vs-continuous"></a>
|
|
Snapshot: complete vs continuous</h2>
|
|
<p>This module comes with bare minimum support for serialization.<br />
|
|
It does not convert components to bytes directly, there was not the need of another tool for serialization out there. Instead, it accepts an opaque object with a suitable interface (namely an <em>archive</em>) 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.</p>
|
|
<p>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 in which they are interested.<br />
|
|
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.</p>
|
|
<p>To take a snapshot of a registry, use the <code>snapshot</code> class:</p>
|
|
<div class="fragment"><div class="line">output_archive output;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ae81f1e05f8be1263f14284164387c180">entt::snapshot</a>{registry}</div>
|
|
<div class="line"> .get<<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>>(output)</div>
|
|
<div class="line"> .get<a_component>(output)</div>
|
|
<div class="line"> .get<another_component>(output);</div>
|
|
<div class="ttc" id="anamespaceentt_html_ae81f1e05f8be1263f14284164387c180"><div class="ttname"><a href="namespaceentt.html#ae81f1e05f8be1263f14284164387c180">entt::snapshot</a></div><div class="ttdeci">basic_snapshot< registry > snapshot</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00121">fwd.hpp:121</a></div></div>
|
|
</div><!-- fragment --><p>It is not necessary to invoke all functions each and every time. What functions to use in which case mostly depends on the goal.</p>
|
|
<p>When <em>getting</em> an entity type, the snapshot class serializes all entities along with their versions.<br />
|
|
In all other cases, entities and components from a given storage are passed to the archive. Named pools are also supported:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#ae81f1e05f8be1263f14284164387c180">entt::snapshot</a>{registry}.get<a_component>(output, <span class="stringliteral">"other"</span>_hs);</div>
|
|
</div><!-- fragment --><p>There exists another version of the <code>get</code> member function that accepts a range of entities to serialize. It can be used to <em>filter</em> out those entities that should not be serialized for some reasons:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> view = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a563374eb952f575470291d2a574176dc">view</a><serialize>();</div>
|
|
<div class="line">output_archive output;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ae81f1e05f8be1263f14284164387c180">entt::snapshot</a>{registry}</div>
|
|
<div class="line"> .get<a_component>(output, view.begin(), view.end())</div>
|
|
<div class="line"> .get<another_component>(output, view.begin(), view.end());</div>
|
|
</div><!-- fragment --><p>Once a snapshot is created, there exist mainly two <em>ways</em> to load it: as a whole and in a kind of <em>continuous mode</em>.<br />
|
|
The following sections describe both loaders and archives in details.</p>
|
|
<h3><a class="anchor" id="snapshot-loader"></a>
|
|
Snapshot loader</h3>
|
|
<p>A snapshot loader requires that the destination registry be empty. It loads all the data at once while keeping intact the identifiers that the entities originally had:</p>
|
|
<div class="fragment"><div class="line">input_archive input;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#affcc892243a02aafd27f353bd810fca6">entt::snapshot_loader</a>{registry}</div>
|
|
<div class="line"> .get<<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>>(input)</div>
|
|
<div class="line"> .get<a_component>(input)</div>
|
|
<div class="line"> .get<another_component>(input)</div>
|
|
<div class="line"> .orphans();</div>
|
|
<div class="ttc" id="anamespaceentt_html_affcc892243a02aafd27f353bd810fca6"><div class="ttname"><a href="namespaceentt.html#affcc892243a02aafd27f353bd810fca6">entt::snapshot_loader</a></div><div class="ttdeci">basic_snapshot_loader< registry > snapshot_loader</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00124">fwd.hpp:124</a></div></div>
|
|
</div><!-- fragment --><p>It is not necessary to invoke all functions each and every time. What functions to use in which case mostly depends on the goal.<br />
|
|
For obvious reasons, what is important is that the data are restored in exactly the same order in which they were serialized.</p>
|
|
<p>When <em>getting</em> an entity type, a snapshot loader restores all entities with the versions that they originally had at the source.<br />
|
|
In all other cases, entities and components are restored in a given storage. If the registry does not contain the entity, it is also created accordingly. As for the snapshot class, named pools are supported too:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#affcc892243a02aafd27f353bd810fca6">entt::snapshot_loader</a>{registry}.get<a_component>(input, <span class="stringliteral">"other"</span>_hs);</div>
|
|
</div><!-- fragment --><p>Finally, the <code>orphans</code> member function releases the entities that have no components after a restore, if any.</p>
|
|
<h3><a class="anchor" id="continuous-loader"></a>
|
|
Continuous loader</h3>
|
|
<p>A continuous loader is designed to load data from a source registry to a (possibly) non-empty destination. The loader accommodates in a registry more than one snapshot in a sort of <em>continuous loading</em> that updates the destination one step at a time.<br />
|
|
Identifiers that entities originally had are not transferred to the target. Instead, the loader maps remote identifiers to local ones while restoring a snapshot. Wrapping the archive is a conveninent way of updating identifiers that are part of components automatically (see the example below).<br />
|
|
Another difference with the snapshot loader is that the continuous loader has an internal state that must persist over time. Therefore, there is no reason to limit its lifetime to that of a temporary object:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#ae827dd63b5553f701ae049a1cf95ef0c">entt::continuous_loader</a> loader{registry};</div>
|
|
<div class="line">input_archive input;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">auto</span> archive = [&loader, &input](<span class="keyword">auto</span> &value) {</div>
|
|
<div class="line"> input(value);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">if</span> <span class="keyword">constexpr</span>(std::is_same_v<std::remove_reference_t<<span class="keyword">decltype</span>(value)>, dirty_component>) {</div>
|
|
<div class="line"> value.parent = loader.map(value.parent);</div>
|
|
<div class="line"> value.child = loader.map(value.child);</div>
|
|
<div class="line"> }</div>
|
|
<div class="line">};</div>
|
|
<div class="line"> </div>
|
|
<div class="line">loader</div>
|
|
<div class="line"> .get<<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>>(input)</div>
|
|
<div class="line"> .get<a_component>(input)</div>
|
|
<div class="line"> .get<another_component>(input)</div>
|
|
<div class="line"> .get<dirty_component>(input)</div>
|
|
<div class="line"> .orphans();</div>
|
|
<div class="ttc" id="anamespaceentt_html_ae827dd63b5553f701ae049a1cf95ef0c"><div class="ttname"><a href="namespaceentt.html#ae827dd63b5553f701ae049a1cf95ef0c">entt::continuous_loader</a></div><div class="ttdeci">basic_continuous_loader< registry > continuous_loader</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00127">fwd.hpp:127</a></div></div>
|
|
</div><!-- fragment --><p>It is not necessary to invoke all functions each and every time. What functions to use in which case mostly depends on the goal.<br />
|
|
For obvious reasons, what is important is that the data are restored in exactly the same order in which they were serialized.</p>
|
|
<p>When <em>getting</em> an entity type, a loader restores groups of entities and maps each entity to a local counterpart when required. For each remote identifier not yet registered by the loader, a local identifier is created so as to keep the local entity in sync with the remote one.<br />
|
|
In all other cases, entities and components are restored in a given storage. If the registry does not contain the entity, it is also tracked accordingly. As for the snapshot class, named pools are supported too:</p>
|
|
<div class="fragment"><div class="line">loader.get<a_component>(input, <span class="stringliteral">"other"</span>_hs);</div>
|
|
</div><!-- fragment --><p>Finally, the <code>orphans</code> member function releases the entities that have no components after a restore, if any.</p>
|
|
<h3><a class="anchor" id="archives"></a>
|
|
Archives</h3>
|
|
<p>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.</p>
|
|
<p>In particular:</p>
|
|
<ul>
|
|
<li><p class="startli">An output archive (the one used when creating a snapshot) exposes a function call operator with the following signature to store entities:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> operator()(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>);</div>
|
|
</div><!-- fragment --><p class="startli">Where <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code> is the type of the entities used by the registry.<br />
|
|
Note that all member functions of the snapshot class also make an initial call to store aside the <em>size</em> of the set they are going to store. In this case, the expected function type for the function call operator is:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> operator()(std::underlying_type_t<entt::entity>);</div>
|
|
</div><!-- fragment --><p class="startli">In addition, an archive accepts (const) references to the types of component to serialize. Therefore, given a type <code>T</code>, the archive offers a function call operator with the following signature:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> operator()(<span class="keyword">const</span> T &);</div>
|
|
</div><!-- fragment --><p class="startli">The output archive can freely decide how to serialize the data. The registry is not affected at all by the decision.</p>
|
|
</li>
|
|
<li><p class="startli">An input archive (the one used when restoring a snapshot) exposes a function call operator with the following signature to load entities:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> operator()(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> &);</div>
|
|
</div><!-- fragment --><p class="startli">Where <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code> is the type of the entities used by the registry. Each time the function is invoked, the archive reads the next element from the underlying storage and copies it in the given variable.<br />
|
|
All member functions of a loader class also make an initial call to read the <em>size</em> of the set they are going to load. In this case, the expected function type for the function call operator is:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> operator()(std::underlying_type_t<entt::entity> &);</div>
|
|
</div><!-- fragment --><p class="startli">In addition, an archive accepts references to the types of component to restore. Therefore, given a type <code>T</code>, the archive contains a function call operator with the following signature:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> operator()(T &);</div>
|
|
</div><!-- fragment --><p class="startli">Every time this operator is invoked, the archive reads the next element from the underlying storage and copies it in the given variable.</p>
|
|
</li>
|
|
</ul>
|
|
<h3><a class="anchor" id="one-example-to-rule-them-all"></a>
|
|
One example to rule them all</h3>
|
|
<p><code>EnTT</code> comes with some examples (actually some tests) that show how to integrate a well known library for serialization as an archive. It uses <a href="https://uscilab.github.io/cereal/"><code>Cereal C++</code></a> under the hood, mainly because I wanted to learn how it works at the time I was writing the code.</p>
|
|
<p>The code <b>is not</b> production-ready and it is not neither the only nor (probably) the best way to do it. However, feel free to use it at your own risk.<br />
|
|
The basic idea is to store everything in a group of queues in memory, then bring everything back to the registry with different loaders.</p>
|
|
<h1><a class="anchor" id="storage"></a>
|
|
Storage</h1>
|
|
<p>Pools of components are <em>specialized versions</em> of the sparse set class. Each pool contains all the instances of a single component type and all the entities to which it is assigned.<br />
|
|
Sparse arrays are <em>paged</em> to avoid wasting memory. Packed arrays of components are also paged to have pointer stability upon additions. Packed arrays of entities are not instead.<br />
|
|
All pools rearranges their items in order to keep the internal arrays tightly packed and maximize performance, unless full pointer stability is enabled.</p>
|
|
<h2><a class="anchor" id="component-traits"></a>
|
|
Component traits</h2>
|
|
<p>In <code>EnTT</code>, almost everything is customizable. Pools are no exception.<br />
|
|
In this case, the <em>standardized</em> way to access all component properties is the <code>component_traits</code> class.</p>
|
|
<p>Various parts of the library access component properties through this class. It makes it possible to use any type as a component, as long as its specialization of <code>component_traits</code> implements all the required functionalities.<br />
|
|
The non-specialized version of this class contains the following members:</p>
|
|
<ul>
|
|
<li><code>in_place_delete</code>: <code>Type::in_place_delete</code> if present, true for non-movable types and false otherwise.</li>
|
|
<li><code>page_size</code>: <code>Type::page_size</code> if present, <code>ENTT_PACKED_PAGE</code> for non-empty types and 0 otherwise.</li>
|
|
</ul>
|
|
<p>Where <code>Type</code> is any type of component. Properties are customized by specializing the above class and defining its members, or by adding only those of interest to a component definition:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">struct </span>transform {</div>
|
|
<div class="line"> <span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keyword">auto</span> in_place_delete = <span class="keyword">true</span>;</div>
|
|
<div class="line"> <span class="comment">// ... other data members ...</span></div>
|
|
<div class="line">};</div>
|
|
</div><!-- fragment --><p>The <code>component_traits</code> class template takes care of <em>extracting</em> the properties from the supplied type.<br />
|
|
Plus, it is <em>sfinae-friendly</em> and also supports feature-based specializations.</p>
|
|
<h2><a class="anchor" id="empty-type-optimization"></a>
|
|
Empty type optimization</h2>
|
|
<p>An empty type <code>T</code> is such that <code>std::is_empty_v<T></code> returns true. They also are the same types for which <em>empty base optimization</em> (EBO) is possible.<br />
|
|
<code>EnTT</code> handles these types in a special way, optimizing both in terms of performance and memory usage. However, this also has consequences that are worth mentioning.</p>
|
|
<p>When an empty type is detected, it is not instantiated by default. Therefore, only the entities to which it is assigned are made available. There does not exist a way to <em>get</em> empty types from a storage or a registry. Views and groups never return their instances too (for example, during a call to <code>each</code>).<br />
|
|
On the other hand, iterations are faster because only the entities to which the type is assigned are considered. Moreover, less memory is used, mainly because there does not exist any instance of the component, no matter how many entities it is assigned to.</p>
|
|
<p>More in general, none of the feature offered by the library is affected, but for the ones that require to return actual instances.<br />
|
|
This optimization is disabled by defining the <code>ENTT_NO_ETO</code> macro. In this case, empty types are treated like all other types. Setting a page size at component level via the <code>component_traits</code> class template is another way to disable this optimization selectively rather than globally.</p>
|
|
<h2><a class="anchor" id="void-storage"></a>
|
|
Void storage</h2>
|
|
<p>A void storage (or <code><a class="el" href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e" title="Alias declaration for the most common use case.">entt::storage</a><void></code> or <code><a class="el" href="classentt_1_1basic__storage.html" title="Storage implementation.">entt::basic_storage</a><Type, void></code>), is a fully functional storage type used to create pools not associated with a particular component type.<br />
|
|
From a technical point of view, it is in all respects similar to a storage for empty types when their optimization is enabled. Pagination is disabled as well as pointer stability (as not necessary).<br />
|
|
However, this should be preferred to using a simple sparse set. In particular, a void storage offers all those feature normally offered by other storage types. Therefore, it is a perfectly valid pool for use with views and groups or within a registry.</p>
|
|
<h2><a class="anchor" id="entity-storage"></a>
|
|
Entity storage</h2>
|
|
<p>This storage is such that the component type is the same as the entity type, for example <code><a class="el" href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e" title="Alias declaration for the most common use case.">entt::storage</a><<a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a>></code> or <code><a class="el" href="classentt_1_1basic__storage.html" title="Storage implementation.">entt::basic_storage</a><Type, Type></code>.<br />
|
|
For this type of pools, there is a specific specialization within <code>EnTT</code>. In fact, entities are subject to different rules with respect to components (although still customizable by the user if needed). In particular:</p>
|
|
<ul>
|
|
<li>Entities are never truly <em>deleted</em>. They are moved out of the list of entities <em>in use</em> and their versions are updated automatically.</li>
|
|
<li>There are no <code>emplace</code> or <code>insert</code> functions in its interface. Instead, a range of <code>generate</code> functions are provided for creating or recycling entities.</li>
|
|
<li>The <code>each</code> function returns an iterable object to visit the entities <em>in use</em>, that is, those not marked as <em>ready for reuse</em>. To iterate all the entities it is necessary to iterate the underlying sparse set instead.</li>
|
|
</ul>
|
|
<p>This kind of storage is designed to be used where any other storage is fine and can therefore be combined with views, groups and so on.</p>
|
|
<h3><a class="anchor" id="reserved-identifiers"></a>
|
|
Reserved identifiers</h3>
|
|
<p>Since the entity storage is the one in charge of generating identifiers, it is also possible to request that some of them be reserved and never returned.<br />
|
|
By doing so, users can then generate and manage them autonomously, as needed.</p>
|
|
<p>To set a starting identifier, the <code>start_from</code> function is invoked as follows:</p>
|
|
<div class="fragment"><div class="line">storage.start_from(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>{100});</div>
|
|
</div><!-- fragment --><p>Note that the version is irrelevant and is ignored in all cases. Identifiers are always generated with default version.<br />
|
|
By calling <code>start_from</code> as above, the first 100 elements are discarded and the first identifier returned is the one with entity 100 and version 0.</p>
|
|
<h3><a class="anchor" id="one-of-a-kind-to-the-registry"></a>
|
|
One of a kind to the registry</h3>
|
|
<p>Within the registry, an entity storage is treated in all respects like any other storage.<br />
|
|
Therefore, it is possible to add mixins to it as well as retrieve it via the <code>storage</code> function. It can also be used as storage in a view (for exclude-only views for example):</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> view = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a563374eb952f575470291d2a574176dc">view</a><<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>>(<a class="code hl_variable" href="namespaceentt.html#a5b73210cef43c4db35ef8ce477cc38a6">entt::exclude<my_type></a>);</div>
|
|
</div><!-- fragment --><p>However, it is also subject to a couple of exceptions, partly out of necessity and partly for ease of use.</p>
|
|
<p>In particular, it is not possible to create multiple elements of this type.<br />
|
|
This means that the <em>name</em> used to retrieve this kind of storage is ignored and the registry will only ever return the same element to the caller. For example:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> &other = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a3ffe409b0f7201456b1c1d32c0850474">storage</a><<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>>(<span class="stringliteral">"other"</span>_hs);</div>
|
|
</div><!-- fragment --><p>In this case, the identifier is discarded as is. The call is in all respects equivalent to the following:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> &storage = registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a3ffe409b0f7201456b1c1d32c0850474">storage</a><<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>>();</div>
|
|
</div><!-- fragment --><p>Because entity storage does not have a name, it cannot be retrieved via the opaque <code>storage</code> function either.<br />
|
|
It would make no sense to try anyway, given that the type of the registry and therefore its entity type are known regardless.</p>
|
|
<p>Finally, when the user asks the registry for an iterable object to visit all the storage elements inside it as follows:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> [<span class="keywordtype">id</span>, storage]: registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a3ffe409b0f7201456b1c1d32c0850474">storage</a>()) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Entity storage is never returned. This simplifies many tasks (such as copying an entity) and fits perfectly with the fact that this type of storage does not have an identifier inside the registry.</p>
|
|
<h2><a class="anchor" id="pointer-stability"></a>
|
|
Pointer stability</h2>
|
|
<p>The ability to achieve pointer stability for one, several or all components is a direct consequence of the design of <code>EnTT</code> and of its default storage.<br />
|
|
In fact, although it contains what is commonly referred to as a <em>packed array</em>, the default storage is paged and does not suffer from invalidation of references when it runs out of space and has to reallocate.<br />
|
|
However, this is not enough to ensure pointer stability in case of deletion. For this reason, a <em>stable</em> deletion method is also offered. This one is such that the position of the elements is preserved by creating tombstones upon deletion rather than trying to fill the holes that are created.</p>
|
|
<p>For performance reasons, <code>EnTT</code> favors storage compaction in all cases, although often accessing a component occurs mostly randomly or traversing pools in a non-linear order on the user side (as in the case of a hierarchy).<br />
|
|
In other words, pointer stability is not automatic but is enabled on request.</p>
|
|
<h3><a class="anchor" id="in-place-delete"></a>
|
|
In-place delete</h3>
|
|
<p>The library offers out of the box support for in-place deletion, thus offering storage with completely stable pointers. This is achieved by specializing the <code>component_traits</code> class or by adding the required properties to the component definition when needed.<br />
|
|
Views and groups adapt accordingly when they detect a storage with a different deletion policy than the default. In particular:</p>
|
|
<ul>
|
|
<li>Groups are incompatible with stable storage and even refuse to compile.</li>
|
|
<li>Multi type and runtime views are completely transparent to storage policies.</li>
|
|
<li>Single type views for stable storage types offer the same interface of multi type views. For example, only <code>size_hint</code> is available.</li>
|
|
</ul>
|
|
<p>In other words, the more generic version of a view is provided in case of stable storage, even for a single type view.<br />
|
|
In no case a tombstone is returned from the view itself. Likewise, non-existent components are not returned, which could otherwise result in an UB.</p>
|
|
<h3><a class="anchor" id="hierarchies-and-the-like"></a>
|
|
Hierarchies and the like</h3>
|
|
<p><code>EnTT</code> does not attempt in any way to offer built-in methods with hidden or unclear costs to facilitate the creation of hierarchies.<br />
|
|
There are various solutions to the problem, such as using the following class:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">struct </span>relationship {</div>
|
|
<div class="line"> std::size_t children{};</div>
|
|
<div class="line"> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> first{<a class="code hl_variable" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b">entt::null</a>};</div>
|
|
<div class="line"> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> prev{<a class="code hl_variable" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b">entt::null</a>};</div>
|
|
<div class="line"> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> next{<a class="code hl_variable" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b">entt::null</a>};</div>
|
|
<div class="line"> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> parent{<a class="code hl_variable" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b">entt::null</a>};</div>
|
|
<div class="line"> <span class="comment">// ... other data members ...</span></div>
|
|
<div class="line">};</div>
|
|
</div><!-- fragment --><p>However, it should be pointed out that the possibility of having stable pointers for one, many or all types solves the problem of hierarchies at the root in many cases.<br />
|
|
In fact, if a certain type of component is visited mainly in random order or according to hierarchical relationships, using direct pointers has many advantages:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">struct </span>transform {</div>
|
|
<div class="line"> <span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keyword">auto</span> in_place_delete = <span class="keyword">true</span>;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> transform *parent;</div>
|
|
<div class="line"> <span class="comment">// ... other data members ...</span></div>
|
|
<div class="line">};</div>
|
|
</div><!-- fragment --><p>Furthermore, it is quite common for a group of elements to be created close in time and therefore fallback into adjacent positions, thus favoring locality even on random accesses. Locality that is not sacrificed over time given the stability of storage positions, with undoubted performance advantages.</p>
|
|
<h1><a class="anchor" id="meet-the-runtime"></a>
|
|
Meet the runtime</h1>
|
|
<p><code>EnTT</code> takes advantage of what the language offers at compile-time. However, this can have its downsides (well known to those familiar with type erasure techniques).<br />
|
|
To fill the gap, the library also provides a bunch of utilities and features that are invaluable to handle types and pools at runtime.</p>
|
|
<h2><a class="anchor" id="a-base-class-to-rule-them-all"></a>
|
|
A base class to rule them all</h2>
|
|
<p>Storage classes are fully self-contained types. They are <em>extended</em> via mixins to add more functionalities (generic or type specific). In addition, they offer a basic set of functions that already allow users to go very far.<br />
|
|
The aim is to limit the need for customizations as much as possible, offering what is usually necessary for the vast majority of cases.</p>
|
|
<p>When a storage is used through its base class (for example, when its actual type is not known), there is always the possibility of receiving a <code>type_info</code> object for the type of elements associated with the entities (if any):</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">if</span>(<a class="code hl_function" href="namespaceentt.html#adb9682d476edbbe4434680363f9c0eb3">entt::type_id<velocity></a>() == base.type()) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="anamespaceentt_html_adb9682d476edbbe4434680363f9c0eb3"><div class="ttname"><a href="namespaceentt.html#adb9682d476edbbe4434680363f9c0eb3">entt::type_id</a></div><div class="ttdeci">const type_info & type_id() noexcept</div><div class="ttdoc">Returns the type info object associated to a given type.</div><div class="ttdef"><b>Definition</b> <a href="type__info_8hpp_source.html#l00251">type_info.hpp:251</a></div></div>
|
|
</div><!-- fragment --><p>Furthermore, all features rely on internal functions that forward the calls to the mixins. The latter can then make use of any information, which is set via <code>bind</code>:</p>
|
|
<div class="fragment"><div class="line">base.bind(registry);</div>
|
|
</div><!-- fragment --><p>The <code>bind</code> function accepts any element by reference or by value and forwards it to derived classes.<br />
|
|
This is how a registry <em>passes</em> itself to all pools that support signals and also why a storage keeps sending events without requiring the registry to be passed to it every time.</p>
|
|
<p>Alongside these more specific things, there are also a couple of functions designed to address some common requirements such as copying an entity.<br />
|
|
In particular, the base class behind a storage offers the possibility to <em>take</em> the value associated with an entity through an opaque pointer:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">void</span> *instance = base.value(entity);</div>
|
|
</div><!-- fragment --><p>Similarly, the non-specialized <code>push</code> function accepts an optional opaque pointer and behaves differently depending on the case:</p>
|
|
<ul>
|
|
<li>When the pointer is null, the function tries to default-construct an instance of the object to bind to the entity and returns true on success.</li>
|
|
<li>When the pointer is not null, the function tries to copy-construct an instance of the object to bind to the entity and returns true on success.</li>
|
|
</ul>
|
|
<p>This means that, starting from a reference to the base, it is possible to bind components with entities without knowing their actual type and even initialize them by copy if needed:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// create a copy of an entity component by component</span></div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> &&curr: registry.<a class="code hl_function" href="classentt_1_1basic__registry.html#a3ffe409b0f7201456b1c1d32c0850474">storage</a>()) {</div>
|
|
<div class="line"> <span class="keywordflow">if</span>(<span class="keyword">auto</span> &storage = curr.second; storage.<a class="code hl_function" href="classentt_1_1basic__sparse__set.html#a97b47cbaea3fc30442fa3e6366766c86">contains</a>(src)) {</div>
|
|
<div class="line"> storage.<a class="code hl_function" href="classentt_1_1basic__sparse__set.html#a8cf01b2a8d20329ec1c1d5d3b5708969">push</a>(dst, storage.<a class="code hl_function" href="classentt_1_1basic__sparse__set.html#ab3725f4fb86b9bb73f5f397884ff1680">value</a>(src));</div>
|
|
<div class="line"> }</div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__sparse__set_html_a8cf01b2a8d20329ec1c1d5d3b5708969"><div class="ttname"><a href="classentt_1_1basic__sparse__set.html#a8cf01b2a8d20329ec1c1d5d3b5708969">entt::basic_sparse_set::push</a></div><div class="ttdeci">iterator push(const entity_type entt, const void *elem=nullptr)</div><div class="ttdoc">Assigns an entity to a sparse set.</div><div class="ttdef"><b>Definition</b> <a href="sparse__set_8hpp_source.html#l00797">sparse_set.hpp:797</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1basic__sparse__set_html_ab3725f4fb86b9bb73f5f397884ff1680"><div class="ttname"><a href="classentt_1_1basic__sparse__set.html#ab3725f4fb86b9bb73f5f397884ff1680">entt::basic_sparse_set::value</a></div><div class="ttdeci">const void * value(const entity_type entt) const noexcept</div><div class="ttdoc">Returns the element assigned to an entity, if any.</div><div class="ttdef"><b>Definition</b> <a href="sparse__set_8hpp_source.html#l00776">sparse_set.hpp:776</a></div></div>
|
|
</div><!-- fragment --><p>This is particularly useful to clone entities in an opaque way. In addition, the decoupling of features allows for filtering or use of different copying policies depending on the type.</p>
|
|
<h2><a class="anchor" id="beam-me-up-registry"></a>
|
|
Beam me up, registry</h2>
|
|
<p><code>EnTT</code> allows the user to assign a <em>name</em> (or rather, a numeric identifier) to a type and then create multiple pools of the same type:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">using namespace </span>entt::literals;</div>
|
|
<div class="line"><span class="keyword">auto</span> &&<a class="code hl_typedef" href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e">storage</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<velocity>(<span class="stringliteral">"second pool"</span>_hs);</div>
|
|
</div><!-- fragment --><p>If a name is not provided, the default storage associated with the given type is always returned.<br />
|
|
Since the storage are also self-contained, the registry does not <em>duplicate</em> its own API for them. However, there is still no limit to the possibilities of use:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> &&other = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<velocity>(<span class="stringliteral">"other"</span>_hs);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.emplace<velocity>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line">other.push(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
</div><!-- fragment --><p>Anything that can be done via the registry interface can also be done directly on the reference storage.<br />
|
|
On the other hand, those calls involving all storage are guaranteed to also <em>reach</em> manually created ones:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// removes the entity from both storage</span></div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.destroy(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
</div><!-- fragment --><p>Finally, a storage of this type works with any view (which also accepts multiple storages of the same type, if necessary):</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// direct initialization</span></div>
|
|
<div class="line"><a class="code hl_class" href="classentt_1_1basic__view.html">entt::basic_view</a> direct{</div>
|
|
<div class="line"> <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<velocity>(),</div>
|
|
<div class="line"> <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<velocity>(<span class="stringliteral">"other"</span>_hs)</div>
|
|
<div class="line">};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// concatenation</span></div>
|
|
<div class="line"><span class="keyword">auto</span> join = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<velocity>() | <a class="code hl_class" href="classentt_1_1basic__view.html">entt::basic_view</a>{<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<velocity>(<span class="stringliteral">"other"</span>_hs)};</div>
|
|
</div><!-- fragment --><p>The possibility of direct use of storage combined with the freedom of being able to create and use more than one of the same type opens the door to the use of <code>EnTT</code> <em>at runtime</em>, which was previously quite limited.</p>
|
|
<h1><a class="anchor" id="views-and-groups"></a>
|
|
Views and Groups</h1>
|
|
<p>Views are a non-intrusive tool for working with entities and components without affecting other functionalities or increasing memory consumption.<br />
|
|
Groups are an intrusive tool to use to improve performance along critical paths but which also has a price to pay for that.</p>
|
|
<p>There are mainly two kinds of views: <em>compile-time</em> (also known as <code>view</code>) and runtime (also known as <code>runtime_view</code>).<br />
|
|
The former requires a compile-time list of component (or storage) types and can make several optimizations because of that. The latter is constructed at runtime using numerical type identifiers instead and is a bit slower to iterate.<br />
|
|
In both cases, creating and destroying views is not expensive at all since they do not have any type of initialization.</p>
|
|
<p>Groups come in three different flavors: <em>full-owning groups</em>, <em>partial-owning groups</em> and <em>non-owning groups</em>. The main difference between them is in terms of performance.<br />
|
|
Groups can literally <em>own</em> one or more component types. They are allowed to rearrange pools so as to speed up iterations. Roughly speaking: the more components a group owns, the faster it is to iterate them.</p>
|
|
<h2><a class="anchor" id="views"></a>
|
|
Views</h2>
|
|
<p>Single type views and multi type views behave differently and also have slightly different APIs.</p>
|
|
<p>Single type views are specialized to give a performance boost in all cases. There is nothing as fast as a single type view. They just walk through packed (actually paged) arrays of elements and return them directly.<br />
|
|
This kind of views also allows getting the exact number of elements they are going to return.<br />
|
|
Refer to the inline documentation for all the details.</p>
|
|
<p>Multi type views iterate entities that have at least all the given components. During construction, they look at the number of elements available in each pool and use the smallest set in order to speed up iterations.<br />
|
|
This kind of views only allow to get the estimated number of elements they are going to return.<br />
|
|
Refer to the inline documentation for all the details.</p>
|
|
<p>Storing aside views is not required as they are extremely cheap to construct. In fact, this is even discouraged when creating a view from a const registry. Since all storage are lazily initialized, they may not exist when the view is created. Thus, while perfectly usable, the view may contain pending references that are never reinitialized with the actual storage.</p>
|
|
<p>Views share the way they are created by means of a registry:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// single type view</span></div>
|
|
<div class="line"><span class="keyword">auto</span> single = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// multi type view</span></div>
|
|
<div class="line"><span class="keyword">auto</span> multi = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position, velocity>();</div>
|
|
</div><!-- fragment --><p>Filtering entities by components is also supported:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position, velocity>(<a class="code hl_variable" href="namespaceentt.html#a5b73210cef43c4db35ef8ce477cc38a6">entt::exclude<renderable></a>);</div>
|
|
<div class="ttc" id="anamespaceentt_html_a3f86766cf81509c46f7009f90513d837"><div class="ttname"><a href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">entt::view</a></div><div class="ttdeci">basic_view< type_list_transform_t< Get, storage_for >, type_list_transform_t< Exclude, storage_for > > view</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00277">fwd.hpp:277</a></div></div>
|
|
</div><!-- fragment --><p>To iterate a view, either use it in a range-for loop:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position, velocity, renderable>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>: <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>) {</div>
|
|
<div class="line"> <span class="comment">// a component at a time ...</span></div>
|
|
<div class="line"> <span class="keyword">auto</span> &position = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get<position>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"> <span class="keyword">auto</span> &velocity = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get<velocity>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// ... multiple components ...</span></div>
|
|
<div class="line"> <span class="keyword">auto</span> [pos, vel] = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get<position, velocity>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// ... all components at once</span></div>
|
|
<div class="line"> <span class="keyword">auto</span> [pos, vel, rend] = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Or rely on the <code>each</code> member functions to iterate both entities and components at once:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// through a callback</span></div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position, velocity>().each([](<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>, <span class="keyword">auto</span> &pos, <span class="keyword">auto</span> &vel) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">});</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// using an input iterator</span></div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> &&[<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>, pos, vel]: <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position, velocity>().each()) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Note that entities can also be excluded from the parameter list when received through a callback and this can improve even further the performance during iterations.<br />
|
|
Since they are not explicitly instantiated, empty components are not returned in any case.</p>
|
|
<p>As a side note, in the case of single type views, <code>get</code> accepts but does not strictly require a template parameter, since the type is implicitly defined. However, when the type is not specified, the instance is returned using a tuple for consistency with multi type views:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<<span class="keyword">const</span> renderable>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>: <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>) {</div>
|
|
<div class="line"> <span class="keyword">auto</span> [renderable] = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p><b>Note</b>: prefer the <code>get</code> member function of a view instead of that of a registry during iterations to get the types iterated by the view itself.</p>
|
|
<h3><a class="anchor" id="create-once-reuse-many-times"></a>
|
|
Create once, reuse many times</h3>
|
|
<p>Views support lazy initialization as well as <em>storage swapping</em>.<br />
|
|
An empty (or partially initialized) view is such that it returns false when converted to bool (to let the user know that it is not fully initialized) but it also works as-is like any other view.</p>
|
|
<p>In order to initialize a view one piece at a time, it allows users to inject storage classes when available:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab7e07285e81bdf526b09a38a9618eb13">entt::storage_for_t<velocity></a> <a class="code hl_typedef" href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e">storage</a>{};</div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">entt::view<entt::get_t<position, velocity></a>> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>{};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.storage(<a class="code hl_typedef" href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e">storage</a>);</div>
|
|
<div class="ttc" id="anamespaceentt_html_ab7e07285e81bdf526b09a38a9618eb13"><div class="ttname"><a href="namespaceentt.html#ab7e07285e81bdf526b09a38a9618eb13">entt::storage_for_t</a></div><div class="ttdeci">typename storage_for< Args... >::type storage_for_t</div><div class="ttdoc">Helper type.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00269">fwd.hpp:269</a></div></div>
|
|
</div><!-- fragment --><p>If there are multiple storages of the same type, it is possible to disambiguate using the <em>index</em> of the element to be replaced:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.storage<1>(<a class="code hl_typedef" href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e">storage</a>);</div>
|
|
</div><!-- fragment --><p>The ability to literally <em>replace</em> a storage in a view also opens up its reuse with different sets of entities.<br />
|
|
For example, to <em>filter</em> a view based on two groups of entities with different characteristics, there will be no need to reinitialize anything:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">entt::view<entt::get<my_type, void></a>> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>{<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<my_type>>()};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab7e07285e81bdf526b09a38a9618eb13">entt::storage_for_t<void></a> the_good{};</div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab7e07285e81bdf526b09a38a9618eb13">entt::storage_for_t<void></a> the_bad{};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// initialize the sets above as needed</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.storage(the_good);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> [<a class="code hl_namespace" href="namespaceentt.html">entt</a>, elem]: <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>) {</div>
|
|
<div class="line"> <span class="comment">// the good entities with their components here</span></div>
|
|
<div class="line">}</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.storage(the_bad);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> [<a class="code hl_namespace" href="namespaceentt.html">entt</a>, elem]: <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>) {</div>
|
|
<div class="line"> <span class="comment">// the bad entities with their components here</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Finally, it should be noted that the lack of a storage is treated to all intents and purposes as if it were an <em>empty</em> element.<br />
|
|
Thus, a <em>get</em> storage (as in <code><a class="el" href="structentt_1_1get__t.html" title="Alias for lists of observed elements.">entt::get_t</a></code>) makes the view empty automatically while an <em>exclude</em> storage (as in <code><a class="el" href="structentt_1_1exclude__t.html" title="Alias for exclusion lists.">entt::exclude_t</a></code>) is ignored as if that part of the filter did not exist.</p>
|
|
<h3><a class="anchor" id="exclude-only"></a>
|
|
Exclude-only</h3>
|
|
<p><em>Exclude-only</em> views are not really a thing in <code>EnTT</code>.<br />
|
|
However, the same result can be achieved by combining the right storage into a simple view.</p>
|
|
<p>If one gets to the root of the problem, the purpose of an exclude-only view is to return entities that do not meet certain requirements.<br />
|
|
Since entity storage, unlike exclude-only views, <b>is</b> a thing in <code>EnTT</code>, users can leverage it for these kinds of queries. It is also guaranteed to be unique within a registry and is always accessible when creating a view:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>>(<a class="code hl_variable" href="namespaceentt.html#a5b73210cef43c4db35ef8ce477cc38a6">entt::exclude<my_type></a>);</div>
|
|
</div><!-- fragment --><p>The returned view is such that it will return only the entities that do not have the <code>my_type</code> component, regardless of what other components they have.</p>
|
|
<h3><a class="anchor" id="view-pack"></a>
|
|
View pack</h3>
|
|
<p>Views are combined with storage objects and with each other to create new, more specific <em>queries</em>.<br />
|
|
The type returned when combining multiple elements together is itself a view, more in general a multi component one.</p>
|
|
<p>Combining different elements tries to mimic C++20 ranges:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position>();</div>
|
|
<div class="line"><span class="keyword">auto</span> other = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<velocity>();</div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> &<a class="code hl_typedef" href="namespaceentt.html#aff8fd99fc1ff2432dcb0f6b017a9c60e">storage</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<renderable>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">auto</span> pack = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a> | other | renderable;</div>
|
|
</div><!-- fragment --><p>The constness of the types is preserved and their order depends on the order in which the views are combined. For example, the above <em>pack</em> first returns an instance of <code>position</code>, then one of <code>velocity</code>, and finally one of <code>renderable</code>.<br />
|
|
Since combining elements generates views, a chain can be of arbitrary length and the above type order rules apply sequentially.</p>
|
|
<h3><a class="anchor" id="iteration-order"></a>
|
|
Iteration order</h3>
|
|
<p>By default, a view is iterated along the pool that contains the smallest number of elements.<br />
|
|
For example, if the registry contains fewer <code>velocity</code>s than it contains <code>position</code>s, then the order of the elements returned by the following view depends on how the <code>velocity</code> components are arranged in their pool:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>: <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<positon, velocity>()) { </div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Moreover, the order of types when constructing a view does not matter. Neither does the order of views in a view pack.<br />
|
|
However, it is possible to <em>enforce</em> iteration of a view by given component order by means of the <code>use</code> function:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position, velocity>();</div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.use<position>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>: <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>On the other hand, if all a user wants is to iterate the elements in reverse order, this is possible for a single type view using its reverse iterators:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> it = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.rbegin(), last = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.rend(); it != last; ++iter) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Unfortunately, multi type views do not offer reverse iterators. Therefore, in this case it is a must to implement this functionality manually or to use single type views to lead the iteration.</p>
|
|
<h3><a class="anchor" id="runtime-views"></a>
|
|
Runtime views</h3>
|
|
<p>Multi type views iterate entities that have at least all the given components. During construction, they look at the number of elements available in each pool and use the smallest set in order to speed up iterations.<br />
|
|
They offer more or less the same functionalities of a multi type view. However, they do not expose a <code>get</code> member function and users should refer to the registry that generated the view to access components.<br />
|
|
Refer to the inline documentation for all the details.</p>
|
|
<p>Runtime views are pretty cheap to construct and should not be stored aside in any case. They should be used immediately after creation and then they should be thrown away.<br />
|
|
To iterate a runtime view, either use it in a range-for loop:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#ae7874d535e3193cbc008ef5c7f02829d">entt::runtime_view</a> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>{};</div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.iterate(<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<position>()).iterate(<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<velocity>());</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>: <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="anamespaceentt_html_ae7874d535e3193cbc008ef5c7f02829d"><div class="ttname"><a href="namespaceentt.html#ae7874d535e3193cbc008ef5c7f02829d">entt::runtime_view</a></div><div class="ttdeci">basic_runtime_view< sparse_set > runtime_view</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00130">fwd.hpp:130</a></div></div>
|
|
</div><!-- fragment --><p>Or rely on the <code>each</code> member function to iterate entities:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#ae7874d535e3193cbc008ef5c7f02829d">entt::runtime_view</a>{}</div>
|
|
<div class="line"> .iterate(<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<position>())</div>
|
|
<div class="line"> .iterate(<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<velocity>())</div>
|
|
<div class="line"> .each([](<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line"> });</div>
|
|
</div><!-- fragment --><p>Performance are exactly the same in both cases.<br />
|
|
Filtering entities by components is also supported for this kind of views:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#ae7874d535e3193cbc008ef5c7f02829d">entt::runtime_view</a> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>{};</div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.iterate(<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<position>()).exclude(<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.storage<velocity>());</div>
|
|
</div><!-- fragment --><p>Runtime views are meant for when users do not know at compile-time what types to <em>use</em> to iterate entities. The <code>storage</code> member function of a registry could be useful in this regard.</p>
|
|
<h2><a class="anchor" id="groups"></a>
|
|
Groups</h2>
|
|
<p>Groups are meant to iterate multiple components at once and to offer a faster alternative to multi type views.<br />
|
|
Groups overcome the performance of the other tools available but require to get the ownership of components. This sets some constraints on their pools. On the other hand, groups are not an automatism that increases memory consumption, affects functionalities and tries to optimize iterations for all the possible combinations of components. Users can decide when to pay for groups and to what extent.<br />
|
|
The most interesting aspect of groups is that they fit <em>usage patterns</em>. Other solutions around usually try to optimize everything, because it is known that somewhere within the <em>everything</em> there are also our usage patterns. However this has a cost that is not negligible, both in terms of performance and memory usage. Ironically, users pay the price also for things they do not want and this is not something I like much. Even worse, one cannot easily disable such a behavior. Groups work differently instead and are designed to optimize only the real use cases when users find they need to.<br />
|
|
Another nice-to-have feature of groups is that they have no impact on memory consumption, put aside full non-owning groups that are pretty rare and should be avoided as long as possible.</p>
|
|
<p>All groups affect to an extent the creation and destruction of their components. This is due to the fact that they must <em>observe</em> changes in the pools of interest and arrange data <em>correctly</em> when needed for the types they own.<br />
|
|
In all cases, a group allows to get the exact number of elements it is going to return.<br />
|
|
Refer to the inline documentation for all the details.</p>
|
|
<p>Storing aside groups is not required as they are extremely cheap to create, even though valid groups can be copied without problems and reused freely.<br />
|
|
A group performs an initialization step the very first time it is requested and this could be quite costly. To avoid it, consider creating the group when no components have been assigned yet. If the registry is empty, preparation is extremely fast.</p>
|
|
<p>To iterate a group, either use it in a range-for loop:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.group<position>(<a class="code hl_variable" href="namespaceentt.html#a8c24ecc5ab0055f9f2a4725c95afb29e">entt::get<velocity, renderable></a>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>: <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a>) {</div>
|
|
<div class="line"> <span class="comment">// a component at a time ...</span></div>
|
|
<div class="line"> <span class="keyword">auto</span> &position = <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a>.get<position>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"> <span class="keyword">auto</span> &velocity = <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a>.get<velocity>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// ... multiple components ...</span></div>
|
|
<div class="line"> <span class="keyword">auto</span> [pos, vel] = <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a>.get<position, velocity>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// ... all components at once</span></div>
|
|
<div class="line"> <span class="keyword">auto</span> [pos, vel, rend] = <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a>.get(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="anamespaceentt_html_a7e718d299437d564f6c3891c4c230f06"><div class="ttname"><a href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">entt::group</a></div><div class="ttdeci">basic_group< type_list_transform_t< Owned, storage_for >, type_list_transform_t< Get, storage_for >, type_list_transform_t< Exclude, storage_for > > group</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00286">fwd.hpp:286</a></div></div>
|
|
<div class="ttc" id="anamespaceentt_html_a8c24ecc5ab0055f9f2a4725c95afb29e"><div class="ttname"><a href="namespaceentt.html#a8c24ecc5ab0055f9f2a4725c95afb29e">entt::get</a></div><div class="ttdeci">constexpr get_t< Type... > get</div><div class="ttdoc">Variable template for lists of observed elements.</div><div class="ttdef"><b>Definition</b> <a href="entity_2fwd_8hpp_source.html#l00167">fwd.hpp:167</a></div></div>
|
|
</div><!-- fragment --><p>Or rely on the <code>each</code> member functions to iterate both entities and components at once:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// through a callback</span></div>
|
|
<div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.group<position>(<a class="code hl_variable" href="namespaceentt.html#a8c24ecc5ab0055f9f2a4725c95afb29e">entt::get<velocity></a>).each([](<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>, <span class="keyword">auto</span> &pos, <span class="keyword">auto</span> &vel) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">});</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// using an input iterator</span></div>
|
|
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> &&[<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>, pos, vel]: <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.group<position>(<a class="code hl_variable" href="namespaceentt.html#a8c24ecc5ab0055f9f2a4725c95afb29e">entt::get<velocity></a>).each()) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Note that entities can also be excluded from the parameter list when received through a callback and this can improve even further the performance during iterations.<br />
|
|
Since they are not explicitly instantiated, empty components are not returned in any case.</p>
|
|
<p><b>Note</b>: prefer the <code>get</code> member function of a group instead of that of a registry during iterations to get the types iterated by the group itself.</p>
|
|
<h3><a class="anchor" id="full-owning-groups"></a>
|
|
Full-owning groups</h3>
|
|
<p>A full-owning group is the fastest tool a user can expect to use to iterate multiple components at once. It iterates all the components directly, no indirection required.<br />
|
|
This type of groups performs more or less as if users are accessing sequentially a bunch of packed arrays of components all sorted identically, with no jumps nor branches.</p>
|
|
<p>A full-owning group is created as:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.group<position, velocity>();</div>
|
|
</div><!-- fragment --><p>Filtering entities by components is also supported:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.group<position, velocity>({}, <a class="code hl_variable" href="namespaceentt.html#a5b73210cef43c4db35ef8ce477cc38a6">entt::exclude<renderable></a>);</div>
|
|
</div><!-- fragment --><p>Once created, the group gets the ownership of all the components specified in the template parameter list and arranges their pools as needed.</p>
|
|
<p>Sorting owned components is no longer allowed once the group has been created. However, full-owning groups are sorted using their <code>sort</code> member functions. Sorting a full-owning group affects all its instances.</p>
|
|
<h3><a class="anchor" id="partial-owning-groups"></a>
|
|
Partial-owning groups</h3>
|
|
<p>A partial-owning group works similarly to a full-owning group for the components it owns, but relies on indirection to get components owned by other groups.<br />
|
|
This is not as fast as a full-owning group, but it is already much faster than a view when there are only one or two free components to retrieve (the most common cases likely). In the worst case, it is not slower than views anyway.</p>
|
|
<p>A partial-owning group is created as:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.group<position>(<a class="code hl_variable" href="namespaceentt.html#a8c24ecc5ab0055f9f2a4725c95afb29e">entt::get<velocity></a>);</div>
|
|
</div><!-- fragment --><p>Filtering entities by components is also supported:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.group<position>(<a class="code hl_variable" href="namespaceentt.html#a8c24ecc5ab0055f9f2a4725c95afb29e">entt::get<velocity></a>, <a class="code hl_variable" href="namespaceentt.html#a5b73210cef43c4db35ef8ce477cc38a6">entt::exclude<renderable></a>);</div>
|
|
</div><!-- fragment --><p>Once created, the group gets the ownership of all the components specified in the template parameter list and arranges their pools as needed. The ownership of the types provided via <code><a class="el" href="namespaceentt.html#a8c24ecc5ab0055f9f2a4725c95afb29e" title="Variable template for lists of observed elements.">entt::get</a></code> does not pass to the group instead.</p>
|
|
<p>Sorting owned components is no longer allowed once the group has been created. However, partial-owning groups are sorted using their <code>sort</code> member functions. Sorting a partial-owning group affects all its instances.</p>
|
|
<h3><a class="anchor" id="non-owning-groups"></a>
|
|
Non-owning groups</h3>
|
|
<p>Non-owning groups are usually fast enough, for sure faster than views and well suited for most of the cases. However, they require custom data structures to work properly and they increase memory consumption.<br />
|
|
As a rule of thumb, users should avoid using non-owning groups, if possible.</p>
|
|
<p>A non-owning group is created as:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.group<>(<a class="code hl_variable" href="namespaceentt.html#a8c24ecc5ab0055f9f2a4725c95afb29e">entt::get<position, velocity></a>);</div>
|
|
</div><!-- fragment --><p>Filtering entities by components is also supported:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a7e718d299437d564f6c3891c4c230f06">group</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.group<>(<a class="code hl_variable" href="namespaceentt.html#a8c24ecc5ab0055f9f2a4725c95afb29e">entt::get<position, velocity></a>, <a class="code hl_variable" href="namespaceentt.html#a5b73210cef43c4db35ef8ce477cc38a6">entt::exclude<renderable></a>);</div>
|
|
</div><!-- fragment --><p>The group does not receive the ownership of any type of component in this case. This type of groups is therefore the least performing in general, but also the only one that can be used in any situation to slightly improve performance.</p>
|
|
<p>Non-owning groups are sorted using their <code>sort</code> member functions. Sorting a non-owning group affects all its instances.</p>
|
|
<h2><a class="anchor" id="types-const-non-const-and-all-in-between"></a>
|
|
Types: const, non-const and all in between</h2>
|
|
<p>The <code>registry</code> class offers two overloads when it comes to constructing views and groups: a const version and a non-const one. The former accepts only const types as template parameters, the latter accepts both const and non-const types instead.<br />
|
|
It means that views and groups generated by a const registry also propagate the constness to the types involved. As an example:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">entt::view<const position, const velocity></a> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a> = std::as_const(<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>).view<<span class="keyword">const</span> position, <span class="keyword">const</span> velocity>();</div>
|
|
</div><!-- fragment --><p>Consider the following definition for a non-const view instead:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">entt::view<position, const velocity></a> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position, <span class="keyword">const</span> velocity>();</div>
|
|
</div><!-- fragment --><p>In the example above, <code>view</code> is used to access either read-only or writable <code>position</code> components while <code>velocity</code> components are read-only in all cases.<br />
|
|
Similarly, these statements are all valid:</p>
|
|
<div class="fragment"><div class="line">position &pos = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get<position>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"><span class="keyword">const</span> position &cpos = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get<<span class="keyword">const</span> position>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"><span class="keyword">const</span> velocity &cpos = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get<<span class="keyword">const</span> velocity>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line">std::tuple<position &, const velocity &> tup = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get<position, <span class="keyword">const</span> velocity>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line">std::tuple<const position &, const velocity &> ctup = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get<<span class="keyword">const</span> position, <span class="keyword">const</span> velocity>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
</div><!-- fragment --><p>It is not possible to get non-const references to <code>velocity</code> components from the same view instead. Therefore, these result in compilation errors:</p>
|
|
<div class="fragment"><div class="line">velocity &cpos = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get<velocity>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line">std::tuple<position &, velocity &> tup = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get<position, velocity>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line">std::tuple<const position &, velocity &> ctup = <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.get<<span class="keyword">const</span> position, velocity>(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
</div><!-- fragment --><p>The <code>each</code> member functions also propagates constness to its <em>return values</em>:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.each([](<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>, position &pos, <span class="keyword">const</span> velocity &vel) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">});</div>
|
|
</div><!-- fragment --><p>A caller can still refer to the <code>position</code> components through a const reference because of the rules of the language that fortunately already allow it.</p>
|
|
<p>The same concepts apply to groups as well.</p>
|
|
<h2><a class="anchor" id="give-me-everything"></a>
|
|
Give me everything</h2>
|
|
<p>Views and groups are narrow windows on the entire list of entities. They work by filtering entities according to their components.<br />
|
|
In some cases there may be the need to iterate all the entities still in use regardless of their components. This is done by accessing entity storage:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>: <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>>()) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>As a rule of thumb, consider using a view or a group if the goal is to iterate entities that have a determinate set of components. These tools are usually much faster than filtering entities with a bunch of custom tests.<br />
|
|
In all the other cases, this is the way to go. For example, it is possible to combine this view with the <code>orphan</code> member function to clean up orphan entities (that is, entities that are still in use and have no assigned components):</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>: <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>>()) {</div>
|
|
<div class="line"> <span class="keywordflow">if</span>(<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.orphan(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>)) {</div>
|
|
<div class="line"> <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.release(<a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"> }</div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>In general, iterating all entities can result in poor performance. It should not be done frequently to avoid the risk of a performance hit.<br />
|
|
However, it is convenient when initializing an editor or to reclaim pending identifiers.</p>
|
|
<h2><a class="anchor" id="what-is-allowed-and-what-is-not"></a>
|
|
What is allowed and what is not</h2>
|
|
<p>Most of the <em>ECS</em> available out there do not allow to create and destroy entities and components during iterations, nor to have pointer stability.<br />
|
|
<code>EnTT</code> partially solves the problem with a few limitations:</p>
|
|
<ul>
|
|
<li>Creating entities and components is allowed during iterations in most cases and it never invalidates already existing references.</li>
|
|
<li>Deleting the current entity or removing its components is allowed during iterations but it could invalidate references. For all the other entities, destroying them or removing their iterated components is not allowed and can result in undefined behavior.</li>
|
|
<li>When pointer stability is enabled for the type leading the iteration, adding instances of the same type may or may not cause the entity involved to be returned. Destroying entities and components is always allowed instead, even if not currently iterated, without the risk of invalidating any references.</li>
|
|
<li>In case of reverse iterations, adding or removing elements is not allowed under any circumstances. It could quickly lead to undefined behaviors.</li>
|
|
</ul>
|
|
<p>In other terms, iterators are rarely invalidated. Also, component references are not invalidated when a new element is added while they could be invalidated upon destruction due to the <em>swap-and-pop</em> policy, unless the type leading the iteration undergoes in-place deletion.<br />
|
|
As an example, consider the following snippet:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position>().each([&](<span class="keyword">const</span> <span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>, <span class="keyword">auto</span> &pos) {</div>
|
|
<div class="line"> <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.emplace<position>(<a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.create(), 0., 0.);</div>
|
|
<div class="line"> <span class="comment">// references remain stable after adding new instances</span></div>
|
|
<div class="line"> pos.x = 0.;</div>
|
|
<div class="line">});</div>
|
|
</div><!-- fragment --><p>The <code>each</code> member function will not break (because iterators remain valid) nor will any reference be invalidated. Instead, more attention should be paid to the destruction of entities or the removal of components.<br />
|
|
Use a common range-for loop and get components directly from the view or move the deletion of entities and components at the end of the function to avoid dangling pointers.</p>
|
|
<p>For all types that do not offer stable pointers, iterators are also invalidated and the behavior is undefined if an entity is modified or destroyed and it is not the one currently returned by the iterator nor a newly created one.<br />
|
|
To work around it, possible approaches are:</p>
|
|
<ul>
|
|
<li>Store aside the entities and the components to be removed and perform the operations at the end of the iteration.</li>
|
|
<li>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.</li>
|
|
</ul>
|
|
<p>A notable side effect of this feature is that the number of required allocations is further reduced in most cases.</p>
|
|
<h3><a class="anchor" id="more-performance-more-constraints"></a>
|
|
More performance, more constraints</h3>
|
|
<p>Groups are a faster alternative to views. However, the higher the performance, the greater the constraints on what is allowed and what is not.<br />
|
|
In particular, groups add in some rare cases a limitation on the creation of components during iterations. It happens in quite particular cases. Given the nature and the scope of the groups, it is not something in which it will happen to come across probably, but it is good to know it anyway.</p>
|
|
<p>First of all, it must be said that creating components while iterating a group is not a problem at all and is done freely as it happens with the views. The same applies to the destruction of components and entities, for which the rules mentioned above apply.</p>
|
|
<p>The additional limitation arises instead when a given component that is owned by a group is iterated outside of it. In this case, adding components that are part of the group itself may invalidate the iterators. There are no further limitations to the destruction of components and entities.<br />
|
|
Fortunately, this is not always true. In fact, it almost never is and only happens under certain conditions. In particular:</p>
|
|
<ul>
|
|
<li>Iterating a type of component that is part of a group with a single type view and adding to an entity all the components required to get it into the group may invalidate the iterators.</li>
|
|
<li>Iterating a type of component that is part of a group with a multi type view and adding to an entity all the components required to get it into the group can invalidate the iterators, unless users specify another type of component to use to induce the order of iteration of the view (in this case, the former is treated as a free type and is not affected by the limitation).</li>
|
|
</ul>
|
|
<p>In other words, the limitation does not exist as long as a type is treated as a free type (as an example with multi type views and partial- or non-owning groups) or iterated with its own group, but it can occur if the type is used as a main type to rule on an iteration.<br />
|
|
This happens because groups own the pools of their components and organize the data internally to maximize performance. Because of that, full consistency for owned components is guaranteed only when they are iterated as part of their groups or as free types with multi type views and groups in general.</p>
|
|
<h1><a class="anchor" id="multithreading"></a>
|
|
Multithreading</h1>
|
|
<p>In general, the entire registry is not thread safe as it is. Thread safety is not something that users should want out of the box for several reasons. Just to mention one of them: performance.<br />
|
|
Views, groups and consequently the approach adopted by <code>EnTT</code> are the great exception to the rule. It is true that views, groups and iterators in general are not thread safe by themselves. Because of this users should not try to iterate a set of components and modify the same set concurrently. However:</p>
|
|
<ul>
|
|
<li>As long as a thread iterates the entities that have the component <code>X</code> or assign and removes that component from a set of entities, another thread can safely do the same with components <code>Y</code> and <code>Z</code> and everything work like just fine. 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.</li>
|
|
<li>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.</li>
|
|
</ul>
|
|
<p>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 <em>ECS</em> do not 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.</p>
|
|
<p>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.</p>
|
|
<p>Finally, <code>EnTT</code> is configured via a few compile-time definitions to make some of its parts implicitly thread-safe, roughly speaking only the ones that really make sense and cannot be turned around.<br />
|
|
In particular, when multiple instances of objects referencing the type index generator (such as the <code>registry</code> class) are used in different threads, then it might be useful to define <code>ENTT_USE_ATOMIC</code>.<br />
|
|
See the relevant documentation for more information.</p>
|
|
<h2><a class="anchor" id="iterators-1"></a>
|
|
Iterators</h2>
|
|
<p>A special mention is needed for the iterators returned by views and groups. Most of the time they meet the requirements of random access iterators, in all cases they meet at least the requirements of forward iterators.<br />
|
|
In other terms, they are suitable for use with the parallel algorithms of the standard library. If it is not clear, this is a great thing.</p>
|
|
<p>As an example, this kind of iterators are used in combination with <code>std::for_each</code> and <code>std::execution::par</code> to parallelize the visit and therefore the update of the components returned by a view or a group, as long as the constraints previously discussed are respected:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a> = <a class="code hl_typedef" href="namespaceentt.html#ab8c1f492841aeafa5e75422af3f0cdc4">registry</a>.view<position, <span class="keyword">const</span> velocity>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line">std::for_each(std::execution::par_unseq, <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.begin(), <a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>.end(), [&<a class="code hl_typedef" href="namespaceentt.html#a3f86766cf81509c46f7009f90513d837">view</a>](<span class="keyword">auto</span> <a class="code hl_enumeration" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">});</div>
|
|
</div><!-- fragment --><p>This can increase the throughput considerably, even without resorting to who knows what artifacts that are difficult to maintain over time.</p>
|
|
<p>Unfortunately, because of the limitations of the current revision of the standard, the parallel <code>std::for_each</code> accepts only forward iterators. This means that the default iterators provided by the library cannot return proxy objects as references and <b>must</b> return actual reference types instead.<br />
|
|
This may change in the future and the iterators will almost certainly return both the entities and a list of references to their components by default sooner or later. Multi-pass guarantee will not break in any case and the performance should even benefit from it further.</p>
|
|
<h2><a class="anchor" id="const-registry"></a>
|
|
Const registry</h2>
|
|
<p>A const registry is also fully thread safe. This means that it is not able to lazily initialize a missing storage when a view is generated.<br />
|
|
The reason for this is easy to explain. To avoid requiring types to be <em>announced</em> in advance, a registry lazily creates the storage objects for the different components. However, this is not possible for a thread safe const registry.</p>
|
|
<p>Returned views are always valid and behave as expected in the context of the caller. However, they may contain dangling references to non-existing storage when created from a const registry.<br />
|
|
As a result, such a view may misbehave over time if it is kept aside for a second use.<br />
|
|
Therefore, if the general advice is to create views when necessary and discard them immediately afterwards, this becomes almost a rule when it comes to views generated from a const registry.</p>
|
|
<p>Fortunately, there is also a way to instantiate storage classes early when in doubt or when there are special requirements.<br />
|
|
Calling the <code>storage</code> method is equivalent to <em>announcing</em> a particular storage, so as to avoid running into problems. For those interested, there are also alternative approaches, such as a single threaded tick for the registry warm-up, but these are not always applicable.<br />
|
|
In this case, views never risk becoming <em>invalid</em>.</p>
|
|
<h1><a class="anchor" id="beyond-this-document"></a>
|
|
Beyond this document</h1>
|
|
<p>There are many other features and functions not listed in this document.<br />
|
|
<code>EnTT</code> and in particular its ECS part is in continuous development and some things could be forgotten, others could have been omitted on purpose to reduce the size of this file. Unfortunately, some parts may even be outdated and still to be updated.</p>
|
|
<p>For further information, it is recommended to refer to the documentation included in the code itself or join the official channels to ask a question. </p>
|
|
</div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.13.2
|
|
</small></address>
|
|
</div><!-- doc-content -->
|
|
</body>
|
|
</html>
|