entt/md_docs_md_faq.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<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.16"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>EnTT: Frequently Asked Questions</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.2.2</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.16 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- 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><!-- top -->
<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">Frequently Asked Questions </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="autotoc_md51"></a>
Introduction</h1>
<p>This is a constantly updated section where I'll try to put the answers to the most frequently asked questions.<br  />
 If you don't find your answer here, there are two cases: nobody has done it yet or this section needs updating. In both cases, try to <a href="https://github.com/skypjack/entt/issues/new">open a new issue</a> or enter the <a href="https://gitter.im/skypjack/entt">gitter channel</a> and ask your question. Probably someone already has an answer for you and we can then integrate this part of the documentation.</p>
<h1><a class="anchor" id="autotoc_md52"></a>
FAQ</h1>
<h2><a class="anchor" id="autotoc_md53"></a>
Why is my debug build on Windows so slow?</h2>
<p><code>EnTT</code> is an experimental project that I also use to keep me up-to-date with the latest revision of the language and the standard library. For this reason, it's likely that some classes you're working with are using standard containers under the hood.<br  />
 Unfortunately, it's known that the standard containers aren't particularly performing in debugging (the reasons for this go beyond this document) and are even less so on Windows apparently. Fortunately this can also be mitigated a lot, achieving good results in many cases.</p>
<p>First of all, there are two things to do in a Windows project:</p>
<ul>
<li>Disable the <a href="https://docs.microsoft.com/cpp/build/reference/jmc"><code>/JMC</code></a> option (<em>Just My Code</em> debugging), available starting in Visual Studio 2017 version 15.8.</li>
<li>Set the <a href="https://docs.microsoft.com/cpp/standard-library/iterator-debug-level"><code>_ITERATOR_DEBUG_LEVEL</code></a> macro to 0. This will disable checked iterators and iterator debugging.</li>
</ul>
<p>Moreover, the macro <code>ENTT_DISABLE_ASSERT</code> should be defined to disable internal checks made by <code>EnTT</code> in debug. These are asserts introduced to help the users, but require to access to the underlying containers and therefore risk ruining the performance in some cases.</p>
<p>With these changes, debug performance should increase enough for most cases. If you want something more, you can can also switch to an optimization level <code>O0</code> or preferably <code>O1</code>.</p>
<h2><a class="anchor" id="autotoc_md54"></a>
How can I represent hierarchies with my components?</h2>
<p>This is one of the first questions that anyone makes when starting to work with the entity-component-system architectural pattern.<br  />
 There are several approaches to the problem and what’s the best one depends mainly on the real problem one is facing. In all cases, how to do it doesn't strictly depend on the library in use, but the latter can certainly allow or not different techniques depending on how the data are laid out.</p>
<p>I tried to describe some of the techniques that fit well with the model of <code>EnTT</code>. <a href="https://skypjack.github.io/2019-06-25-ecs-baf-part-4/">Here</a> is the first post of a series that tries to explore the problem. More will probably come in future.</p>
<p>Long story short, you can always define a tree where the nodes expose implicit lists of children by means of the following type:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>relationship {</div>
<div class="line">    std::size_t children{};</div>
<div class="line">    entt::entity first{<a class="code" href="namespaceentt.html#a588326af8f6f902a6c0b57d3f9fc6c17">entt::null</a>};</div>
<div class="line">    entt::entity prev{<a class="code" href="namespaceentt.html#a588326af8f6f902a6c0b57d3f9fc6c17">entt::null</a>};</div>
<div class="line">    entt::entity next{<a class="code" href="namespaceentt.html#a588326af8f6f902a6c0b57d3f9fc6c17">entt::null</a>};</div>
<div class="line">    entt::entity parent{<a class="code" href="namespaceentt.html#a588326af8f6f902a6c0b57d3f9fc6c17">entt::null</a>};</div>
<div class="line">    <span class="comment">// ... other data members ...</span></div>
<div class="line">};</div>
</div><!-- fragment --><p>The sort functionalities of <code>EnTT</code>, the groups and all the other features of the library can help then to get the best in terms of data locality and therefore performance from this component.</p>
<h2><a class="anchor" id="autotoc_md55"></a>
Custom entity identifiers: yay or nay?</h2>
<p>Custom entity identifiers are definitely a good idea in two cases at least:</p>
<ul>
<li>If <code>std::uint32_t</code> isn't large enough as an underlying type.</li>
<li>If you want to avoid conflicts when using multiple registries.</li>
</ul>
<p>These identifiers are nothing more than enum classes with some salt.<br  />
 To simplify the creation of new identifiers, <code>EnTT</code> provides the macro <code>ENTT_OPAQUE_TYPE</code> that accepts two arguments:</p>
<ul>
<li>The name you want to give to the new identifier (watch out for namespaces).</li>
<li>The underlying type to use (either <code>std::uint16_t</code>, <code>std::uint32_t</code> or <code>std::uint64_t</code>).</li>
</ul>
<p>In fact, this is the definition of <code>entt::entity</code>:</p>
<div class="fragment"><div class="line">ENTT_OPAQUE_TYPE(entity, std::uint32_t)</div>
</div><!-- fragment --><p>The use of this macro is highly recommended, so as not to run into problems if the requirements for the identifiers should change in the future.</p>
<h2><a class="anchor" id="autotoc_md56"></a>
Warning C4307: integral constant overflow</h2>
<p>According to <a href="https://github.com/skypjack/entt/issues/121">this</a> issue, using a hashed string under VS could generate a warning.<br  />
 First of all, I want to reassure you: it's expected and harmless. However, it can be annoying.</p>
<p>To suppress it and if you don't want to suppress all the other warnings as well, here is a workaround in the form of a macro:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#if defined(_MSC_VER)</span></div>
<div class="line"><span class="preprocessor">    #define HS(str)\</span></div>
<div class="line"><span class="preprocessor">        __pragma(warning(push))\</span></div>
<div class="line"><span class="preprocessor">        __pragma(warning(disable:4307))\</span></div>
<div class="line"><span class="preprocessor">        entt::hashed_string{str}\</span></div>
<div class="line"><span class="preprocessor">        __pragma(warning(pop))</span></div>
<div class="line"><span class="preprocessor">#else</span></div>
<div class="line"><span class="preprocessor">    #define HS(str) entt::hashed_string{str}</span></div>
<div class="line"><span class="preprocessor">#endif</span></div>
</div><!-- fragment --><p>With an example of use included:</p>
<div class="fragment"><div class="line">constexpr <span class="keyword">auto</span> identifier = HS(<span class="stringliteral">&quot;my/resource/identifier&quot;</span>);</div>
</div><!-- fragment --><p>Thanks to <a href="https://github.com/huwpascoe">huwpascoe</a> for the courtesy.</p>
<h2><a class="anchor" id="autotoc_md57"></a>
Warning C4003: the min, the max and the macro</h2>
<p>On Windows, a header file defines two macros <code>min</code> and <code>max</code> which may result in conflicts with their counterparts in the standard library and therefore in errors during compilation.</p>
<p>It's a pretty big problem but fortunately it's not a problem of <code>EnTT</code> and there is a fairly simple solution to it.<br  />
 It consists in defining the <code>NOMINMAX</code> macro before to include any other header so as to get rid of the extra definitions:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define NOMINMAX</span></div>
</div><!-- fragment --><p>Please refer to <a href="https://github.com/skypjack/entt/issues/96">this</a> issue for more details.</p>
<h2><a class="anchor" id="autotoc_md58"></a>
The standard and the non-copyable types</h2>
<p><code>EnTT</code> uses internally the trait <code>std::is_copy_constructible_v</code> to check if a component is actually copyable. This trait doesn't check if an object can actually be copied but only verifies if there is a copy constructor available.<br  />
 This can lead to surprising results due to some idiosyncrasies of the standard mainly related to the need to guarantee backward compatibility.</p>
<p>For example, <code>std::vector</code> defines a copy constructor no matter if its value type is copyable or not. As a result, <code>std::is_copy_constructible_v</code> is true for the following specialization:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>type {</div>
<div class="line">    std::vector&lt;std::unique_ptr&lt;action&gt;&gt; vec;</div>
<div class="line">};</div>
</div><!-- fragment --><p>When trying to assign an instance of this type to an entity in the ECS part, this may trigger a compilation error because we cannot really make a copy of it.<br  />
 As a workaround, users can mark the type explicitly as non-copyable:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>type {</div>
<div class="line">    type(<span class="keyword">const</span> type &amp;) = <span class="keyword">delete</span>;</div>
<div class="line">    type &amp; operator=(<span class="keyword">const</span> type &amp;) = <span class="keyword">delete</span>;</div>
<div class="line"> </div>
<div class="line">    std::vector&lt;std::unique_ptr&lt;action&gt;&gt; vec;</div>
<div class="line">};</div>
</div><!-- fragment --><p>Unfortunately, this will also disable aggregate initialization. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<div class="ttc" id="anamespaceentt_html_a588326af8f6f902a6c0b57d3f9fc6c17"><div class="ttname"><a href="namespaceentt.html#a588326af8f6f902a6c0b57d3f9fc6c17">entt::null</a></div><div class="ttdeci">constexpr auto null</div><div class="ttdoc">Compile-time constant for null entities.</div><div class="ttdef"><b>Definition:</b> <a href="entity_8hpp_source.html#l00168">entity.hpp:168</a></div></div>
<!-- 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.16
</small></address>
</body>
</html>