Просмотр исходного кода

doc: more about entity storage

Michele Caini 2 лет назад
Родитель
Сommit
a1e76fc638
1 измененных файлов с 49 добавлено и 0 удалено
  1. 49 0
      docs/md/entity.md

+ 49 - 0
docs/md/entity.md

@@ -38,6 +38,7 @@
   * [Empty type optimization](#empty-type-optimization)
   * [Empty type optimization](#empty-type-optimization)
   * [Void storage](#void-storage)
   * [Void storage](#void-storage)
   * [Entity storage](#entity-storage)
   * [Entity storage](#entity-storage)
+    * [One of a kind to the registry](#one-of-a-kind-to-the-registry)
   * [Pointer stability](#pointer-stability)
   * [Pointer stability](#pointer-stability)
     * [In-place delete](#in-place-delete)
     * [In-place delete](#in-place-delete)
     * [Hierarchies and the like](#hierarchies-and-the-like)
     * [Hierarchies and the like](#hierarchies-and-the-like)
@@ -1273,6 +1274,54 @@ Moreover, the entity storage offers a couple of additional utilities such as:
 This kind of storage is designed to be used where any other storage is fine and
 This kind of storage is designed to be used where any other storage is fine and
 can therefore be combined with views, groups and so on.
 can therefore be combined with views, groups and so on.
 
 
+### One of a kind to the registry
+
+Within the registry, an entity storage is treated in all respects like any other
+storage.<br/>
+Therefore, it's possible to add mixins to it as well as retrieve it via the
+`storage` function. It can also be used as storage in a view (for exclude-only
+views for example):
+
+```cpp
+auto view = registry.view<entt::entity>(entt::exclude<my_type>);
+```
+
+However, it's also subject to a couple of exceptions, partly out of necessity
+and partly for ease of use.
+
+In particular, it's not possible to create multiple elements of this type.<br/>
+This means that the _name_ used to retrieve this kind of storage is ignored and
+the registry will only ever return the same element to the caller. For example:
+
+```cpp
+auto &other = registry.storage<entt::entity>("custom"_hs);
+```
+
+In this case, the identifier is discarded as is. The call is in all respects
+equivalent to the following:
+
+```cpp
+auto &storage = registry.storage<entt::entity>();
+```
+
+Because entity storage doesn't have a name, it can't be retrieved via the opaque
+`storage` function either.<br/>
+It would make no sense to try anyway, given that the type of the registry and
+therefore its entity type are known regardless.
+
+Finally, when the user asks the registry for an iterable object to visit all the
+storage elements inside it as follows:
+
+```cpp
+for(auto [id, storage]: registry.each()) {
+    // ...
+}
+```
+
+Entity storage is never returned. This simplifies many tasks (such as copying an
+entity) and fits perfectly with the fact that this type of storage doesn't have
+an identifier inside the registry.
+
 ## Pointer stability
 ## Pointer stability
 
 
 The ability to achieve pointer stability for one, several or all components is a
 The ability to achieve pointer stability for one, several or all components is a