Files
entt/faq_8md_source.html
T
2019-08-29 16:16:50 +02:00

75 lines
22 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!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: docs/md/faq.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">3.1.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">docs/md/faq.md</div> </div>
</div><!--header-->
<div class="contents">
<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span>&#160;# Frequently Asked Questions</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;&lt;!--</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span>&#160;@cond TURN_OFF_DOXYGEN</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span>&#160;--&gt;</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span>&#160;# Table of Contents</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](#introduction)</div><div class="line"><a name="l00009"></a><span class="lineno"> 9</span>&#160;* [FAQ](#faq)</div><div class="line"><a name="l00010"></a><span class="lineno"> 10</span>&#160; * [Why is my debug build on Windows so slow?](#why-is-my-debug-build-on-windows-so-slow)</div><div class="line"><a name="l00011"></a><span class="lineno"> 11</span>&#160; * [How can I represent hierarchies with my components?](#how-can-i-represent-hierarchies-with-my-components)</div><div class="line"><a name="l00012"></a><span class="lineno"> 12</span>&#160; * [Custom entity identifiers: yay or nay?](#custom-entity-identifiers-yay-or-nay)</div><div class="line"><a name="l00013"></a><span class="lineno"> 13</span>&#160; * [Warning C4307: integral constant overflow](#warning-C4307-integral-constant-overflow)</div><div class="line"><a name="l00014"></a><span class="lineno"> 14</span>&#160; * [Warning C4003: the min, the max and the macro](#warning-C4003-the-min-the-max-and-the-macro)</div><div class="line"><a name="l00015"></a><span class="lineno"> 15</span>&#160;&lt;!--</div><div class="line"><a name="l00016"></a><span class="lineno"> 16</span>&#160;@endcond TURN_OFF_DOXYGEN</div><div class="line"><a name="l00017"></a><span class="lineno"> 17</span>&#160;--&gt;</div><div class="line"><a name="l00018"></a><span class="lineno"> 18</span>&#160;</div><div class="line"><a name="l00019"></a><span class="lineno"> 19</span>&#160;# Introduction</div><div class="line"><a name="l00020"></a><span class="lineno"> 20</span>&#160;</div><div class="line"><a name="l00021"></a><span class="lineno"> 21</span>&#160;This is a constantly updated section where I&#39;ll try to put the answers to the</div><div class="line"><a name="l00022"></a><span class="lineno"> 22</span>&#160;most frequently asked questions.&lt;br/&gt;</div><div class="line"><a name="l00023"></a><span class="lineno"> 23</span>&#160;If you don&#39;t find your answer here, there are two cases: nobody has done it yet</div><div class="line"><a name="l00024"></a><span class="lineno"> 24</span>&#160;or this section needs updating. In both cases, try to</div><div class="line"><a name="l00025"></a><span class="lineno"> 25</span>&#160;[open a new issue](https://github.com/skypjack/entt/issues/new) or enter the</div><div class="line"><a name="l00026"></a><span class="lineno"> 26</span>&#160;[gitter channel](https://gitter.im/skypjack/entt) and ask your question.</div><div class="line"><a name="l00027"></a><span class="lineno"> 27</span>&#160;Probably someone already has an answer for you and we can then integrate this</div><div class="line"><a name="l00028"></a><span class="lineno"> 28</span>&#160;part of the documentation.</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;# FAQ</div><div class="line"><a name="l00031"></a><span class="lineno"> 31</span>&#160;</div><div class="line"><a name="l00032"></a><span class="lineno"> 32</span>&#160;## Why is my debug build on Windows so slow?</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;`EnTT` is an experimental project that I also use to keep me up-to-date with the</div><div class="line"><a name="l00035"></a><span class="lineno"> 35</span>&#160;latest revision of the language and the standard library. For this reason, it&#39;s</div><div class="line"><a name="l00036"></a><span class="lineno"> 36</span>&#160;likely that some classes you&#39;re working with are using standard containers under</div><div class="line"><a name="l00037"></a><span class="lineno"> 37</span>&#160;the hood.&lt;br/&gt;</div><div class="line"><a name="l00038"></a><span class="lineno"> 38</span>&#160;Unfortunately, it&#39;s known that the standard containers aren&#39;t particularly</div><div class="line"><a name="l00039"></a><span class="lineno"> 39</span>&#160;performing in debugging (the reasons for this go beyond this document) and are</div><div class="line"><a name="l00040"></a><span class="lineno"> 40</span>&#160;even less so on Windows apparently. Fortunately this can also be mitigated a</div><div class="line"><a name="l00041"></a><span class="lineno"> 41</span>&#160;lot, achieving good results in many cases.</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;First of all, there are two things to do in a Windows project:</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;* Disable the [`/JMC`](https://docs.microsoft.com/cpp/build/reference/jmc)</div><div class="line"><a name="l00046"></a><span class="lineno"> 46</span>&#160; option (_Just My Code_ debugging), available starting in Visual Studio 2017</div><div class="line"><a name="l00047"></a><span class="lineno"> 47</span>&#160; version 15.8.</div><div class="line"><a name="l00048"></a><span class="lineno"> 48</span>&#160;</div><div class="line"><a name="l00049"></a><span class="lineno"> 49</span>&#160;* Set the [`_ITERATOR_DEBUG_LEVEL`](https://docs.microsoft.com/cpp/standard-library/iterator-debug-level)</div><div class="line"><a name="l00050"></a><span class="lineno"> 50</span>&#160; macro to 0. This will disable checked iterators and iterator debugging.</div><div class="line"><a name="l00051"></a><span class="lineno"> 51</span>&#160;</div><div class="line"><a name="l00052"></a><span class="lineno"> 52</span>&#160;Moreover, the macro `ENTT_DISABLE_ASSERT` should be defined to disable internal</div><div class="line"><a name="l00053"></a><span class="lineno"> 53</span>&#160;checks made by `EnTT` in debug. These are asserts introduced to help the users,</div><div class="line"><a name="l00054"></a><span class="lineno"> 54</span>&#160;but require to access to the underlying containers and therefore risk ruining</div><div class="line"><a name="l00055"></a><span class="lineno"> 55</span>&#160;the performance in some cases.</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;With these changes, debug performance should increase enough for most cases. If</div><div class="line"><a name="l00058"></a><span class="lineno"> 58</span>&#160;you want something more, you can can also switch to an optimization level `O0`</div><div class="line"><a name="l00059"></a><span class="lineno"> 59</span>&#160;or preferably `O1`.</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;## How can I represent hierarchies with my components?</div><div class="line"><a name="l00062"></a><span class="lineno"> 62</span>&#160;</div><div class="line"><a name="l00063"></a><span class="lineno"> 63</span>&#160;This is one of the first questions that anyone makes when starting to work with</div><div class="line"><a name="l00064"></a><span class="lineno"> 64</span>&#160;the entity-component-system architectural pattern.&lt;br/&gt;</div><div class="line"><a name="l00065"></a><span class="lineno"> 65</span>&#160;There are several approaches to the problem and what’s the best one depends</div><div class="line"><a name="l00066"></a><span class="lineno"> 66</span>&#160;mainly on the real problem one is facing. In all cases, how to do it doesn&#39;t</div><div class="line"><a name="l00067"></a><span class="lineno"> 67</span>&#160;strictly depend on the library in use, but the latter can certainly allow or</div><div class="line"><a name="l00068"></a><span class="lineno"> 68</span>&#160;not different techniques depending on how the data are laid out.</div><div class="line"><a name="l00069"></a><span class="lineno"> 69</span>&#160;</div><div class="line"><a name="l00070"></a><span class="lineno"> 70</span>&#160;I tried to describe some of the techniques that fit well with the model of</div><div class="line"><a name="l00071"></a><span class="lineno"> 71</span>&#160;`EnTT`. [Here](https://skypjack.github.io/2019-06-25-ecs-baf-part-4/) is the</div><div class="line"><a name="l00072"></a><span class="lineno"> 72</span>&#160;first post of a series that tries to explore the problem. More will probably</div><div class="line"><a name="l00073"></a><span class="lineno"> 73</span>&#160;come in future.</div><div class="line"><a name="l00074"></a><span class="lineno"> 74</span>&#160;</div><div class="line"><a name="l00075"></a><span class="lineno"> 75</span>&#160;Long story short, you can always define a tree where the nodes expose implicit</div><div class="line"><a name="l00076"></a><span class="lineno"> 76</span>&#160;lists of children by means of the following type:</div><div class="line"><a name="l00077"></a><span class="lineno"> 77</span>&#160;</div><div class="line"><a name="l00078"></a><span class="lineno"> 78</span>&#160;```cpp</div><div class="line"><a name="l00079"></a><span class="lineno"> 79</span>&#160;struct relationship {</div><div class="line"><a name="l00080"></a><span class="lineno"> 80</span>&#160; std::size_t children{};</div><div class="line"><a name="l00081"></a><span class="lineno"> 81</span>&#160; entt::entity first{entt::null};</div><div class="line"><a name="l00082"></a><span class="lineno"> 82</span>&#160; entt::entity prev{entt::null};</div><div class="line"><a name="l00083"></a><span class="lineno"> 83</span>&#160; entt::entity next{entt::null};</div><div class="line"><a name="l00084"></a><span class="lineno"> 84</span>&#160; entt::entity parent{entt::null};</div><div class="line"><a name="l00085"></a><span class="lineno"> 85</span>&#160; // ... other data members ...</div><div class="line"><a name="l00086"></a><span class="lineno"> 86</span>&#160;};</div><div class="line"><a name="l00087"></a><span class="lineno"> 87</span>&#160;```</div><div class="line"><a name="l00088"></a><span class="lineno"> 88</span>&#160;</div><div class="line"><a name="l00089"></a><span class="lineno"> 89</span>&#160;The sort functionalities of `EnTT`, the groups and all the other features of the</div><div class="line"><a name="l00090"></a><span class="lineno"> 90</span>&#160;library can help then to get the best in terms of data locality and therefore</div><div class="line"><a name="l00091"></a><span class="lineno"> 91</span>&#160;performance from this component.</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;## Custom entity identifiers: yay or nay?</div><div class="line"><a name="l00094"></a><span class="lineno"> 94</span>&#160;</div><div class="line"><a name="l00095"></a><span class="lineno"> 95</span>&#160;Custom entity identifiers are definitely a good idea in two cases at least:</div><div class="line"><a name="l00096"></a><span class="lineno"> 96</span>&#160;</div><div class="line"><a name="l00097"></a><span class="lineno"> 97</span>&#160;* If `std::uint32_t` isn&#39;t large enough as an underlying type.</div><div class="line"><a name="l00098"></a><span class="lineno"> 98</span>&#160;* If you want to avoid conflicts when using multiple registries.</div><div class="line"><a name="l00099"></a><span class="lineno"> 99</span>&#160;</div><div class="line"><a name="l00100"></a><span class="lineno"> 100</span>&#160;These identifiers are nothing more than enum classes with some salt.&lt;br/&gt;</div><div class="line"><a name="l00101"></a><span class="lineno"> 101</span>&#160;To simplify the creation of new identifiers, `EnTT` provides the macro</div><div class="line"><a name="l00102"></a><span class="lineno"> 102</span>&#160;`ENTT_OPAQUE_TYPE` that accepts two arguments:</div><div class="line"><a name="l00103"></a><span class="lineno"> 103</span>&#160;</div><div class="line"><a name="l00104"></a><span class="lineno"> 104</span>&#160;* The name you want to give to the new identifier (watch out for namespaces).</div><div class="line"><a name="l00105"></a><span class="lineno"> 105</span>&#160;* The underlying type to use (either `std::uint16_t`, `std::uint32_t`</div><div class="line"><a name="l00106"></a><span class="lineno"> 106</span>&#160; or `std::uint64_t`).</div><div class="line"><a name="l00107"></a><span class="lineno"> 107</span>&#160;</div><div class="line"><a name="l00108"></a><span class="lineno"> 108</span>&#160;In fact, this is the definition of `entt::entity`:</div><div class="line"><a name="l00109"></a><span class="lineno"> 109</span>&#160;</div><div class="line"><a name="l00110"></a><span class="lineno"> 110</span>&#160;```cpp</div><div class="line"><a name="l00111"></a><span class="lineno"> 111</span>&#160;ENTT_OPAQUE_TYPE(entity, std::uint32_t)</div><div class="line"><a name="l00112"></a><span class="lineno"> 112</span>&#160;```</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;The use of this macro is highly recommended, so as not to run into problems if</div><div class="line"><a name="l00115"></a><span class="lineno"> 115</span>&#160;the requirements for the identifiers should change in the future.</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;## Warning C4307: integral constant overflow</div><div class="line"><a name="l00118"></a><span class="lineno"> 118</span>&#160;</div><div class="line"><a name="l00119"></a><span class="lineno"> 119</span>&#160;According to [this](https://github.com/skypjack/entt/issues/121) issue, using a</div><div class="line"><a name="l00120"></a><span class="lineno"> 120</span>&#160;hashed string under VS could generate a warning.&lt;br/&gt;</div><div class="line"><a name="l00121"></a><span class="lineno"> 121</span>&#160;First of all, I want to reassure you: it&#39;s expected and harmless. However, it</div><div class="line"><a name="l00122"></a><span class="lineno"> 122</span>&#160;can be annoying.</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;To suppress it and if you don&#39;t want to suppress all the other warnings as well,</div><div class="line"><a name="l00125"></a><span class="lineno"> 125</span>&#160;here is a workaround in the form of a macro:</div><div class="line"><a name="l00126"></a><span class="lineno"> 126</span>&#160;</div><div class="line"><a name="l00127"></a><span class="lineno"> 127</span>&#160;```cpp</div><div class="line"><a name="l00128"></a><span class="lineno"> 128</span>&#160;#if defined(_MSC_VER)</div><div class="line"><a name="l00129"></a><span class="lineno"> 129</span>&#160; #define HS(str)\</div><div class="line"><a name="l00130"></a><span class="lineno"> 130</span>&#160; __pragma(warning(push))\</div><div class="line"><a name="l00131"></a><span class="lineno"> 131</span>&#160; __pragma(warning(disable:4307))\</div><div class="line"><a name="l00132"></a><span class="lineno"> 132</span>&#160; entt::hashed_string{str}\</div><div class="line"><a name="l00133"></a><span class="lineno"> 133</span>&#160; __pragma(warning(pop))</div><div class="line"><a name="l00134"></a><span class="lineno"> 134</span>&#160;#else</div><div class="line"><a name="l00135"></a><span class="lineno"> 135</span>&#160; #define HS(str) entt::hashed_string{str}</div><div class="line"><a name="l00136"></a><span class="lineno"> 136</span>&#160;#endif</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;</div><div class="line"><a name="l00139"></a><span class="lineno"> 139</span>&#160;With an example of use included:</div><div class="line"><a name="l00140"></a><span class="lineno"> 140</span>&#160;</div><div class="line"><a name="l00141"></a><span class="lineno"> 141</span>&#160;```cpp</div><div class="line"><a name="l00142"></a><span class="lineno"> 142</span>&#160;constexpr auto identifier = HS(&quot;my/resource/identifier&quot;);</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;</div><div class="line"><a name="l00145"></a><span class="lineno"> 145</span>&#160;Thanks to [huwpascoe](https://github.com/huwpascoe) for the courtesy.</div><div class="line"><a name="l00146"></a><span class="lineno"> 146</span>&#160;</div><div class="line"><a name="l00147"></a><span class="lineno"> 147</span>&#160;## Warning C4003: the min, the max and the macro</div><div class="line"><a name="l00148"></a><span class="lineno"> 148</span>&#160;</div><div class="line"><a name="l00149"></a><span class="lineno"> 149</span>&#160;On Windows, a header file defines two macros `min` and `max` which may result in</div><div class="line"><a name="l00150"></a><span class="lineno"> 150</span>&#160;conflicts with their counterparts in the standard library and therefore in</div><div class="line"><a name="l00151"></a><span class="lineno"> 151</span>&#160;errors during compilation.</div><div class="line"><a name="l00152"></a><span class="lineno"> 152</span>&#160;</div><div class="line"><a name="l00153"></a><span class="lineno"> 153</span>&#160;It&#39;s a pretty big problem but fortunately it&#39;s not a problem of `EnTT` and there</div><div class="line"><a name="l00154"></a><span class="lineno"> 154</span>&#160;is a fairly simple solution to it.&lt;br/&gt;</div><div class="line"><a name="l00155"></a><span class="lineno"> 155</span>&#160;It consists in defining the `NOMINMAX` macro before to include any other header</div><div class="line"><a name="l00156"></a><span class="lineno"> 156</span>&#160;so as to get rid of the extra definitions:</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;```cpp</div><div class="line"><a name="l00159"></a><span class="lineno"> 159</span>&#160;#define NOMINMAX</div><div class="line"><a name="l00160"></a><span class="lineno"> 160</span>&#160;```</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;Please refer to [this](https://github.com/skypjack/entt/issues/96) issue for</div><div class="line"><a name="l00163"></a><span class="lineno"> 163</span>&#160;more details.</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>