From 51eafaeb4f2de18fd6a290dffed65891ad206b76 Mon Sep 17 00:00:00 2001 From: Michele Caini Date: Wed, 1 Jul 2020 18:41:00 +0200 Subject: [PATCH] doc: mention custom types for entity identifiers --- TODO | 7 ------- docs/md/entity.md | 11 +++++++---- docs/md/faq.md | 22 +++++++++------------- 3 files changed, 16 insertions(+), 24 deletions(-) diff --git a/TODO b/TODO index e253ce559..dc011a6d9 100644 --- a/TODO +++ b/TODO @@ -3,13 +3,10 @@ * debugging tools (#60): the issue online already contains interesting tips on this, look at it * work stealing job system (see #100) + mt scheduler based on const awareness for types * meta: sort of meta view based on meta stuff to iterate entities, void * and meta info objects (remove runtime views, welcome reflection) -* add opaque input iterators to views and groups that return tuples (proxy), multi-pass guaranteed * allow to replace std:: with custom implementations * custom (decoupled) pools ==> N-buffering, shared components, multi-model, hibitsets, and so on * add examples (and credits) from @alanjfs :) * static reflection, hint: template<> meta_type_t: meta_descriptor (see #342) -* can we write a bool conv func for entt::entity that silently compares it to null? -* is it possible to make 0 the entity null? * update documentation for meta, it contains less than half of the actual feature Next: @@ -23,7 +20,3 @@ Next: * WIP: snapshot rework - snapshot: support for range-based archives - update documentation to describe alternatives - -* WIP: - - remove internal::find_if - - add cast_or_convert to meta_any, clean up codebase diff --git a/docs/md/entity.md b/docs/md/entity.md index f2389111e..e8836cb10 100644 --- a/docs/md/entity.md +++ b/docs/md/entity.md @@ -162,13 +162,16 @@ A registry can store and manage entities, as well as create views and groups to iterate the underlying data structures.
The class template `basic_registry` lets users decide what's the preferred type to represent an entity. Because `std::uint32_t` is large enough for almost all -the cases, there exists also the type `entt::entity` for it and the alias -`entt::registry` for `entt::basic_registry`. +the cases, there exists also the enum class `entt::entity` that _wraps_ it and +the alias `entt::registry` for `entt::basic_registry`. Entities are represented by _entity identifiers_. An entity identifier carries information about the entity itself and its version.
-User defined identifiers can be introduced by means of the `ENTT_OPAQUE_TYPE` -macro if needed. +User defined identifiers can be introduced by means of enum classes and custom +types for which a specialization of `entt_traits` exists. For this purpose, +`entt_traits` is also defined as a _sfinae-friendly_ class template. In theory, +integral types can also be used as entity identifiers, even though this may +break in future and isn't recommended in general. A registry is used both to construct and to destroy entities: diff --git a/docs/md/faq.md b/docs/md/faq.md index 35926ae65..f5d8941d0 100644 --- a/docs/md/faq.md +++ b/docs/md/faq.md @@ -100,25 +100,21 @@ performance from this component. Custom entity identifiers are definitely a good idea in two cases at least: -* If `std::uint32_t` isn't large enough as an underlying type. +* If `std::uint32_t` is too large or isn't large enough for your purposes, since + this is the underlying type of `entt::entity`. * If you want to avoid conflicts when using multiple registries. -These identifiers are nothing more than enum classes with some salt.
-To simplify the creation of new identifiers, `EnTT` provides the macro -`ENTT_OPAQUE_TYPE` that accepts two arguments: - -* The name you want to give to the new identifier (watch out for namespaces). -* The underlying type to use (either `std::uint16_t`, `std::uint32_t` - or `std::uint64_t`). - -In fact, this is the definition of `entt::entity`: +Identifiers can be defined through enum classes and custom types for which a +specialization of `entt_traits` exists. For this purpose, `entt_traits` is also +defined as a _sfinae-friendly_ class template.
+In fact, this is a definition equivalent to that of `entt::entity`: ```cpp -ENTT_OPAQUE_TYPE(entity, std::uint32_t) +enum class entity: std::uint32_t {}; ``` -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. +In theory, integral types can also be used as entity identifiers, even though +this may break in future and isn't recommended in general. ## Warning C4307: integral constant overflow