75 lines
69 KiB
HTML
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
|
|
 <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> # The EnTT Framework</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span> </div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span> [](https://travis-ci.org/skypjack/entt)</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span> [](https://ci.appveyor.com/project/skypjack/entt)</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span> [](https://coveralls.io/github/skypjack/entt?branch=master)</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span> [](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)</div><div class="line"><a name="l00007"></a><span class="lineno"> 7</span> </div><div class="line"><a name="l00008"></a><span class="lineno"> 8</span> # Introduction</div><div class="line"><a name="l00009"></a><span class="lineno"> 9</span> </div><div class="line"><a name="l00010"></a><span class="lineno"> 10</span> `EnTT` is a header-only, tiny and easy to use framework written in modern C++.<br/></div><div class="line"><a name="l00011"></a><span class="lineno"> 11</span> It'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> </div><div class="line"><a name="l00013"></a><span class="lineno"> 13</span> * [Entity Systems Wiki](http://entity-systems.wikidot.com/)</div><div class="line"><a name="l00014"></a><span class="lineno"> 14</span> * [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> * [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> </div><div class="line"><a name="l00017"></a><span class="lineno"> 17</span> Originally, `EnTT` was written as a faster alternative to other well known and open source entity-component systems.<br/></div><div class="line"><a name="l00018"></a><span class="lineno"> 18</span> 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> </div><div class="line"><a name="l00020"></a><span class="lineno"> 20</span> ## Code Example</div><div class="line"><a name="l00021"></a><span class="lineno"> 21</span> </div><div class="line"><a name="l00022"></a><span class="lineno"> 22</span> ```cpp</div><div class="line"><a name="l00023"></a><span class="lineno"> 23</span> #include <registry.hpp></div><div class="line"><a name="l00024"></a><span class="lineno"> 24</span> </div><div class="line"><a name="l00025"></a><span class="lineno"> 25</span> struct Position {</div><div class="line"><a name="l00026"></a><span class="lineno"> 26</span>  float x;</div><div class="line"><a name="l00027"></a><span class="lineno"> 27</span>  float y;</div><div class="line"><a name="l00028"></a><span class="lineno"> 28</span> };</div><div class="line"><a name="l00029"></a><span class="lineno"> 29</span> </div><div class="line"><a name="l00030"></a><span class="lineno"> 30</span> struct Velocity {</div><div class="line"><a name="l00031"></a><span class="lineno"> 31</span>  float dx;</div><div class="line"><a name="l00032"></a><span class="lineno"> 32</span>  float dy;</div><div class="line"><a name="l00033"></a><span class="lineno"> 33</span> };</div><div class="line"><a name="l00034"></a><span class="lineno"> 34</span> </div><div class="line"><a name="l00035"></a><span class="lineno"> 35</span> void update(entt::DefaultRegistry &registry) {</div><div class="line"><a name="l00036"></a><span class="lineno"> 36</span>  auto view = ecs.view<Position, Velocity>();</div><div class="line"><a name="l00037"></a><span class="lineno"> 37</span> </div><div class="line"><a name="l00038"></a><span class="lineno"> 38</span>  for(auto entity: view) {</div><div class="line"><a name="l00039"></a><span class="lineno"> 39</span>  auto &position = view.get<Position>(entity);</div><div class="line"><a name="l00040"></a><span class="lineno"> 40</span>  auto &velocity = view.get<Velocity>(entity);</div><div class="line"><a name="l00041"></a><span class="lineno"> 41</span>  // ...</div><div class="line"><a name="l00042"></a><span class="lineno"> 42</span>  }</div><div class="line"><a name="l00043"></a><span class="lineno"> 43</span> }</div><div class="line"><a name="l00044"></a><span class="lineno"> 44</span> </div><div class="line"><a name="l00045"></a><span class="lineno"> 45</span> int main() {</div><div class="line"><a name="l00046"></a><span class="lineno"> 46</span>  entt::DefaultRegistry registry;</div><div class="line"><a name="l00047"></a><span class="lineno"> 47</span> </div><div class="line"><a name="l00048"></a><span class="lineno"> 48</span>  for(auto i = 0; i < 10; ++i) {</div><div class="line"><a name="l00049"></a><span class="lineno"> 49</span>  auto entity = registry.create();</div><div class="line"><a name="l00050"></a><span class="lineno"> 50</span>  registry.assign<Position>(entity, i * 1.f, i * 1.f);</div><div class="line"><a name="l00051"></a><span class="lineno"> 51</span>  if(i % 2 == 0) { registry.assign<Velocity>(entity, i * .1f, i * .1f); }</div><div class="line"><a name="l00052"></a><span class="lineno"> 52</span>  }</div><div class="line"><a name="l00053"></a><span class="lineno"> 53</span> </div><div class="line"><a name="l00054"></a><span class="lineno"> 54</span>  update(registry);</div><div class="line"><a name="l00055"></a><span class="lineno"> 55</span>  // ...</div><div class="line"><a name="l00056"></a><span class="lineno"> 56</span> }</div><div class="line"><a name="l00057"></a><span class="lineno"> 57</span> ```</div><div class="line"><a name="l00058"></a><span class="lineno"> 58</span> </div><div class="line"><a name="l00059"></a><span class="lineno"> 59</span> ## Motivation</div><div class="line"><a name="l00060"></a><span class="lineno"> 60</span> </div><div class="line"><a name="l00061"></a><span class="lineno"> 61</span> 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.<br/></div><div class="line"><a name="l00062"></a><span class="lineno"> 62</span> I did it, of course, but it wasn't much satisfying. Actually it wasn'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> 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> </div><div class="line"><a name="l00065"></a><span class="lineno"> 65</span> 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> </div><div class="line"><a name="l00067"></a><span class="lineno"> 67</span> ### Performance</div><div class="line"><a name="l00068"></a><span class="lineno"> 68</span> </div><div class="line"><a name="l00069"></a><span class="lineno"> 69</span> 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).<br/></div><div class="line"><a name="l00070"></a><span class="lineno"> 70</span> 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> </div><div class="line"><a name="l00072"></a><span class="lineno"> 72</span> | Benchmark | EntityX (experimental/compile_time) | EnTT |</div><div class="line"><a name="l00073"></a><span class="lineno"> 73</span> |-----------|-------------|-------------|</div><div class="line"><a name="l00074"></a><span class="lineno"> 74</span> | Creating 10M entities | 0.128881s | **0.0408754s** |</div><div class="line"><a name="l00075"></a><span class="lineno"> 75</span> | Destroying 10M entities | **0.0531374s** | 0.0545839s |</div><div class="line"><a name="l00076"></a><span class="lineno"> 76</span> | 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> | 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> | 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> | 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> | 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> | 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> | 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> | 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> | 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> | 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> | 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> | 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> | 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> | 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> | Sort 150k entities, one component | - | **0.0080046s** |</div><div class="line"><a name="l00091"></a><span class="lineno"> 91</span> | Sort 150k entities, match two components | - | **0.00608322s** |</div><div class="line"><a name="l00092"></a><span class="lineno"> 92</span> </div><div class="line"><a name="l00093"></a><span class="lineno"> 93</span> `EnTT` includes its own tests and benchmarks. See [benchmark.cpp](https://github.com/skypjack/entt/blob/master/test/benchmark.cpp) for further details.<br/></div><div class="line"><a name="l00094"></a><span class="lineno"> 94</span> 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> </div><div class="line"><a name="l00096"></a><span class="lineno"> 96</span> Of course, probably I'll try to get out of `EnTT` more features and better performance in the future, mainly for fun.<br/></div><div class="line"><a name="l00097"></a><span class="lineno"> 97</span> 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> </div><div class="line"><a name="l00099"></a><span class="lineno"> 99</span> # Build Instructions</div><div class="line"><a name="l00100"></a><span class="lineno"> 100</span> </div><div class="line"><a name="l00101"></a><span class="lineno"> 101</span> ## Requirements</div><div class="line"><a name="l00102"></a><span class="lineno"> 102</span> </div><div class="line"><a name="l00103"></a><span class="lineno"> 103</span> To be able to use `EnTT`, users must provide a full-featured compiler that supports at least C++14.<br/></div><div class="line"><a name="l00104"></a><span class="lineno"> 104</span> 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> </div><div class="line"><a name="l00106"></a><span class="lineno"> 106</span> * CMake version 3.2 or later.</div><div class="line"><a name="l00107"></a><span class="lineno"> 107</span> * Doxygen version 1.8 or later.</div><div class="line"><a name="l00108"></a><span class="lineno"> 108</span> </div><div class="line"><a name="l00109"></a><span class="lineno"> 109</span> ## Library</div><div class="line"><a name="l00110"></a><span class="lineno"> 110</span> </div><div class="line"><a name="l00111"></a><span class="lineno"> 111</span> `EnTT` is a header-only library. This means that including the `registry.hpp` header is enough to use it.<br/></div><div class="line"><a name="l00112"></a><span class="lineno"> 112</span> It'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> </div><div class="line"><a name="l00114"></a><span class="lineno"> 114</span> ```cpp</div><div class="line"><a name="l00115"></a><span class="lineno"> 115</span> #include <registry.hpp></div><div class="line"><a name="l00116"></a><span class="lineno"> 116</span> ```</div><div class="line"><a name="l00117"></a><span class="lineno"> 117</span> </div><div class="line"><a name="l00118"></a><span class="lineno"> 118</span> 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> </div><div class="line"><a name="l00120"></a><span class="lineno"> 120</span> ## Documentation</div><div class="line"><a name="l00121"></a><span class="lineno"> 121</span> </div><div class="line"><a name="l00122"></a><span class="lineno"> 122</span> ### API Reference</div><div class="line"><a name="l00123"></a><span class="lineno"> 123</span> </div><div class="line"><a name="l00124"></a><span class="lineno"> 124</span> 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> </div><div class="line"><a name="l00126"></a><span class="lineno"> 126</span> $ cd build</div><div class="line"><a name="l00127"></a><span class="lineno"> 127</span> $ cmake ..</div><div class="line"><a name="l00128"></a><span class="lineno"> 128</span> $ make docs</div><div class="line"><a name="l00129"></a><span class="lineno"> 129</span> </div><div class="line"><a name="l00130"></a><span class="lineno"> 130</span> 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> To navigate it with your favorite browser:</div><div class="line"><a name="l00132"></a><span class="lineno"> 132</span> </div><div class="line"><a name="l00133"></a><span class="lineno"> 133</span> $ cd build</div><div class="line"><a name="l00134"></a><span class="lineno"> 134</span> $ your_favorite_browser docs/html/index.html</div><div class="line"><a name="l00135"></a><span class="lineno"> 135</span> </div><div class="line"><a name="l00136"></a><span class="lineno"> 136</span> 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> </div><div class="line"><a name="l00138"></a><span class="lineno"> 138</span> ### Crash Course</div><div class="line"><a name="l00139"></a><span class="lineno"> 139</span> </div><div class="line"><a name="l00140"></a><span class="lineno"> 140</span> #### Vademecum</div><div class="line"><a name="l00141"></a><span class="lineno"> 141</span> </div><div class="line"><a name="l00142"></a><span class="lineno"> 142</span> The `Registry` to store, the `View`s to iterate. That's all.</div><div class="line"><a name="l00143"></a><span class="lineno"> 143</span> </div><div class="line"><a name="l00144"></a><span class="lineno"> 144</span> <!--</div><div class="line"><a name="l00145"></a><span class="lineno"> 145</span> `EnTT` has two main actors: the **Registry** and the **View**.<br/></div><div class="line"><a name="l00146"></a><span class="lineno"> 146</span> 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> </div><div class="line"><a name="l00148"></a><span class="lineno"> 148</span> #### The Registry</div><div class="line"><a name="l00149"></a><span class="lineno"> 149</span> </div><div class="line"><a name="l00150"></a><span class="lineno"> 150</span> There are two options to instantiate a registry:</div><div class="line"><a name="l00151"></a><span class="lineno"> 151</span> </div><div class="line"><a name="l00152"></a><span class="lineno"> 152</span> * Use the `DefaultRegistry` alias:</div><div class="line"><a name="l00153"></a><span class="lineno"> 153</span> </div><div class="line"><a name="l00154"></a><span class="lineno"> 154</span>  ```cpp</div><div class="line"><a name="l00155"></a><span class="lineno"> 155</span>  auto registry = entt::DefaultRegistry<Components...>{args...};</div><div class="line"><a name="l00156"></a><span class="lineno"> 156</span>  ```</div><div class="line"><a name="l00157"></a><span class="lineno"> 157</span> </div><div class="line"><a name="l00158"></a><span class="lineno"> 158</span>  Users must provide the whole list of components to be registered with the default registry and that's all.</div><div class="line"><a name="l00159"></a><span class="lineno"> 159</span> </div><div class="line"><a name="l00160"></a><span class="lineno"> 160</span> * Use directly the `Registry` class template:</div><div class="line"><a name="l00161"></a><span class="lineno"> 161</span> </div><div class="line"><a name="l00162"></a><span class="lineno"> 162</span>  ```cpp</div><div class="line"><a name="l00163"></a><span class="lineno"> 163</span>  auto registry = entt::Registry<std::uint16_t, Components...>{args...};</div><div class="line"><a name="l00164"></a><span class="lineno"> 164</span>  ```</div><div class="line"><a name="l00165"></a><span class="lineno"> 165</span> </div><div class="line"><a name="l00166"></a><span class="lineno"> 166</span>  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>  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> </div><div class="line"><a name="l00169"></a><span class="lineno"> 169</span> 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> </div><div class="line"><a name="l00171"></a><span class="lineno"> 171</span> 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> In almost all the cases those member functions can be used to query either the entity list or the components lists.<br/></div><div class="line"><a name="l00173"></a><span class="lineno"> 173</span> 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.<br/></div><div class="line"><a name="l00174"></a><span class="lineno"> 174</span> </div><div class="line"><a name="l00175"></a><span class="lineno"> 175</span> ```cpp</div><div class="line"><a name="l00176"></a><span class="lineno"> 176</span> bool b = registry.empty();</div><div class="line"><a name="l00177"></a><span class="lineno"> 177</span> // ...</div><div class="line"><a name="l00178"></a><span class="lineno"> 178</span> bool b = registry.empty<MyComponent>();</div><div class="line"><a name="l00179"></a><span class="lineno"> 179</span> ```</div><div class="line"><a name="l00180"></a><span class="lineno"> 180</span> </div><div class="line"><a name="l00181"></a><span class="lineno"> 181</span> 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> </div><div class="line"><a name="l00183"></a><span class="lineno"> 183</span> 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> </div><div class="line"><a name="l00185"></a><span class="lineno"> 185</span> ```cpp</div><div class="line"><a name="l00186"></a><span class="lineno"> 186</span> bool b = registry.valid(entity);</div><div class="line"><a name="l00187"></a><span class="lineno"> 187</span> ```</div><div class="line"><a name="l00188"></a><span class="lineno"> 188</span> </div><div class="line"><a name="l00189"></a><span class="lineno"> 189</span> Boring, I agree. Let's go to something more tasty.</div><div class="line"><a name="l00190"></a><span class="lineno"> 190</span> 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> </div><div class="line"><a name="l00192"></a><span class="lineno"> 192</span> 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> </div><div class="line"><a name="l00194"></a><span class="lineno"> 194</span> * 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> </div><div class="line"><a name="l00196"></a><span class="lineno"> 196</span>  ```cpp</div><div class="line"><a name="l00197"></a><span class="lineno"> 197</span>  auto entity = registry.create();</div><div class="line"><a name="l00198"></a><span class="lineno"> 198</span>  ```</div><div class="line"><a name="l00199"></a><span class="lineno"> 199</span> </div><div class="line"><a name="l00200"></a><span class="lineno"> 200</span> * 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> </div><div class="line"><a name="l00202"></a><span class="lineno"> 202</span>  ```cpp</div><div class="line"><a name="l00203"></a><span class="lineno"> 203</span>  auto entity = registry.create<Position, Velocity>();</div><div class="line"><a name="l00204"></a><span class="lineno"> 204</span>  ```</div><div class="line"><a name="l00205"></a><span class="lineno"> 205</span> </div><div class="line"><a name="l00206"></a><span class="lineno"> 206</span>  It's a helper function, mostly syncactic sugar and it's equivalent to the following snippet:</div><div class="line"><a name="l00207"></a><span class="lineno"> 207</span> </div><div class="line"><a name="l00208"></a><span class="lineno"> 208</span>  ```cpp</div><div class="line"><a name="l00209"></a><span class="lineno"> 209</span>  auto entity = registry.create();</div><div class="line"><a name="l00210"></a><span class="lineno"> 210</span>  registry.assign<Position>();</div><div class="line"><a name="l00211"></a><span class="lineno"> 211</span>  registry.assign<Velocity>();</div><div class="line"><a name="l00212"></a><span class="lineno"> 212</span>  ```</div><div class="line"><a name="l00213"></a><span class="lineno"> 213</span> </div><div class="line"><a name="l00214"></a><span class="lineno"> 214</span>  See below to find more about the `assign` member function.</div><div class="line"><a name="l00215"></a><span class="lineno"> 215</span> </div><div class="line"><a name="l00216"></a><span class="lineno"> 216</span> 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> </div><div class="line"><a name="l00218"></a><span class="lineno"> 218</span> ```cpp</div><div class="line"><a name="l00219"></a><span class="lineno"> 219</span> registry.destroy(entity);</div><div class="line"><a name="l00220"></a><span class="lineno"> 220</span> ```</div><div class="line"><a name="l00221"></a><span class="lineno"> 221</span> </div><div class="line"><a name="l00222"></a><span class="lineno"> 222</span> 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> </div><div class="line"><a name="l00224"></a><span class="lineno"> 224</span> 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> </div><div class="line"><a name="l00226"></a><span class="lineno"> 226</span> ```cpp</div><div class="line"><a name="l00227"></a><span class="lineno"> 227</span> registry.remove<Position>(entity);</div><div class="line"><a name="l00228"></a><span class="lineno"> 228</span> ```</div><div class="line"><a name="l00229"></a><span class="lineno"> 229</span> </div><div class="line"><a name="l00230"></a><span class="lineno"> 230</span> 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> If one of the requirements isn'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> </div><div class="line"><a name="l00233"></a><span class="lineno"> 233</span> 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> </div><div class="line"><a name="l00235"></a><span class="lineno"> 235</span> ```cpp</div><div class="line"><a name="l00236"></a><span class="lineno"> 236</span> registry.reset<Position>(entity);</div><div class="line"><a name="l00237"></a><span class="lineno"> 237</span> ```</div><div class="line"><a name="l00238"></a><span class="lineno"> 238</span> </div><div class="line"><a name="l00239"></a><span class="lineno"> 239</span> 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> </div><div class="line"><a name="l00241"></a><span class="lineno"> 241</span> There exist also two more _versions_ of the `reset` member function:</div><div class="line"><a name="l00242"></a><span class="lineno"> 242</span> </div><div class="line"><a name="l00243"></a><span class="lineno"> 243</span> * 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> </div><div class="line"><a name="l00245"></a><span class="lineno"> 245</span>  ```cpp</div><div class="line"><a name="l00246"></a><span class="lineno"> 246</span>  registry.reset<Position>();</div><div class="line"><a name="l00247"></a><span class="lineno"> 247</span>  ```</div><div class="line"><a name="l00248"></a><span class="lineno"> 248</span> </div><div class="line"><a name="l00249"></a><span class="lineno"> 249</span> * 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> </div><div class="line"><a name="l00251"></a><span class="lineno"> 251</span>  ```cpp</div><div class="line"><a name="l00252"></a><span class="lineno"> 252</span>  registry.reset();</div><div class="line"><a name="l00253"></a><span class="lineno"> 253</span>  ```</div><div class="line"><a name="l00254"></a><span class="lineno"> 254</span> </div><div class="line"><a name="l00255"></a><span class="lineno"> 255</span>  **Note**: the registry has an assert in debug mode that verifies that entities are no longer valid when it'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> </div><div class="line"><a name="l00257"></a><span class="lineno"> 257</span> 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> </div><div class="line"><a name="l00259"></a><span class="lineno"> 259</span> ```cpp</div><div class="line"><a name="l00260"></a><span class="lineno"> 260</span> registry.assign<Position>(entity, 0., 0.);</div><div class="line"><a name="l00261"></a><span class="lineno"> 261</span> // ...</div><div class="line"><a name="l00262"></a><span class="lineno"> 262</span> auto &velocity = registry.assign<Velocity>(entity);</div><div class="line"><a name="l00263"></a><span class="lineno"> 263</span> velocity.dx = 0.;</div><div class="line"><a name="l00264"></a><span class="lineno"> 264</span> velocity.dy = 0.;</div><div class="line"><a name="l00265"></a><span class="lineno"> 265</span> ```</div><div class="line"><a name="l00266"></a><span class="lineno"> 266</span> </div><div class="line"><a name="l00267"></a><span class="lineno"> 267</span> It requires that `entity` is valid. Moreover, the entity shouldn't have another instance of the component assigned to it.</div><div class="line"><a name="l00268"></a><span class="lineno"> 268</span> If one of the requirements isn'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> </div><div class="line"><a name="l00270"></a><span class="lineno"> 270</span> 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> </div><div class="line"><a name="l00272"></a><span class="lineno"> 272</span> ```cpp</div><div class="line"><a name="l00273"></a><span class="lineno"> 273</span> registry.replace<Position>(entity, 0., 0.);</div><div class="line"><a name="l00274"></a><span class="lineno"> 274</span> // ...</div><div class="line"><a name="l00275"></a><span class="lineno"> 275</span> auto &velocity = registry.replace<Velocity>(entity);</div><div class="line"><a name="l00276"></a><span class="lineno"> 276</span> velocity.dx = 0.;</div><div class="line"><a name="l00277"></a><span class="lineno"> 277</span> velocity.dy = 0.;</div><div class="line"><a name="l00278"></a><span class="lineno"> 278</span> ```</div><div class="line"><a name="l00279"></a><span class="lineno"> 279</span> </div><div class="line"><a name="l00280"></a><span class="lineno"> 280</span> 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> If one of the requirements isn'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> </div><div class="line"><a name="l00283"></a><span class="lineno"> 283</span> In case users want to assign a component to an entity, but it'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> (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> </div><div class="line"><a name="l00286"></a><span class="lineno"> 286</span> ```cpp</div><div class="line"><a name="l00287"></a><span class="lineno"> 287</span> registry.accomodate<Position>(entity, 0., 0.);</div><div class="line"><a name="l00288"></a><span class="lineno"> 288</span> // ...</div><div class="line"><a name="l00289"></a><span class="lineno"> 289</span> auto &velocity = registry.accomodate<Velocity>(entity);</div><div class="line"><a name="l00290"></a><span class="lineno"> 290</span> velocity.dx = 0.;</div><div class="line"><a name="l00291"></a><span class="lineno"> 291</span> velocity.dy = 0.;</div><div class="line"><a name="l00292"></a><span class="lineno"> 292</span> ```</div><div class="line"><a name="l00293"></a><span class="lineno"> 293</span> </div><div class="line"><a name="l00294"></a><span class="lineno"> 294</span> 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.<br/></div><div class="line"><a name="l00295"></a><span class="lineno"> 295</span> 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> </div><div class="line"><a name="l00297"></a><span class="lineno"> 297</span> ```cpp</div><div class="line"><a name="l00298"></a><span class="lineno"> 298</span> if(registry.has<Comp>(entity)) {</div><div class="line"><a name="l00299"></a><span class="lineno"> 299</span>  registry.replace<Comp>(entity, arg1, argN);</div><div class="line"><a name="l00300"></a><span class="lineno"> 300</span> } else {</div><div class="line"><a name="l00301"></a><span class="lineno"> 301</span>  registry.assign<Comp>(entity, arg1, argN);</div><div class="line"><a name="l00302"></a><span class="lineno"> 302</span> }</div><div class="line"><a name="l00303"></a><span class="lineno"> 303</span> ```</div><div class="line"><a name="l00304"></a><span class="lineno"> 304</span> </div><div class="line"><a name="l00305"></a><span class="lineno"> 305</span> 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> </div><div class="line"><a name="l00307"></a><span class="lineno"> 307</span> ```cpp</div><div class="line"><a name="l00308"></a><span class="lineno"> 308</span> bool b = registry.has<Position, Velocity>(entity);</div><div class="line"><a name="l00309"></a><span class="lineno"> 309</span> ```</div><div class="line"><a name="l00310"></a><span class="lineno"> 310</span> </div><div class="line"><a name="l00311"></a><span class="lineno"> 311</span> 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> </div><div class="line"><a name="l00313"></a><span class="lineno"> 313</span> Entities can also be cloned and either partially or fully copied:</div><div class="line"><a name="l00314"></a><span class="lineno"> 314</span> </div><div class="line"><a name="l00315"></a><span class="lineno"> 315</span> ```cpp</div><div class="line"><a name="l00316"></a><span class="lineno"> 316</span> auto entity = registry.clone(other);</div><div class="line"><a name="l00317"></a><span class="lineno"> 317</span> // ...</div><div class="line"><a name="l00318"></a><span class="lineno"> 318</span> auto &velocity = registry.copy<Velocity>(to, from);</div><div class="line"><a name="l00319"></a><span class="lineno"> 319</span> // ...</div><div class="line"><a name="l00320"></a><span class="lineno"> 320</span> registry.copy(dst, src);</div><div class="line"><a name="l00321"></a><span class="lineno"> 321</span> ```</div><div class="line"><a name="l00322"></a><span class="lineno"> 322</span> </div><div class="line"><a name="l00323"></a><span class="lineno"> 323</span> In particular:</div><div class="line"><a name="l00324"></a><span class="lineno"> 324</span> </div><div class="line"><a name="l00325"></a><span class="lineno"> 325</span> * 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> * 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> * 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> </div><div class="line"><a name="l00329"></a><span class="lineno"> 329</span> 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> 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> </div><div class="line"><a name="l00332"></a><span class="lineno"> 332</span> 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> </div><div class="line"><a name="l00334"></a><span class="lineno"> 334</span> ```cpp</div><div class="line"><a name="l00335"></a><span class="lineno"> 335</span> registry.swap<Position>(e1, e2);</div><div class="line"><a name="l00336"></a><span class="lineno"> 336</span> ```</div><div class="line"><a name="l00337"></a><span class="lineno"> 337</span> </div><div class="line"><a name="l00338"></a><span class="lineno"> 338</span> 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> 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> </div><div class="line"><a name="l00341"></a><span class="lineno"> 341</span> 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> </div><div class="line"><a name="l00343"></a><span class="lineno"> 343</span> ```cpp</div><div class="line"><a name="l00344"></a><span class="lineno"> 344</span> auto &position = registry.get<Position>(entity);</div><div class="line"><a name="l00345"></a><span class="lineno"> 345</span> ```</div><div class="line"><a name="l00346"></a><span class="lineno"> 346</span> </div><div class="line"><a name="l00347"></a><span class="lineno"> 347</span> 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> If one of the requirements isn'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> </div><div class="line"><a name="l00350"></a><span class="lineno"> 350</span> 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> </div><div class="line"><a name="l00352"></a><span class="lineno"> 352</span> * Components can be sorted according to a component:</div><div class="line"><a name="l00353"></a><span class="lineno"> 353</span> </div><div class="line"><a name="l00354"></a><span class="lineno"> 354</span>  ```cpp</div><div class="line"><a name="l00355"></a><span class="lineno"> 355</span>  registry.sort<Renderable>([](const auto &lhs, const auto &rhs) { return lhs.z < rhs.z; });</div><div class="line"><a name="l00356"></a><span class="lineno"> 356</span>  ```</div><div class="line"><a name="l00357"></a><span class="lineno"> 357</span> </div><div class="line"><a name="l00358"></a><span class="lineno"> 358</span> * 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> </div><div class="line"><a name="l00360"></a><span class="lineno"> 360</span>  ```cpp</div><div class="line"><a name="l00361"></a><span class="lineno"> 361</span>  registry.sort<Movement, Physics>();</div><div class="line"><a name="l00362"></a><span class="lineno"> 362</span>  ```</div><div class="line"><a name="l00363"></a><span class="lineno"> 363</span> </div><div class="line"><a name="l00364"></a><span class="lineno"> 364</span>  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> </div><div class="line"><a name="l00366"></a><span class="lineno"> 366</span> 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> </div><div class="line"><a name="l00368"></a><span class="lineno"> 368</span> ```cpp</div><div class="line"><a name="l00369"></a><span class="lineno"> 369</span> auto view = registry.view<Position, Velocity>();</div><div class="line"><a name="l00370"></a><span class="lineno"> 370</span> ```</div><div class="line"><a name="l00371"></a><span class="lineno"> 371</span> </div><div class="line"><a name="l00372"></a><span class="lineno"> 372</span> 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> </div><div class="line"><a name="l00374"></a><span class="lineno"> 374</span> #### The View</div><div class="line"><a name="l00375"></a><span class="lineno"> 375</span> </div><div class="line"><a name="l00376"></a><span class="lineno"> 376</span> There are two types of views:</div><div class="line"><a name="l00377"></a><span class="lineno"> 377</span> </div><div class="line"><a name="l00378"></a><span class="lineno"> 378</span> * **Single component view**.</div><div class="line"><a name="l00379"></a><span class="lineno"> 379</span> </div><div class="line"><a name="l00380"></a><span class="lineno"> 380</span>  A single component view gives direct access to both the components and the entities to which the components are assigned.<br/></div><div class="line"><a name="l00381"></a><span class="lineno"> 381</span>  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> </div><div class="line"><a name="l00383"></a><span class="lineno"> 383</span>  ```cpp</div><div class="line"><a name="l00384"></a><span class="lineno"> 384</span>  // Actual type is Registry<Components...>::view_type<Comp>, 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>  // ... well, auto is far easier to use in this case, isn't it?</div><div class="line"><a name="l00386"></a><span class="lineno"> 386</span>  auto view = registry.view<Sprite>();</div><div class="line"><a name="l00387"></a><span class="lineno"> 387</span>  ```</div><div class="line"><a name="l00388"></a><span class="lineno"> 388</span> </div><div class="line"><a name="l00389"></a><span class="lineno"> 389</span>  Components and entities are stored in tightly packed arrays and single component views are the fastest solution to iterate them.<br/></div><div class="line"><a name="l00390"></a><span class="lineno"> 390</span>  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> </div><div class="line"><a name="l00392"></a><span class="lineno"> 392</span>  ```cpp</div><div class="line"><a name="l00393"></a><span class="lineno"> 393</span>  auto view = registry.view<Sprite>();</div><div class="line"><a name="l00394"></a><span class="lineno"> 394</span> </div><div class="line"><a name="l00395"></a><span class="lineno"> 395</span>  for(auto entity: view) {</div><div class="line"><a name="l00396"></a><span class="lineno"> 396</span>  auto &sprite = registry.get<Sprite>(entity);</div><div class="line"><a name="l00397"></a><span class="lineno"> 397</span>  // ...</div><div class="line"><a name="l00398"></a><span class="lineno"> 398</span>  }</div><div class="line"><a name="l00399"></a><span class="lineno"> 399</span>  ```</div><div class="line"><a name="l00400"></a><span class="lineno"> 400</span> </div><div class="line"><a name="l00401"></a><span class="lineno"> 401</span>  Iterating a view this way returns entities that can be further used to get components or perform other activities.<br/></div><div class="line"><a name="l00402"></a><span class="lineno"> 402</span>  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> </div><div class="line"><a name="l00404"></a><span class="lineno"> 404</span>  ```cpp</div><div class="line"><a name="l00405"></a><span class="lineno"> 405</span>  auto view = registry.view<Sprite>();</div><div class="line"><a name="l00406"></a><span class="lineno"> 406</span>  const auto *data = view.data();</div><div class="line"><a name="l00407"></a><span class="lineno"> 407</span> </div><div class="line"><a name="l00408"></a><span class="lineno"> 408</span>  for(auto i = 0, end = view.size(); i < end; ++i) {</div><div class="line"><a name="l00409"></a><span class="lineno"> 409</span>  auto entity = *(data + i);</div><div class="line"><a name="l00410"></a><span class="lineno"> 410</span>  // ...</div><div class="line"><a name="l00411"></a><span class="lineno"> 411</span>  }</div><div class="line"><a name="l00412"></a><span class="lineno"> 412</span>  ```</div><div class="line"><a name="l00413"></a><span class="lineno"> 413</span> </div><div class="line"><a name="l00414"></a><span class="lineno"> 414</span>  Entites are good when the sole component isn't enough to perform a task.</div><div class="line"><a name="l00415"></a><span class="lineno"> 415</span>  Anyway they come with a cost: accessing components by entities has an extra level of indirection. It's pretty fast, but not that fast in some cases.<br/></div><div class="line"><a name="l00416"></a><span class="lineno"> 416</span>  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> </div><div class="line"><a name="l00418"></a><span class="lineno"> 418</span>  ```cpp</div><div class="line"><a name="l00419"></a><span class="lineno"> 419</span>  auto view = registry.view<Sprite>();</div><div class="line"><a name="l00420"></a><span class="lineno"> 420</span>  const auto *raw = view.raw();</div><div class="line"><a name="l00421"></a><span class="lineno"> 421</span> </div><div class="line"><a name="l00422"></a><span class="lineno"> 422</span>  for(auto i = 0, end = view.size(); i < end; ++i) {</div><div class="line"><a name="l00423"></a><span class="lineno"> 423</span>  auto &sprite = *(raw + i);</div><div class="line"><a name="l00424"></a><span class="lineno"> 424</span>  // ...</div><div class="line"><a name="l00425"></a><span class="lineno"> 425</span>  }</div><div class="line"><a name="l00426"></a><span class="lineno"> 426</span>  ```</div><div class="line"><a name="l00427"></a><span class="lineno"> 427</span> </div><div class="line"><a name="l00428"></a><span class="lineno"> 428</span>  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> </div><div class="line"><a name="l00430"></a><span class="lineno"> 430</span> * **Multi component view**.</div><div class="line"><a name="l00431"></a><span class="lineno"> 431</span> </div><div class="line"><a name="l00432"></a><span class="lineno"> 432</span>  A multi component view gives access only to the entities to which the components are assigned.<br/></div><div class="line"><a name="l00433"></a><span class="lineno"> 433</span>  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> </div><div class="line"><a name="l00435"></a><span class="lineno"> 435</span>  ```cpp</div><div class="line"><a name="l00436"></a><span class="lineno"> 436</span>  // Actual type is Registry<Components...>::view_type<Comp...>, 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>  // ... well, auto is far easier to use in this case, isn't it?</div><div class="line"><a name="l00438"></a><span class="lineno"> 438</span>  auto view = registry.view<Position, Velocity>();</div><div class="line"><a name="l00439"></a><span class="lineno"> 439</span>  ```</div><div class="line"><a name="l00440"></a><span class="lineno"> 440</span> </div><div class="line"><a name="l00441"></a><span class="lineno"> 441</span>  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> </div><div class="line"><a name="l00443"></a><span class="lineno"> 443</span>  ```cpp</div><div class="line"><a name="l00444"></a><span class="lineno"> 444</span>  auto view = registry.view<Position, Velocity>();</div><div class="line"><a name="l00445"></a><span class="lineno"> 445</span> </div><div class="line"><a name="l00446"></a><span class="lineno"> 446</span>  for(auto entity: view) {</div><div class="line"><a name="l00447"></a><span class="lineno"> 447</span>  auto &position = registry.get<Position>(entity);</div><div class="line"><a name="l00448"></a><span class="lineno"> 448</span>  auto &velocity = registry.get<Velocity>(entity);</div><div class="line"><a name="l00449"></a><span class="lineno"> 449</span>  // ...</div><div class="line"><a name="l00450"></a><span class="lineno"> 450</span>  }</div><div class="line"><a name="l00451"></a><span class="lineno"> 451</span>  ```</div><div class="line"><a name="l00452"></a><span class="lineno"> 452</span> </div><div class="line"><a name="l00453"></a><span class="lineno"> 453</span>  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>  Iterators of a multi component view pick the shortest array up and use it to visit the smallest set of potential entities.<br/></div><div class="line"><a name="l00455"></a><span class="lineno"> 455</span>  The choice is performed when the view is constructed. It'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>  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> </div><div class="line"><a name="l00458"></a><span class="lineno"> 458</span>  **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>  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> </div><div class="line"><a name="l00461"></a><span class="lineno"> 461</span> 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> 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.<br/></div><div class="line"><a name="l00463"></a><span class="lineno"> 463</span> I'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> </div><div class="line"><a name="l00465"></a><span class="lineno"> 465</span> #### Side notes</div><div class="line"><a name="l00466"></a><span class="lineno"> 466</span> </div><div class="line"><a name="l00467"></a><span class="lineno"> 467</span> * 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> </div><div class="line"><a name="l00469"></a><span class="lineno"> 469</span> * 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.<br/></div><div class="line"><a name="l00470"></a><span class="lineno"> 470</span>  `EnTT` partially solves the problem with a few limitations:</div><div class="line"><a name="l00471"></a><span class="lineno"> 471</span> </div><div class="line"><a name="l00472"></a><span class="lineno"> 472</span>  * 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>  * 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>  * 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> </div><div class="line"><a name="l00476"></a><span class="lineno"> 476</span>  Entities that are not the current one (that is the one returned by the iterator) cannot be deleted from within a loop.<br/></div><div class="line"><a name="l00477"></a><span class="lineno"> 477</span>  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.<br/></div><div class="line"><a name="l00478"></a><span class="lineno"> 478</span>  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> </div><div class="line"><a name="l00480"></a><span class="lineno"> 480</span>  * 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>  * 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> </div><div class="line"><a name="l00483"></a><span class="lineno"> 483</span> * Iterators aren't thread safe. Do no try to iterate over a set of components and modify them concurrently.<br/></div><div class="line"><a name="l00484"></a><span class="lineno"> 484</span>  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't be a problem at all.<br/></div><div class="line"><a name="l00485"></a><span class="lineno"> 485</span>  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> --></div><div class="line"><a name="l00487"></a><span class="lineno"> 487</span> </div><div class="line"><a name="l00488"></a><span class="lineno"> 488</span> ## Tests</div><div class="line"><a name="l00489"></a><span class="lineno"> 489</span> </div><div class="line"><a name="l00490"></a><span class="lineno"> 490</span> To compile and run the tests, `EnTT` requires *googletest*.<br/></div><div class="line"><a name="l00491"></a><span class="lineno"> 491</span> `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> </div><div class="line"><a name="l00493"></a><span class="lineno"> 493</span> To build the tests:</div><div class="line"><a name="l00494"></a><span class="lineno"> 494</span> </div><div class="line"><a name="l00495"></a><span class="lineno"> 495</span> * `$ cd build`</div><div class="line"><a name="l00496"></a><span class="lineno"> 496</span> * `$ cmake ..`</div><div class="line"><a name="l00497"></a><span class="lineno"> 497</span> * `$ make`</div><div class="line"><a name="l00498"></a><span class="lineno"> 498</span> * `$ make test`</div><div class="line"><a name="l00499"></a><span class="lineno"> 499</span> </div><div class="line"><a name="l00500"></a><span class="lineno"> 500</span> To build the benchmarks, use the following line instead:</div><div class="line"><a name="l00501"></a><span class="lineno"> 501</span> </div><div class="line"><a name="l00502"></a><span class="lineno"> 502</span> * `$ cmake -DCMAKE_BUILD_TYPE=Release ..`</div><div class="line"><a name="l00503"></a><span class="lineno"> 503</span> </div><div class="line"><a name="l00504"></a><span class="lineno"> 504</span> Benchmarks are compiled only in release mode currently.</div><div class="line"><a name="l00505"></a><span class="lineno"> 505</span> </div><div class="line"><a name="l00506"></a><span class="lineno"> 506</span> # Contributors</div><div class="line"><a name="l00507"></a><span class="lineno"> 507</span> </div><div class="line"><a name="l00508"></a><span class="lineno"> 508</span> If you want to contribute, please send patches as pull requests against the branch master.<br/></div><div class="line"><a name="l00509"></a><span class="lineno"> 509</span> 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> </div><div class="line"><a name="l00511"></a><span class="lineno"> 511</span> # License</div><div class="line"><a name="l00512"></a><span class="lineno"> 512</span> </div><div class="line"><a name="l00513"></a><span class="lineno"> 513</span> Code and documentation Copyright (c) 2017 Michele Caini.<br/></div><div class="line"><a name="l00514"></a><span class="lineno"> 514</span> 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> 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> </div><div class="line"><a name="l00517"></a><span class="lineno"> 517</span> # Donation</div><div class="line"><a name="l00518"></a><span class="lineno"> 518</span> </div><div class="line"><a name="l00519"></a><span class="lineno"> 519</span> 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.<br/></div><div class="line"><a name="l00520"></a><span class="lineno"> 520</span> If you want to support this project, you can offer me an espresso. I'm from Italy, we're used to turning the best coffee ever in code.<br/></div><div class="line"><a name="l00521"></a><span class="lineno"> 521</span> 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&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&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  <a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/>
|
|
</a> 1.8.13
|
|
</small></address>
|
|
</body>
|
|
</html>
|