Files
entt/README_8md_source.html
2017-10-13 14:00:07 +02:00

75 lines
69 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>entt: README.md Source File</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>
<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.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 style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">entt
&#160;<span id="projectnumber">2.0.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- 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">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">README.md</div> </div>
</div><!--header-->
<div class="contents">
<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span>&#160;# The EnTT Framework</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span>&#160;</div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span>&#160;[![Build Status](https://travis-ci.org/skypjack/entt.svg?branch=master)](https://travis-ci.org/skypjack/entt)</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>&#160;[![Build status](https://ci.appveyor.com/api/projects/status/rvhaabjmghg715ck?svg=true)](https://ci.appveyor.com/project/skypjack/entt)</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span>&#160;[![Coverage Status](https://coveralls.io/repos/github/skypjack/entt/badge.svg?branch=master)](https://coveralls.io/github/skypjack/entt?branch=master)</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span>&#160;[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&amp;business=W2HF9FESD5LJY&amp;lc=IT&amp;item_name=Michele%20Caini&amp;currency_code=EUR&amp;bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)</div><div class="line"><a name="l00007"></a><span class="lineno"> 7</span>&#160;</div><div class="line"><a name="l00008"></a><span class="lineno"> 8</span>&#160;# Introduction</div><div class="line"><a name="l00009"></a><span class="lineno"> 9</span>&#160;</div><div class="line"><a name="l00010"></a><span class="lineno"> 10</span>&#160;`EnTT` is a header-only, tiny and easy to use framework written in modern C++.&lt;br/&gt;</div><div class="line"><a name="l00011"></a><span class="lineno"> 11</span>&#160;It&#39;s entirely designed around an architectural pattern pattern called _ECS_ that is used mostly in game development. For further details:</div><div class="line"><a name="l00012"></a><span class="lineno"> 12</span>&#160;</div><div class="line"><a name="l00013"></a><span class="lineno"> 13</span>&#160;* [Entity Systems Wiki](http://entity-systems.wikidot.com/)</div><div class="line"><a name="l00014"></a><span class="lineno"> 14</span>&#160;* [Evolve Your Hierarchy](http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/)</div><div class="line"><a name="l00015"></a><span class="lineno"> 15</span>&#160;* [ECS on Wikipedia](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system)</div><div class="line"><a name="l00016"></a><span class="lineno"> 16</span>&#160;</div><div class="line"><a name="l00017"></a><span class="lineno"> 17</span>&#160;Originally, `EnTT` was written as a faster alternative to other well known and open source entity-component systems.&lt;br/&gt;</div><div class="line"><a name="l00018"></a><span class="lineno"> 18</span>&#160;After a while the codebase has grown and more features have become part of the framework.</div><div class="line"><a name="l00019"></a><span class="lineno"> 19</span>&#160;</div><div class="line"><a name="l00020"></a><span class="lineno"> 20</span>&#160;## Code Example</div><div class="line"><a name="l00021"></a><span class="lineno"> 21</span>&#160;</div><div class="line"><a name="l00022"></a><span class="lineno"> 22</span>&#160;```cpp</div><div class="line"><a name="l00023"></a><span class="lineno"> 23</span>&#160;#include &lt;registry.hpp&gt;</div><div class="line"><a name="l00024"></a><span class="lineno"> 24</span>&#160;</div><div class="line"><a name="l00025"></a><span class="lineno"> 25</span>&#160;struct Position {</div><div class="line"><a name="l00026"></a><span class="lineno"> 26</span>&#160; float x;</div><div class="line"><a name="l00027"></a><span class="lineno"> 27</span>&#160; float y;</div><div class="line"><a name="l00028"></a><span class="lineno"> 28</span>&#160;};</div><div class="line"><a name="l00029"></a><span class="lineno"> 29</span>&#160;</div><div class="line"><a name="l00030"></a><span class="lineno"> 30</span>&#160;struct Velocity {</div><div class="line"><a name="l00031"></a><span class="lineno"> 31</span>&#160; float dx;</div><div class="line"><a name="l00032"></a><span class="lineno"> 32</span>&#160; float dy;</div><div class="line"><a name="l00033"></a><span class="lineno"> 33</span>&#160;};</div><div class="line"><a name="l00034"></a><span class="lineno"> 34</span>&#160;</div><div class="line"><a name="l00035"></a><span class="lineno"> 35</span>&#160;void update(entt::DefaultRegistry &amp;registry) {</div><div class="line"><a name="l00036"></a><span class="lineno"> 36</span>&#160; auto view = ecs.view&lt;Position, Velocity&gt;();</div><div class="line"><a name="l00037"></a><span class="lineno"> 37</span>&#160;</div><div class="line"><a name="l00038"></a><span class="lineno"> 38</span>&#160; for(auto entity: view) {</div><div class="line"><a name="l00039"></a><span class="lineno"> 39</span>&#160; auto &amp;position = view.get&lt;Position&gt;(entity);</div><div class="line"><a name="l00040"></a><span class="lineno"> 40</span>&#160; auto &amp;velocity = view.get&lt;Velocity&gt;(entity);</div><div class="line"><a name="l00041"></a><span class="lineno"> 41</span>&#160; // ...</div><div class="line"><a name="l00042"></a><span class="lineno"> 42</span>&#160; }</div><div class="line"><a name="l00043"></a><span class="lineno"> 43</span>&#160;}</div><div class="line"><a name="l00044"></a><span class="lineno"> 44</span>&#160;</div><div class="line"><a name="l00045"></a><span class="lineno"> 45</span>&#160;int main() {</div><div class="line"><a name="l00046"></a><span class="lineno"> 46</span>&#160; entt::DefaultRegistry registry;</div><div class="line"><a name="l00047"></a><span class="lineno"> 47</span>&#160;</div><div class="line"><a name="l00048"></a><span class="lineno"> 48</span>&#160; for(auto i = 0; i &lt; 10; ++i) {</div><div class="line"><a name="l00049"></a><span class="lineno"> 49</span>&#160; auto entity = registry.create();</div><div class="line"><a name="l00050"></a><span class="lineno"> 50</span>&#160; registry.assign&lt;Position&gt;(entity, i * 1.f, i * 1.f);</div><div class="line"><a name="l00051"></a><span class="lineno"> 51</span>&#160; if(i % 2 == 0) { registry.assign&lt;Velocity&gt;(entity, i * .1f, i * .1f); }</div><div class="line"><a name="l00052"></a><span class="lineno"> 52</span>&#160; }</div><div class="line"><a name="l00053"></a><span class="lineno"> 53</span>&#160;</div><div class="line"><a name="l00054"></a><span class="lineno"> 54</span>&#160; update(registry);</div><div class="line"><a name="l00055"></a><span class="lineno"> 55</span>&#160; // ...</div><div class="line"><a name="l00056"></a><span class="lineno"> 56</span>&#160;}</div><div class="line"><a name="l00057"></a><span class="lineno"> 57</span>&#160;```</div><div class="line"><a name="l00058"></a><span class="lineno"> 58</span>&#160;</div><div class="line"><a name="l00059"></a><span class="lineno"> 59</span>&#160;## Motivation</div><div class="line"><a name="l00060"></a><span class="lineno"> 60</span>&#160;</div><div class="line"><a name="l00061"></a><span class="lineno"> 61</span>&#160;I started working on `EnTT` because of the wrong reason: my goal was to design an entity-component system that beated another well known open source solution in terms of performance.&lt;br/&gt;</div><div class="line"><a name="l00062"></a><span class="lineno"> 62</span>&#160;I did it, of course, but it wasn&#39;t much satisfying. Actually it wasn&#39;t satisfying at all. The fastest and nothing more, fairly little indeed.</div><div class="line"><a name="l00063"></a><span class="lineno"> 63</span>&#160;When I realized it, I tried hard to keep intact the great performance of `EnTT` and to add all the features I wanted to see in *my* entity-component system at the same time.</div><div class="line"><a name="l00064"></a><span class="lineno"> 64</span>&#160;</div><div class="line"><a name="l00065"></a><span class="lineno"> 65</span>&#160;Today `EnTT` is finally what I was looking for: still faster than its _rivals_, a really good API and an amazing set of features. And even more, of course.</div><div class="line"><a name="l00066"></a><span class="lineno"> 66</span>&#160;</div><div class="line"><a name="l00067"></a><span class="lineno"> 67</span>&#160;### Performance</div><div class="line"><a name="l00068"></a><span class="lineno"> 68</span>&#160;</div><div class="line"><a name="l00069"></a><span class="lineno"> 69</span>&#160;As it stands right now, `EnTT` is just fast enough for my requirements if compared to my first choice (that was already amazingly fast indeed).&lt;br/&gt;</div><div class="line"><a name="l00070"></a><span class="lineno"> 70</span>&#160;Here is a comparision between the two (both of them compiled with GCC 7.2.0 on a Dell XPS 13 out of the mid 2014):</div><div class="line"><a name="l00071"></a><span class="lineno"> 71</span>&#160;</div><div class="line"><a name="l00072"></a><span class="lineno"> 72</span>&#160;| Benchmark | EntityX (experimental/compile_time) | EnTT |</div><div class="line"><a name="l00073"></a><span class="lineno"> 73</span>&#160;|-----------|-------------|-------------|</div><div class="line"><a name="l00074"></a><span class="lineno"> 74</span>&#160;| Creating 10M entities | 0.128881s | **0.0408754s** |</div><div class="line"><a name="l00075"></a><span class="lineno"> 75</span>&#160;| Destroying 10M entities | **0.0531374s** | 0.0545839s |</div><div class="line"><a name="l00076"></a><span class="lineno"> 76</span>&#160;| Iterating over 10M entities, unpacking one component, standard view | 0.010661s | **1.58e-07s** |</div><div class="line"><a name="l00077"></a><span class="lineno"> 77</span>&#160;| Iterating over 10M entities, unpacking two components, standard view | **0.0112664s** | 0.0840068s |</div><div class="line"><a name="l00078"></a><span class="lineno"> 78</span>&#160;| Iterating over 10M entities, unpacking two components, standard view, half of the entities have all the components | **0.0077951s** | 0.042168s |</div><div class="line"><a name="l00079"></a><span class="lineno"> 79</span>&#160;| Iterating over 10M entities, unpacking two components, standard view, one of the entities has all the components | 0.00713398s | **8.93e-07s** |</div><div class="line"><a name="l00080"></a><span class="lineno"> 80</span>&#160;| Iterating over 10M entities, unpacking two components, persistent view | 0.0112664s | **5.68e-07s** |</div><div class="line"><a name="l00081"></a><span class="lineno"> 81</span>&#160;| Iterating over 10M entities, unpacking five components, standard view | **0.00905084s** | 0.137757s |</div><div class="line"><a name="l00082"></a><span class="lineno"> 82</span>&#160;| Iterating over 10M entities, unpacking five components, persistent view | 0.00905084s | **2.9e-07s** |</div><div class="line"><a name="l00083"></a><span class="lineno"> 83</span>&#160;| Iterating over 10M entities, unpacking ten components, standard view | **0.0104708s** | 0.388602s |</div><div class="line"><a name="l00084"></a><span class="lineno"> 84</span>&#160;| Iterating over 10M entities, unpacking ten components, standard view, half of the entities have all the components | **0.00899859s** | 0.200752s |</div><div class="line"><a name="l00085"></a><span class="lineno"> 85</span>&#160;| Iterating over 10M entities, unpacking ten components, standard view, one of the entities has all the components | 0.00700349s | **2.565e-06s** |</div><div class="line"><a name="l00086"></a><span class="lineno"> 86</span>&#160;| Iterating over 10M entities, unpacking ten components, persistent view | 0.0104708s | **6.23e-07s** |</div><div class="line"><a name="l00087"></a><span class="lineno"> 87</span>&#160;| Iterating over 50M entities, unpacking one component, standard view | 0.055194s | **2.87e-07s** |</div><div class="line"><a name="l00088"></a><span class="lineno"> 88</span>&#160;| Iterating over 50M entities, unpacking two components, standard view | **0.0533921s** | 0.243197s |</div><div class="line"><a name="l00089"></a><span class="lineno"> 89</span>&#160;| Iterating over 50M entities, unpacking two components, persistent view | 0.055194s | **4.47e-07s** |</div><div class="line"><a name="l00090"></a><span class="lineno"> 90</span>&#160;| Sort 150k entities, one component | - | **0.0080046s** |</div><div class="line"><a name="l00091"></a><span class="lineno"> 91</span>&#160;| Sort 150k entities, match two components | - | **0.00608322s** |</div><div class="line"><a name="l00092"></a><span class="lineno"> 92</span>&#160;</div><div class="line"><a name="l00093"></a><span class="lineno"> 93</span>&#160;`EnTT` includes its own tests and benchmarks. See [benchmark.cpp](https://github.com/skypjack/entt/blob/master/test/benchmark.cpp) for further details.&lt;br/&gt;</div><div class="line"><a name="l00094"></a><span class="lineno"> 94</span>&#160;On Github users can find also a [benchmark suite](https://github.com/abeimler/ecs_benchmark) that compares a bunch of different projects, one of which is `EnTT`.</div><div class="line"><a name="l00095"></a><span class="lineno"> 95</span>&#160;</div><div class="line"><a name="l00096"></a><span class="lineno"> 96</span>&#160;Of course, probably I&#39;ll try to get out of `EnTT` more features and better performance in the future, mainly for fun.&lt;br/&gt;</div><div class="line"><a name="l00097"></a><span class="lineno"> 97</span>&#160;If you want to contribute and/or have any suggestion, feel free to make a PR or open an issue to discuss your idea.</div><div class="line"><a name="l00098"></a><span class="lineno"> 98</span>&#160;</div><div class="line"><a name="l00099"></a><span class="lineno"> 99</span>&#160;# Build Instructions</div><div class="line"><a name="l00100"></a><span class="lineno"> 100</span>&#160;</div><div class="line"><a name="l00101"></a><span class="lineno"> 101</span>&#160;## Requirements</div><div class="line"><a name="l00102"></a><span class="lineno"> 102</span>&#160;</div><div class="line"><a name="l00103"></a><span class="lineno"> 103</span>&#160;To be able to use `EnTT`, users must provide a full-featured compiler that supports at least C++14.&lt;br/&gt;</div><div class="line"><a name="l00104"></a><span class="lineno"> 104</span>&#160;The requirements below are mandatory to compile the tests and to extract the documentation:</div><div class="line"><a name="l00105"></a><span class="lineno"> 105</span>&#160;</div><div class="line"><a name="l00106"></a><span class="lineno"> 106</span>&#160;* CMake version 3.2 or later.</div><div class="line"><a name="l00107"></a><span class="lineno"> 107</span>&#160;* Doxygen version 1.8 or later.</div><div class="line"><a name="l00108"></a><span class="lineno"> 108</span>&#160;</div><div class="line"><a name="l00109"></a><span class="lineno"> 109</span>&#160;## Library</div><div class="line"><a name="l00110"></a><span class="lineno"> 110</span>&#160;</div><div class="line"><a name="l00111"></a><span class="lineno"> 111</span>&#160;`EnTT` is a header-only library. This means that including the `registry.hpp` header is enough to use it.&lt;br/&gt;</div><div class="line"><a name="l00112"></a><span class="lineno"> 112</span>&#160;It&#39;s a matter of adding the following line at the top of a file:</div><div class="line"><a name="l00113"></a><span class="lineno"> 113</span>&#160;</div><div class="line"><a name="l00114"></a><span class="lineno"> 114</span>&#160;```cpp</div><div class="line"><a name="l00115"></a><span class="lineno"> 115</span>&#160;#include &lt;registry.hpp&gt;</div><div class="line"><a name="l00116"></a><span class="lineno"> 116</span>&#160;```</div><div class="line"><a name="l00117"></a><span class="lineno"> 117</span>&#160;</div><div class="line"><a name="l00118"></a><span class="lineno"> 118</span>&#160;Then pass the proper `-I` argument to the compiler to add the `src` directory to the include paths.</div><div class="line"><a name="l00119"></a><span class="lineno"> 119</span>&#160;</div><div class="line"><a name="l00120"></a><span class="lineno"> 120</span>&#160;## Documentation</div><div class="line"><a name="l00121"></a><span class="lineno"> 121</span>&#160;</div><div class="line"><a name="l00122"></a><span class="lineno"> 122</span>&#160;### API Reference</div><div class="line"><a name="l00123"></a><span class="lineno"> 123</span>&#160;</div><div class="line"><a name="l00124"></a><span class="lineno"> 124</span>&#160;The documentation is based on [doxygen](http://www.stack.nl/~dimitri/doxygen/). To build it:</div><div class="line"><a name="l00125"></a><span class="lineno"> 125</span>&#160;</div><div class="line"><a name="l00126"></a><span class="lineno"> 126</span>&#160;$ cd build</div><div class="line"><a name="l00127"></a><span class="lineno"> 127</span>&#160;$ cmake ..</div><div class="line"><a name="l00128"></a><span class="lineno"> 128</span>&#160;$ make docs</div><div class="line"><a name="l00129"></a><span class="lineno"> 129</span>&#160;</div><div class="line"><a name="l00130"></a><span class="lineno"> 130</span>&#160;The API reference will be created in HTML format within the directory `build/docs/html`.</div><div class="line"><a name="l00131"></a><span class="lineno"> 131</span>&#160;To navigate it with your favorite browser:</div><div class="line"><a name="l00132"></a><span class="lineno"> 132</span>&#160;</div><div class="line"><a name="l00133"></a><span class="lineno"> 133</span>&#160;$ cd build</div><div class="line"><a name="l00134"></a><span class="lineno"> 134</span>&#160;$ your_favorite_browser docs/html/index.html</div><div class="line"><a name="l00135"></a><span class="lineno"> 135</span>&#160;</div><div class="line"><a name="l00136"></a><span class="lineno"> 136</span>&#160;The API reference is also available [online](https://skypjack.github.io/entt/) for the latest version.</div><div class="line"><a name="l00137"></a><span class="lineno"> 137</span>&#160;</div><div class="line"><a name="l00138"></a><span class="lineno"> 138</span>&#160;### Crash Course</div><div class="line"><a name="l00139"></a><span class="lineno"> 139</span>&#160;</div><div class="line"><a name="l00140"></a><span class="lineno"> 140</span>&#160;#### Vademecum</div><div class="line"><a name="l00141"></a><span class="lineno"> 141</span>&#160;</div><div class="line"><a name="l00142"></a><span class="lineno"> 142</span>&#160;The `Registry` to store, the `View`s to iterate. That&#39;s all.</div><div class="line"><a name="l00143"></a><span class="lineno"> 143</span>&#160;</div><div class="line"><a name="l00144"></a><span class="lineno"> 144</span>&#160;&lt;!--</div><div class="line"><a name="l00145"></a><span class="lineno"> 145</span>&#160;`EnTT` has two main actors: the **Registry** and the **View**.&lt;br/&gt;</div><div class="line"><a name="l00146"></a><span class="lineno"> 146</span>&#160;The former can be used to manage components, entities and collections of components and entities. The latter allows users to iterate the underlying collections.</div><div class="line"><a name="l00147"></a><span class="lineno"> 147</span>&#160;</div><div class="line"><a name="l00148"></a><span class="lineno"> 148</span>&#160;#### The Registry</div><div class="line"><a name="l00149"></a><span class="lineno"> 149</span>&#160;</div><div class="line"><a name="l00150"></a><span class="lineno"> 150</span>&#160;There are two options to instantiate a registry:</div><div class="line"><a name="l00151"></a><span class="lineno"> 151</span>&#160;</div><div class="line"><a name="l00152"></a><span class="lineno"> 152</span>&#160;* Use the `DefaultRegistry` alias:</div><div class="line"><a name="l00153"></a><span class="lineno"> 153</span>&#160;</div><div class="line"><a name="l00154"></a><span class="lineno"> 154</span>&#160; ```cpp</div><div class="line"><a name="l00155"></a><span class="lineno"> 155</span>&#160; auto registry = entt::DefaultRegistry&lt;Components...&gt;{args...};</div><div class="line"><a name="l00156"></a><span class="lineno"> 156</span>&#160; ```</div><div class="line"><a name="l00157"></a><span class="lineno"> 157</span>&#160;</div><div class="line"><a name="l00158"></a><span class="lineno"> 158</span>&#160; Users must provide the whole list of components to be registered with the default registry and that&#39;s all.</div><div class="line"><a name="l00159"></a><span class="lineno"> 159</span>&#160;</div><div class="line"><a name="l00160"></a><span class="lineno"> 160</span>&#160;* Use directly the `Registry` class template:</div><div class="line"><a name="l00161"></a><span class="lineno"> 161</span>&#160;</div><div class="line"><a name="l00162"></a><span class="lineno"> 162</span>&#160; ```cpp</div><div class="line"><a name="l00163"></a><span class="lineno"> 163</span>&#160; auto registry = entt::Registry&lt;std::uint16_t, Components...&gt;{args...};</div><div class="line"><a name="l00164"></a><span class="lineno"> 164</span>&#160; ```</div><div class="line"><a name="l00165"></a><span class="lineno"> 165</span>&#160;</div><div class="line"><a name="l00166"></a><span class="lineno"> 166</span>&#160; Users must provide the whole list of components to be registered with the registry **and** the desired type for the entities.</div><div class="line"><a name="l00167"></a><span class="lineno"> 167</span>&#160; Note that the default type (the one used by the default registry) is `std::uint32_t`, that is larger enough for almost all the games but also too big for the most of the games.</div><div class="line"><a name="l00168"></a><span class="lineno"> 168</span>&#160;</div><div class="line"><a name="l00169"></a><span class="lineno"> 169</span>&#160;In both cases there are no requirements for the components but to be moveable, therefore POD types are just fine.</div><div class="line"><a name="l00170"></a><span class="lineno"> 170</span>&#160;</div><div class="line"><a name="l00171"></a><span class="lineno"> 171</span>&#160;The `Registry` class offers a bunch of basic functionalities to query the internal data structures.</div><div class="line"><a name="l00172"></a><span class="lineno"> 172</span>&#160;In almost all the cases those member functions can be used to query either the entity list or the components lists.&lt;br/&gt;</div><div class="line"><a name="l00173"></a><span class="lineno"> 173</span>&#160;As an example, the member functions `empty` can be used to know if at least an entity exists and/or if at least one component of the given type has been assigned to an entity.&lt;br/&gt;</div><div class="line"><a name="l00174"></a><span class="lineno"> 174</span>&#160;</div><div class="line"><a name="l00175"></a><span class="lineno"> 175</span>&#160;```cpp</div><div class="line"><a name="l00176"></a><span class="lineno"> 176</span>&#160;bool b = registry.empty();</div><div class="line"><a name="l00177"></a><span class="lineno"> 177</span>&#160;// ...</div><div class="line"><a name="l00178"></a><span class="lineno"> 178</span>&#160;bool b = registry.empty&lt;MyComponent&gt;();</div><div class="line"><a name="l00179"></a><span class="lineno"> 179</span>&#160;```</div><div class="line"><a name="l00180"></a><span class="lineno"> 180</span>&#160;</div><div class="line"><a name="l00181"></a><span class="lineno"> 181</span>&#160;Similarly, `size` can be used to know the number of entities alive and/or the number of components of a given type still assigned to entities. `capacity` follows the same pattern and returns the storage capacity for the given element.</div><div class="line"><a name="l00182"></a><span class="lineno"> 182</span>&#160;</div><div class="line"><a name="l00183"></a><span class="lineno"> 183</span>&#160;The `valid` member function returns true if `entity` is still in use, false otherwise:</div><div class="line"><a name="l00184"></a><span class="lineno"> 184</span>&#160;</div><div class="line"><a name="l00185"></a><span class="lineno"> 185</span>&#160;```cpp</div><div class="line"><a name="l00186"></a><span class="lineno"> 186</span>&#160;bool b = registry.valid(entity);</div><div class="line"><a name="l00187"></a><span class="lineno"> 187</span>&#160;```</div><div class="line"><a name="l00188"></a><span class="lineno"> 188</span>&#160;</div><div class="line"><a name="l00189"></a><span class="lineno"> 189</span>&#160;Boring, I agree. Let&#39;s go to something more tasty.</div><div class="line"><a name="l00190"></a><span class="lineno"> 190</span>&#160;The following functionalities are meant to give users the chance to play with entities and components within a registry.</div><div class="line"><a name="l00191"></a><span class="lineno"> 191</span>&#160;</div><div class="line"><a name="l00192"></a><span class="lineno"> 192</span>&#160;The `create` member function can be used to construct a new entity and it comes in two flavors:</div><div class="line"><a name="l00193"></a><span class="lineno"> 193</span>&#160;</div><div class="line"><a name="l00194"></a><span class="lineno"> 194</span>&#160;* The plain version just creates a _naked_ entity with no components assigned to it:</div><div class="line"><a name="l00195"></a><span class="lineno"> 195</span>&#160;</div><div class="line"><a name="l00196"></a><span class="lineno"> 196</span>&#160; ```cpp</div><div class="line"><a name="l00197"></a><span class="lineno"> 197</span>&#160; auto entity = registry.create();</div><div class="line"><a name="l00198"></a><span class="lineno"> 198</span>&#160; ```</div><div class="line"><a name="l00199"></a><span class="lineno"> 199</span>&#160;</div><div class="line"><a name="l00200"></a><span class="lineno"> 200</span>&#160;* The member function template creates an entity and assigns to it the given _default-initialized_ components:</div><div class="line"><a name="l00201"></a><span class="lineno"> 201</span>&#160;</div><div class="line"><a name="l00202"></a><span class="lineno"> 202</span>&#160; ```cpp</div><div class="line"><a name="l00203"></a><span class="lineno"> 203</span>&#160; auto entity = registry.create&lt;Position, Velocity&gt;();</div><div class="line"><a name="l00204"></a><span class="lineno"> 204</span>&#160; ```</div><div class="line"><a name="l00205"></a><span class="lineno"> 205</span>&#160;</div><div class="line"><a name="l00206"></a><span class="lineno"> 206</span>&#160; It&#39;s a helper function, mostly syncactic sugar and it&#39;s equivalent to the following snippet:</div><div class="line"><a name="l00207"></a><span class="lineno"> 207</span>&#160;</div><div class="line"><a name="l00208"></a><span class="lineno"> 208</span>&#160; ```cpp</div><div class="line"><a name="l00209"></a><span class="lineno"> 209</span>&#160; auto entity = registry.create();</div><div class="line"><a name="l00210"></a><span class="lineno"> 210</span>&#160; registry.assign&lt;Position&gt;();</div><div class="line"><a name="l00211"></a><span class="lineno"> 211</span>&#160; registry.assign&lt;Velocity&gt;();</div><div class="line"><a name="l00212"></a><span class="lineno"> 212</span>&#160; ```</div><div class="line"><a name="l00213"></a><span class="lineno"> 213</span>&#160;</div><div class="line"><a name="l00214"></a><span class="lineno"> 214</span>&#160; See below to find more about the `assign` member function.</div><div class="line"><a name="l00215"></a><span class="lineno"> 215</span>&#160;</div><div class="line"><a name="l00216"></a><span class="lineno"> 216</span>&#160;On the other side, the `destroy` member function can be used to delete an entity and all its components (if any):</div><div class="line"><a name="l00217"></a><span class="lineno"> 217</span>&#160;</div><div class="line"><a name="l00218"></a><span class="lineno"> 218</span>&#160;```cpp</div><div class="line"><a name="l00219"></a><span class="lineno"> 219</span>&#160;registry.destroy(entity);</div><div class="line"><a name="l00220"></a><span class="lineno"> 220</span>&#160;```</div><div class="line"><a name="l00221"></a><span class="lineno"> 221</span>&#160;</div><div class="line"><a name="l00222"></a><span class="lineno"> 222</span>&#160;It requires that `entity` is valid. In case it is not, an assertion will fail in debug mode and the behaviour is undefined in release mode.</div><div class="line"><a name="l00223"></a><span class="lineno"> 223</span>&#160;</div><div class="line"><a name="l00224"></a><span class="lineno"> 224</span>&#160;If the purpose is to remove a single component instead, the `remove` member function template is the way to go:</div><div class="line"><a name="l00225"></a><span class="lineno"> 225</span>&#160;</div><div class="line"><a name="l00226"></a><span class="lineno"> 226</span>&#160;```cpp</div><div class="line"><a name="l00227"></a><span class="lineno"> 227</span>&#160;registry.remove&lt;Position&gt;(entity);</div><div class="line"><a name="l00228"></a><span class="lineno"> 228</span>&#160;```</div><div class="line"><a name="l00229"></a><span class="lineno"> 229</span>&#160;</div><div class="line"><a name="l00230"></a><span class="lineno"> 230</span>&#160;Again, it requires that `entity` is valid. Moreover, an instance of the component must have been previously assigned to the entity.</div><div class="line"><a name="l00231"></a><span class="lineno"> 231</span>&#160;If one of the requirements isn&#39;t satisfied, an assertion will fail in debug mode and the behaviour is undefined in release mode.</div><div class="line"><a name="l00232"></a><span class="lineno"> 232</span>&#160;</div><div class="line"><a name="l00233"></a><span class="lineno"> 233</span>&#160;The `reset` member function behaves similarly but with a strictly defined behaviour (and a performance penalty is the price to pay for that). In particular it removes the component if and only if it exists, otherwise it returns safely to the caller:</div><div class="line"><a name="l00234"></a><span class="lineno"> 234</span>&#160;</div><div class="line"><a name="l00235"></a><span class="lineno"> 235</span>&#160;```cpp</div><div class="line"><a name="l00236"></a><span class="lineno"> 236</span>&#160;registry.reset&lt;Position&gt;(entity);</div><div class="line"><a name="l00237"></a><span class="lineno"> 237</span>&#160;```</div><div class="line"><a name="l00238"></a><span class="lineno"> 238</span>&#160;</div><div class="line"><a name="l00239"></a><span class="lineno"> 239</span>&#160;It requires only that `entity` is valid. In case it is not, an assertion will fail in debug mode and the behaviour is undefined in release mode.</div><div class="line"><a name="l00240"></a><span class="lineno"> 240</span>&#160;</div><div class="line"><a name="l00241"></a><span class="lineno"> 241</span>&#160;There exist also two more _versions_ of the `reset` member function:</div><div class="line"><a name="l00242"></a><span class="lineno"> 242</span>&#160;</div><div class="line"><a name="l00243"></a><span class="lineno"> 243</span>&#160;* If no entity is passed to it, `reset` will remove the given component from each entity that has it:</div><div class="line"><a name="l00244"></a><span class="lineno"> 244</span>&#160;</div><div class="line"><a name="l00245"></a><span class="lineno"> 245</span>&#160; ```cpp</div><div class="line"><a name="l00246"></a><span class="lineno"> 246</span>&#160; registry.reset&lt;Position&gt;();</div><div class="line"><a name="l00247"></a><span class="lineno"> 247</span>&#160; ```</div><div class="line"><a name="l00248"></a><span class="lineno"> 248</span>&#160;</div><div class="line"><a name="l00249"></a><span class="lineno"> 249</span>&#160;* If neither the entity nor the component are specified, all the entities and their components are destroyed:</div><div class="line"><a name="l00250"></a><span class="lineno"> 250</span>&#160;</div><div class="line"><a name="l00251"></a><span class="lineno"> 251</span>&#160; ```cpp</div><div class="line"><a name="l00252"></a><span class="lineno"> 252</span>&#160; registry.reset();</div><div class="line"><a name="l00253"></a><span class="lineno"> 253</span>&#160; ```</div><div class="line"><a name="l00254"></a><span class="lineno"> 254</span>&#160;</div><div class="line"><a name="l00255"></a><span class="lineno"> 255</span>&#160; **Note**: the registry has an assert in debug mode that verifies that entities are no longer valid when it&#39;s destructed. This function can be used to reset the registry to its initial state and thus to satisfy the requirement.</div><div class="line"><a name="l00256"></a><span class="lineno"> 256</span>&#160;</div><div class="line"><a name="l00257"></a><span class="lineno"> 257</span>&#160;To assign a component to an entity, users can rely on the `assign` member function template. It accepts a variable number of arguments that are used to construct the component itself if present:</div><div class="line"><a name="l00258"></a><span class="lineno"> 258</span>&#160;</div><div class="line"><a name="l00259"></a><span class="lineno"> 259</span>&#160;```cpp</div><div class="line"><a name="l00260"></a><span class="lineno"> 260</span>&#160;registry.assign&lt;Position&gt;(entity, 0., 0.);</div><div class="line"><a name="l00261"></a><span class="lineno"> 261</span>&#160;// ...</div><div class="line"><a name="l00262"></a><span class="lineno"> 262</span>&#160;auto &amp;velocity = registry.assign&lt;Velocity&gt;(entity);</div><div class="line"><a name="l00263"></a><span class="lineno"> 263</span>&#160;velocity.dx = 0.;</div><div class="line"><a name="l00264"></a><span class="lineno"> 264</span>&#160;velocity.dy = 0.;</div><div class="line"><a name="l00265"></a><span class="lineno"> 265</span>&#160;```</div><div class="line"><a name="l00266"></a><span class="lineno"> 266</span>&#160;</div><div class="line"><a name="l00267"></a><span class="lineno"> 267</span>&#160;It requires that `entity` is valid. Moreover, the entity shouldn&#39;t have another instance of the component assigned to it.</div><div class="line"><a name="l00268"></a><span class="lineno"> 268</span>&#160;If one of the requirements isn&#39;t satisfied, an assertion will fail in debug mode and the behaviour is undefined in release mode.</div><div class="line"><a name="l00269"></a><span class="lineno"> 269</span>&#160;</div><div class="line"><a name="l00270"></a><span class="lineno"> 270</span>&#160;If the entity already has the given component and the user wants to replace it, the `replace` member function template is the way to go:</div><div class="line"><a name="l00271"></a><span class="lineno"> 271</span>&#160;</div><div class="line"><a name="l00272"></a><span class="lineno"> 272</span>&#160;```cpp</div><div class="line"><a name="l00273"></a><span class="lineno"> 273</span>&#160;registry.replace&lt;Position&gt;(entity, 0., 0.);</div><div class="line"><a name="l00274"></a><span class="lineno"> 274</span>&#160;// ...</div><div class="line"><a name="l00275"></a><span class="lineno"> 275</span>&#160;auto &amp;velocity = registry.replace&lt;Velocity&gt;(entity);</div><div class="line"><a name="l00276"></a><span class="lineno"> 276</span>&#160;velocity.dx = 0.;</div><div class="line"><a name="l00277"></a><span class="lineno"> 277</span>&#160;velocity.dy = 0.;</div><div class="line"><a name="l00278"></a><span class="lineno"> 278</span>&#160;```</div><div class="line"><a name="l00279"></a><span class="lineno"> 279</span>&#160;</div><div class="line"><a name="l00280"></a><span class="lineno"> 280</span>&#160;It requires that `entity` is valid. Moreover, an instance of the component must have been previously assigned to the entity.</div><div class="line"><a name="l00281"></a><span class="lineno"> 281</span>&#160;If one of the requirements isn&#39;t satisfied, an assertion will fail in debug mode and the behaviour is undefined in release mode.</div><div class="line"><a name="l00282"></a><span class="lineno"> 282</span>&#160;</div><div class="line"><a name="l00283"></a><span class="lineno"> 283</span>&#160;In case users want to assign a component to an entity, but it&#39;s unknown whether the entity already has it or not, `accomodate` does the work in a single call</div><div class="line"><a name="l00284"></a><span class="lineno"> 284</span>&#160;(of course, there is a performance penalty to pay for that mainly due to the fact that it must check if `entity` already has the given component or not):</div><div class="line"><a name="l00285"></a><span class="lineno"> 285</span>&#160;</div><div class="line"><a name="l00286"></a><span class="lineno"> 286</span>&#160;```cpp</div><div class="line"><a name="l00287"></a><span class="lineno"> 287</span>&#160;registry.accomodate&lt;Position&gt;(entity, 0., 0.);</div><div class="line"><a name="l00288"></a><span class="lineno"> 288</span>&#160;// ...</div><div class="line"><a name="l00289"></a><span class="lineno"> 289</span>&#160;auto &amp;velocity = registry.accomodate&lt;Velocity&gt;(entity);</div><div class="line"><a name="l00290"></a><span class="lineno"> 290</span>&#160;velocity.dx = 0.;</div><div class="line"><a name="l00291"></a><span class="lineno"> 291</span>&#160;velocity.dy = 0.;</div><div class="line"><a name="l00292"></a><span class="lineno"> 292</span>&#160;```</div><div class="line"><a name="l00293"></a><span class="lineno"> 293</span>&#160;</div><div class="line"><a name="l00294"></a><span class="lineno"> 294</span>&#160;It requires only that `entity` is valid. In case it is not, an assertion will fail in debug mode and the behaviour is undefined in release mode.&lt;br/&gt;</div><div class="line"><a name="l00295"></a><span class="lineno"> 295</span>&#160;Note that `accomodate` is a sliglhty faster alternative for the following if/else statement and nothing more:</div><div class="line"><a name="l00296"></a><span class="lineno"> 296</span>&#160;</div><div class="line"><a name="l00297"></a><span class="lineno"> 297</span>&#160;```cpp</div><div class="line"><a name="l00298"></a><span class="lineno"> 298</span>&#160;if(registry.has&lt;Comp&gt;(entity)) {</div><div class="line"><a name="l00299"></a><span class="lineno"> 299</span>&#160; registry.replace&lt;Comp&gt;(entity, arg1, argN);</div><div class="line"><a name="l00300"></a><span class="lineno"> 300</span>&#160;} else {</div><div class="line"><a name="l00301"></a><span class="lineno"> 301</span>&#160; registry.assign&lt;Comp&gt;(entity, arg1, argN);</div><div class="line"><a name="l00302"></a><span class="lineno"> 302</span>&#160;}</div><div class="line"><a name="l00303"></a><span class="lineno"> 303</span>&#160;```</div><div class="line"><a name="l00304"></a><span class="lineno"> 304</span>&#160;</div><div class="line"><a name="l00305"></a><span class="lineno"> 305</span>&#160;As already shown, if in doubt about whether or not an entity has one or more components, the `has` member function template may be useful:</div><div class="line"><a name="l00306"></a><span class="lineno"> 306</span>&#160;</div><div class="line"><a name="l00307"></a><span class="lineno"> 307</span>&#160;```cpp</div><div class="line"><a name="l00308"></a><span class="lineno"> 308</span>&#160;bool b = registry.has&lt;Position, Velocity&gt;(entity);</div><div class="line"><a name="l00309"></a><span class="lineno"> 309</span>&#160;```</div><div class="line"><a name="l00310"></a><span class="lineno"> 310</span>&#160;</div><div class="line"><a name="l00311"></a><span class="lineno"> 311</span>&#160;It requires only that `entity` is valid. In case it is not, an assertion will fail in debug mode and the behaviour is undefined in release mode.</div><div class="line"><a name="l00312"></a><span class="lineno"> 312</span>&#160;</div><div class="line"><a name="l00313"></a><span class="lineno"> 313</span>&#160;Entities can also be cloned and either partially or fully copied:</div><div class="line"><a name="l00314"></a><span class="lineno"> 314</span>&#160;</div><div class="line"><a name="l00315"></a><span class="lineno"> 315</span>&#160;```cpp</div><div class="line"><a name="l00316"></a><span class="lineno"> 316</span>&#160;auto entity = registry.clone(other);</div><div class="line"><a name="l00317"></a><span class="lineno"> 317</span>&#160;// ...</div><div class="line"><a name="l00318"></a><span class="lineno"> 318</span>&#160;auto &amp;velocity = registry.copy&lt;Velocity&gt;(to, from);</div><div class="line"><a name="l00319"></a><span class="lineno"> 319</span>&#160;// ...</div><div class="line"><a name="l00320"></a><span class="lineno"> 320</span>&#160;registry.copy(dst, src);</div><div class="line"><a name="l00321"></a><span class="lineno"> 321</span>&#160;```</div><div class="line"><a name="l00322"></a><span class="lineno"> 322</span>&#160;</div><div class="line"><a name="l00323"></a><span class="lineno"> 323</span>&#160;In particular:</div><div class="line"><a name="l00324"></a><span class="lineno"> 324</span>&#160;</div><div class="line"><a name="l00325"></a><span class="lineno"> 325</span>&#160;* The `clone` member function creates a new entity and copy all the components from the given one.</div><div class="line"><a name="l00326"></a><span class="lineno"> 326</span>&#160;* The `copy` member function template copies one component from an entity to another one.</div><div class="line"><a name="l00327"></a><span class="lineno"> 327</span>&#160;* The `copy` member function copies all the components from an entity to another one.</div><div class="line"><a name="l00328"></a><span class="lineno"> 328</span>&#160;</div><div class="line"><a name="l00329"></a><span class="lineno"> 329</span>&#160;All the functions above mentioned require that entities provided as arguments are valid and components exist wherever they have to be accessed.</div><div class="line"><a name="l00330"></a><span class="lineno"> 330</span>&#160;In case they are not, an assertion will fail in debug mode and the behaviour is undefined in release mode.</div><div class="line"><a name="l00331"></a><span class="lineno"> 331</span>&#160;</div><div class="line"><a name="l00332"></a><span class="lineno"> 332</span>&#160;There exists also an utility member function that can be used to `swap` components between entities:</div><div class="line"><a name="l00333"></a><span class="lineno"> 333</span>&#160;</div><div class="line"><a name="l00334"></a><span class="lineno"> 334</span>&#160;```cpp</div><div class="line"><a name="l00335"></a><span class="lineno"> 335</span>&#160;registry.swap&lt;Position&gt;(e1, e2);</div><div class="line"><a name="l00336"></a><span class="lineno"> 336</span>&#160;```</div><div class="line"><a name="l00337"></a><span class="lineno"> 337</span>&#160;</div><div class="line"><a name="l00338"></a><span class="lineno"> 338</span>&#160;As usual, it requires that the two entities are valid and that two instances of the component have been previously assigned to them.</div><div class="line"><a name="l00339"></a><span class="lineno"> 339</span>&#160;In case they are not, an assertion will fail in debug mode and the behaviour is undefined in release mode.</div><div class="line"><a name="l00340"></a><span class="lineno"> 340</span>&#160;</div><div class="line"><a name="l00341"></a><span class="lineno"> 341</span>&#160;The `get` member function template (either the non-const or the const version) gives direct access to the component of an entity instead:</div><div class="line"><a name="l00342"></a><span class="lineno"> 342</span>&#160;</div><div class="line"><a name="l00343"></a><span class="lineno"> 343</span>&#160;```cpp</div><div class="line"><a name="l00344"></a><span class="lineno"> 344</span>&#160;auto &amp;position = registry.get&lt;Position&gt;(entity);</div><div class="line"><a name="l00345"></a><span class="lineno"> 345</span>&#160;```</div><div class="line"><a name="l00346"></a><span class="lineno"> 346</span>&#160;</div><div class="line"><a name="l00347"></a><span class="lineno"> 347</span>&#160;It requires that `entity` is valid. Moreover, an instance of the component must have been previously assigned to the entity.</div><div class="line"><a name="l00348"></a><span class="lineno"> 348</span>&#160;If one of the requirements isn&#39;t satisfied, an assertion will fail in debug mode and the behaviour is undefined in release mode.</div><div class="line"><a name="l00349"></a><span class="lineno"> 349</span>&#160;</div><div class="line"><a name="l00350"></a><span class="lineno"> 350</span>&#160;Components can also be sorted in memory by means of the `sort` member function templates. In particular:</div><div class="line"><a name="l00351"></a><span class="lineno"> 351</span>&#160;</div><div class="line"><a name="l00352"></a><span class="lineno"> 352</span>&#160;* Components can be sorted according to a component:</div><div class="line"><a name="l00353"></a><span class="lineno"> 353</span>&#160;</div><div class="line"><a name="l00354"></a><span class="lineno"> 354</span>&#160; ```cpp</div><div class="line"><a name="l00355"></a><span class="lineno"> 355</span>&#160; registry.sort&lt;Renderable&gt;([](const auto &amp;lhs, const auto &amp;rhs) { return lhs.z &lt; rhs.z; });</div><div class="line"><a name="l00356"></a><span class="lineno"> 356</span>&#160; ```</div><div class="line"><a name="l00357"></a><span class="lineno"> 357</span>&#160;</div><div class="line"><a name="l00358"></a><span class="lineno"> 358</span>&#160;* Components can be sorted according to the order imposed by another component:</div><div class="line"><a name="l00359"></a><span class="lineno"> 359</span>&#160;</div><div class="line"><a name="l00360"></a><span class="lineno"> 360</span>&#160; ```cpp</div><div class="line"><a name="l00361"></a><span class="lineno"> 361</span>&#160; registry.sort&lt;Movement, Physics&gt;();</div><div class="line"><a name="l00362"></a><span class="lineno"> 362</span>&#160; ```</div><div class="line"><a name="l00363"></a><span class="lineno"> 363</span>&#160;</div><div class="line"><a name="l00364"></a><span class="lineno"> 364</span>&#160; In this case, instances of `Movement` are arranged in memory so that cache misses are minimized when the two components are iterated together.</div><div class="line"><a name="l00365"></a><span class="lineno"> 365</span>&#160;</div><div class="line"><a name="l00366"></a><span class="lineno"> 366</span>&#160;Finally, the `view` member function template returns an iterable portion of entities and components:</div><div class="line"><a name="l00367"></a><span class="lineno"> 367</span>&#160;</div><div class="line"><a name="l00368"></a><span class="lineno"> 368</span>&#160;```cpp</div><div class="line"><a name="l00369"></a><span class="lineno"> 369</span>&#160;auto view = registry.view&lt;Position, Velocity&gt;();</div><div class="line"><a name="l00370"></a><span class="lineno"> 370</span>&#160;```</div><div class="line"><a name="l00371"></a><span class="lineno"> 371</span>&#160;</div><div class="line"><a name="l00372"></a><span class="lineno"> 372</span>&#160;Views are the other core component of `EnTT` and are usually extensively used by softwares that include it. See below for more details about the types of views.</div><div class="line"><a name="l00373"></a><span class="lineno"> 373</span>&#160;</div><div class="line"><a name="l00374"></a><span class="lineno"> 374</span>&#160;#### The View</div><div class="line"><a name="l00375"></a><span class="lineno"> 375</span>&#160;</div><div class="line"><a name="l00376"></a><span class="lineno"> 376</span>&#160;There are two types of views:</div><div class="line"><a name="l00377"></a><span class="lineno"> 377</span>&#160;</div><div class="line"><a name="l00378"></a><span class="lineno"> 378</span>&#160;* **Single component view**.</div><div class="line"><a name="l00379"></a><span class="lineno"> 379</span>&#160;</div><div class="line"><a name="l00380"></a><span class="lineno"> 380</span>&#160; A single component view gives direct access to both the components and the entities to which the components are assigned.&lt;br/&gt;</div><div class="line"><a name="l00381"></a><span class="lineno"> 381</span>&#160; This kind of views are created from the `Registry` class by means of the `view` member function template as it follows:</div><div class="line"><a name="l00382"></a><span class="lineno"> 382</span>&#160;</div><div class="line"><a name="l00383"></a><span class="lineno"> 383</span>&#160; ```cpp</div><div class="line"><a name="l00384"></a><span class="lineno"> 384</span>&#160; // Actual type is Registry&lt;Components...&gt;::view_type&lt;Comp&gt;, where Comp is the component for which the view should be created ...</div><div class="line"><a name="l00385"></a><span class="lineno"> 385</span>&#160; // ... well, auto is far easier to use in this case, isn&#39;t it?</div><div class="line"><a name="l00386"></a><span class="lineno"> 386</span>&#160; auto view = registry.view&lt;Sprite&gt;();</div><div class="line"><a name="l00387"></a><span class="lineno"> 387</span>&#160; ```</div><div class="line"><a name="l00388"></a><span class="lineno"> 388</span>&#160;</div><div class="line"><a name="l00389"></a><span class="lineno"> 389</span>&#160; Components and entities are stored in tightly packed arrays and single component views are the fastest solution to iterate them.&lt;br/&gt;</div><div class="line"><a name="l00390"></a><span class="lineno"> 390</span>&#160; They have the _C++11-ish_ `begin` and `end` member function that allow users to use them in a typical range-for loop:</div><div class="line"><a name="l00391"></a><span class="lineno"> 391</span>&#160;</div><div class="line"><a name="l00392"></a><span class="lineno"> 392</span>&#160; ```cpp</div><div class="line"><a name="l00393"></a><span class="lineno"> 393</span>&#160; auto view = registry.view&lt;Sprite&gt;();</div><div class="line"><a name="l00394"></a><span class="lineno"> 394</span>&#160;</div><div class="line"><a name="l00395"></a><span class="lineno"> 395</span>&#160; for(auto entity: view) {</div><div class="line"><a name="l00396"></a><span class="lineno"> 396</span>&#160; auto &amp;sprite = registry.get&lt;Sprite&gt;(entity);</div><div class="line"><a name="l00397"></a><span class="lineno"> 397</span>&#160; // ...</div><div class="line"><a name="l00398"></a><span class="lineno"> 398</span>&#160; }</div><div class="line"><a name="l00399"></a><span class="lineno"> 399</span>&#160; ```</div><div class="line"><a name="l00400"></a><span class="lineno"> 400</span>&#160;</div><div class="line"><a name="l00401"></a><span class="lineno"> 401</span>&#160; Iterating a view this way returns entities that can be further used to get components or perform other activities.&lt;br/&gt;</div><div class="line"><a name="l00402"></a><span class="lineno"> 402</span>&#160; There is also another method one can use to iterate the array of entities, that is by using the `size` and `data` member functions:</div><div class="line"><a name="l00403"></a><span class="lineno"> 403</span>&#160;</div><div class="line"><a name="l00404"></a><span class="lineno"> 404</span>&#160; ```cpp</div><div class="line"><a name="l00405"></a><span class="lineno"> 405</span>&#160; auto view = registry.view&lt;Sprite&gt;();</div><div class="line"><a name="l00406"></a><span class="lineno"> 406</span>&#160; const auto *data = view.data();</div><div class="line"><a name="l00407"></a><span class="lineno"> 407</span>&#160;</div><div class="line"><a name="l00408"></a><span class="lineno"> 408</span>&#160; for(auto i = 0, end = view.size(); i &lt; end; ++i) {</div><div class="line"><a name="l00409"></a><span class="lineno"> 409</span>&#160; auto entity = *(data + i);</div><div class="line"><a name="l00410"></a><span class="lineno"> 410</span>&#160; // ...</div><div class="line"><a name="l00411"></a><span class="lineno"> 411</span>&#160; }</div><div class="line"><a name="l00412"></a><span class="lineno"> 412</span>&#160; ```</div><div class="line"><a name="l00413"></a><span class="lineno"> 413</span>&#160;</div><div class="line"><a name="l00414"></a><span class="lineno"> 414</span>&#160; Entites are good when the sole component isn&#39;t enough to perform a task.</div><div class="line"><a name="l00415"></a><span class="lineno"> 415</span>&#160; Anyway they come with a cost: accessing components by entities has an extra level of indirection. It&#39;s pretty fast, but not that fast in some cases.&lt;br/&gt;</div><div class="line"><a name="l00416"></a><span class="lineno"> 416</span>&#160; Direct access to the packed array of components is the other option around of a single component view. Member functions `size` and `raw` are there for that:</div><div class="line"><a name="l00417"></a><span class="lineno"> 417</span>&#160;</div><div class="line"><a name="l00418"></a><span class="lineno"> 418</span>&#160; ```cpp</div><div class="line"><a name="l00419"></a><span class="lineno"> 419</span>&#160; auto view = registry.view&lt;Sprite&gt;();</div><div class="line"><a name="l00420"></a><span class="lineno"> 420</span>&#160; const auto *raw = view.raw();</div><div class="line"><a name="l00421"></a><span class="lineno"> 421</span>&#160;</div><div class="line"><a name="l00422"></a><span class="lineno"> 422</span>&#160; for(auto i = 0, end = view.size(); i &lt; end; ++i) {</div><div class="line"><a name="l00423"></a><span class="lineno"> 423</span>&#160; auto &amp;sprite = *(raw + i);</div><div class="line"><a name="l00424"></a><span class="lineno"> 424</span>&#160; // ...</div><div class="line"><a name="l00425"></a><span class="lineno"> 425</span>&#160; }</div><div class="line"><a name="l00426"></a><span class="lineno"> 426</span>&#160; ```</div><div class="line"><a name="l00427"></a><span class="lineno"> 427</span>&#160;</div><div class="line"><a name="l00428"></a><span class="lineno"> 428</span>&#160; This is the fastest solution to iterate over the components: they are packed together by construction and visit them in order will reduce to a minimum the number of cache misses.</div><div class="line"><a name="l00429"></a><span class="lineno"> 429</span>&#160;</div><div class="line"><a name="l00430"></a><span class="lineno"> 430</span>&#160;* **Multi component view**.</div><div class="line"><a name="l00431"></a><span class="lineno"> 431</span>&#160;</div><div class="line"><a name="l00432"></a><span class="lineno"> 432</span>&#160; A multi component view gives access only to the entities to which the components are assigned.&lt;br/&gt;</div><div class="line"><a name="l00433"></a><span class="lineno"> 433</span>&#160; This kind of views are created from the `Registry` class by means of the `view` member function template as it follows:</div><div class="line"><a name="l00434"></a><span class="lineno"> 434</span>&#160;</div><div class="line"><a name="l00435"></a><span class="lineno"> 435</span>&#160; ```cpp</div><div class="line"><a name="l00436"></a><span class="lineno"> 436</span>&#160; // Actual type is Registry&lt;Components...&gt;::view_type&lt;Comp...&gt;, where Comp... are the components for which the view should be created ...</div><div class="line"><a name="l00437"></a><span class="lineno"> 437</span>&#160; // ... well, auto is far easier to use in this case, isn&#39;t it?</div><div class="line"><a name="l00438"></a><span class="lineno"> 438</span>&#160; auto view = registry.view&lt;Position, Velocity&gt;();</div><div class="line"><a name="l00439"></a><span class="lineno"> 439</span>&#160; ```</div><div class="line"><a name="l00440"></a><span class="lineno"> 440</span>&#160;</div><div class="line"><a name="l00441"></a><span class="lineno"> 441</span>&#160; Multi component views can be iterated by means of the `begin` and `end` member functions in a typical range-for loop:</div><div class="line"><a name="l00442"></a><span class="lineno"> 442</span>&#160;</div><div class="line"><a name="l00443"></a><span class="lineno"> 443</span>&#160; ```cpp</div><div class="line"><a name="l00444"></a><span class="lineno"> 444</span>&#160; auto view = registry.view&lt;Position, Velocity&gt;();</div><div class="line"><a name="l00445"></a><span class="lineno"> 445</span>&#160;</div><div class="line"><a name="l00446"></a><span class="lineno"> 446</span>&#160; for(auto entity: view) {</div><div class="line"><a name="l00447"></a><span class="lineno"> 447</span>&#160; auto &amp;position = registry.get&lt;Position&gt;(entity);</div><div class="line"><a name="l00448"></a><span class="lineno"> 448</span>&#160; auto &amp;velocity = registry.get&lt;Velocity&gt;(entity);</div><div class="line"><a name="l00449"></a><span class="lineno"> 449</span>&#160; // ...</div><div class="line"><a name="l00450"></a><span class="lineno"> 450</span>&#160; }</div><div class="line"><a name="l00451"></a><span class="lineno"> 451</span>&#160; ```</div><div class="line"><a name="l00452"></a><span class="lineno"> 452</span>&#160;</div><div class="line"><a name="l00453"></a><span class="lineno"> 453</span>&#160; Note that there exists a packed array of entities to which the component is assigned for each component.</div><div class="line"><a name="l00454"></a><span class="lineno"> 454</span>&#160; Iterators of a multi component view pick the shortest array up and use it to visit the smallest set of potential entities.&lt;br/&gt;</div><div class="line"><a name="l00455"></a><span class="lineno"> 455</span>&#160; The choice is performed when the view is constructed. It&#39;s good enough as long as views are discarded once they have been used.</div><div class="line"><a name="l00456"></a><span class="lineno"> 456</span>&#160; For all the other cases, the `reset` member function can be used whenever the data within the registry are known to be changed and forcing the choice again could speed up the execution.</div><div class="line"><a name="l00457"></a><span class="lineno"> 457</span>&#160;</div><div class="line"><a name="l00458"></a><span class="lineno"> 458</span>&#160; **Note**: one could argue that an iterator should return the set of references to components for each entity instead of the entity itself.</div><div class="line"><a name="l00459"></a><span class="lineno"> 459</span>&#160; Well, who wants to spend CPU cycles to get a reference to an useless tag component? This drove the design choice indeed.</div><div class="line"><a name="l00460"></a><span class="lineno"> 460</span>&#160;</div><div class="line"><a name="l00461"></a><span class="lineno"> 461</span>&#160;All the views can be used more than once. They return newly created and correctly initialized iterators whenever `begin` or `end` is invoked.</div><div class="line"><a name="l00462"></a><span class="lineno"> 462</span>&#160;The same is valid for `data` and `raw` too. Anyway views and iterators are tiny objects and the time spent to construct them can be safely ignored.&lt;br/&gt;</div><div class="line"><a name="l00463"></a><span class="lineno"> 463</span>&#160;I&#39;d suggest not to store them anywhere and to invoke the `Registry::view` member function template at each iteration to get a properly initialized view through which to iterate.</div><div class="line"><a name="l00464"></a><span class="lineno"> 464</span>&#160;</div><div class="line"><a name="l00465"></a><span class="lineno"> 465</span>&#160;#### Side notes</div><div class="line"><a name="l00466"></a><span class="lineno"> 466</span>&#160;</div><div class="line"><a name="l00467"></a><span class="lineno"> 467</span>&#160;* Entities are numbers and nothing more. They are not classes and they have no member functions at all.</div><div class="line"><a name="l00468"></a><span class="lineno"> 468</span>&#160;</div><div class="line"><a name="l00469"></a><span class="lineno"> 469</span>&#160;* Most of the _ECS_ available out there have an annoying limitation (at least from my point of view): entities and components cannot be created, assigned or deleted while users are iterating on them.&lt;br/&gt;</div><div class="line"><a name="l00470"></a><span class="lineno"> 470</span>&#160; `EnTT` partially solves the problem with a few limitations:</div><div class="line"><a name="l00471"></a><span class="lineno"> 471</span>&#160;</div><div class="line"><a name="l00472"></a><span class="lineno"> 472</span>&#160; * Entities can be created at any time while iterating one or more components.</div><div class="line"><a name="l00473"></a><span class="lineno"> 473</span>&#160; * Components can be assigned to any entity at any time while iterating one or more components.</div><div class="line"><a name="l00474"></a><span class="lineno"> 474</span>&#160; * During an iteration, the current entity (that is the one returned by the iterator) can be deleted and all its components can be removed safely.</div><div class="line"><a name="l00475"></a><span class="lineno"> 475</span>&#160;</div><div class="line"><a name="l00476"></a><span class="lineno"> 476</span>&#160; Entities that are not the current one (that is the one returned by the iterator) cannot be deleted from within a loop.&lt;br/&gt;</div><div class="line"><a name="l00477"></a><span class="lineno"> 477</span>&#160; Components assigned to entities that are not the current one (that is the one returned by the iterator) cannot be removed from within a loop.&lt;br/&gt;</div><div class="line"><a name="l00478"></a><span class="lineno"> 478</span>&#160; In this case, iterators are invalidated and the behaviour is undefined if one continues to use those iterators. Possible approaches are:</div><div class="line"><a name="l00479"></a><span class="lineno"> 479</span>&#160;</div><div class="line"><a name="l00480"></a><span class="lineno"> 480</span>&#160; * Store aside the entities and components to be removed and perform the operations at the end of the iteration.</div><div class="line"><a name="l00481"></a><span class="lineno"> 481</span>&#160; * Mark entities and components with a proper tag component that indicates that they must be purged, then perform a second iteration to clean them up one by one.</div><div class="line"><a name="l00482"></a><span class="lineno"> 482</span>&#160;</div><div class="line"><a name="l00483"></a><span class="lineno"> 483</span>&#160;* Iterators aren&#39;t thread safe. Do no try to iterate over a set of components and modify them concurrently.&lt;br/&gt;</div><div class="line"><a name="l00484"></a><span class="lineno"> 484</span>&#160; That being said, as long as a thread iterates over the entities that have the component `X` or assign and removes that component from a set of entities and another thread does something similar with components `Y` and `Z`, it shouldn&#39;t be a problem at all.&lt;br/&gt;</div><div class="line"><a name="l00485"></a><span class="lineno"> 485</span>&#160; As an example, that means that users can freely run the rendering system over the renderable entities and update the physics concurrently on a separate thread if needed.</div><div class="line"><a name="l00486"></a><span class="lineno"> 486</span>&#160;--&gt;</div><div class="line"><a name="l00487"></a><span class="lineno"> 487</span>&#160;</div><div class="line"><a name="l00488"></a><span class="lineno"> 488</span>&#160;## Tests</div><div class="line"><a name="l00489"></a><span class="lineno"> 489</span>&#160;</div><div class="line"><a name="l00490"></a><span class="lineno"> 490</span>&#160;To compile and run the tests, `EnTT` requires *googletest*.&lt;br/&gt;</div><div class="line"><a name="l00491"></a><span class="lineno"> 491</span>&#160;`cmake` will download and compile the library before to compile anything else.</div><div class="line"><a name="l00492"></a><span class="lineno"> 492</span>&#160;</div><div class="line"><a name="l00493"></a><span class="lineno"> 493</span>&#160;To build the tests:</div><div class="line"><a name="l00494"></a><span class="lineno"> 494</span>&#160;</div><div class="line"><a name="l00495"></a><span class="lineno"> 495</span>&#160;* `$ cd build`</div><div class="line"><a name="l00496"></a><span class="lineno"> 496</span>&#160;* `$ cmake ..`</div><div class="line"><a name="l00497"></a><span class="lineno"> 497</span>&#160;* `$ make`</div><div class="line"><a name="l00498"></a><span class="lineno"> 498</span>&#160;* `$ make test`</div><div class="line"><a name="l00499"></a><span class="lineno"> 499</span>&#160;</div><div class="line"><a name="l00500"></a><span class="lineno"> 500</span>&#160;To build the benchmarks, use the following line instead:</div><div class="line"><a name="l00501"></a><span class="lineno"> 501</span>&#160;</div><div class="line"><a name="l00502"></a><span class="lineno"> 502</span>&#160;* `$ cmake -DCMAKE_BUILD_TYPE=Release ..`</div><div class="line"><a name="l00503"></a><span class="lineno"> 503</span>&#160;</div><div class="line"><a name="l00504"></a><span class="lineno"> 504</span>&#160;Benchmarks are compiled only in release mode currently.</div><div class="line"><a name="l00505"></a><span class="lineno"> 505</span>&#160;</div><div class="line"><a name="l00506"></a><span class="lineno"> 506</span>&#160;# Contributors</div><div class="line"><a name="l00507"></a><span class="lineno"> 507</span>&#160;</div><div class="line"><a name="l00508"></a><span class="lineno"> 508</span>&#160;If you want to contribute, please send patches as pull requests against the branch master.&lt;br/&gt;</div><div class="line"><a name="l00509"></a><span class="lineno"> 509</span>&#160;Check the [contributors list](https://github.com/skypjack/entt/blob/master/AUTHORS) to see who has partecipated so far.</div><div class="line"><a name="l00510"></a><span class="lineno"> 510</span>&#160;</div><div class="line"><a name="l00511"></a><span class="lineno"> 511</span>&#160;# License</div><div class="line"><a name="l00512"></a><span class="lineno"> 512</span>&#160;</div><div class="line"><a name="l00513"></a><span class="lineno"> 513</span>&#160;Code and documentation Copyright (c) 2017 Michele Caini.&lt;br/&gt;</div><div class="line"><a name="l00514"></a><span class="lineno"> 514</span>&#160;Code released under [the MIT license](https://github.com/skypjack/entt/blob/master/LICENSE).</div><div class="line"><a name="l00515"></a><span class="lineno"> 515</span>&#160;Docs released under [Creative Commons](https://github.com/skypjack/entt/blob/master/docs/LICENSE).</div><div class="line"><a name="l00516"></a><span class="lineno"> 516</span>&#160;</div><div class="line"><a name="l00517"></a><span class="lineno"> 517</span>&#160;# Donation</div><div class="line"><a name="l00518"></a><span class="lineno"> 518</span>&#160;</div><div class="line"><a name="l00519"></a><span class="lineno"> 519</span>&#160;Developing and maintaining `EnTT` takes some time and lots of coffee. It still lacks a proper test suite, documentation is partially incomplete and not all functionalities have been fully implemented yet.&lt;br/&gt;</div><div class="line"><a name="l00520"></a><span class="lineno"> 520</span>&#160;If you want to support this project, you can offer me an espresso. I&#39;m from Italy, we&#39;re used to turning the best coffee ever in code.&lt;br/&gt;</div><div class="line"><a name="l00521"></a><span class="lineno"> 521</span>&#160;Take a look at the donation button at the top of the page for more details or just click [here](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&amp;business=W2HF9FESD5LJY&amp;lc=IT&amp;item_name=Michele%20Caini&amp;currency_code=EUR&amp;bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted).</div></div><!-- fragment --></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>