ソースを参照

doc: more on view_pack

Michele Caini 5 年 前
コミット
9a574aa00c
1 ファイル変更61 行追加0 行削除
  1. 61 0
      docs/md/entity.md

+ 61 - 0
docs/md/entity.md

@@ -35,6 +35,7 @@
     * [One example to rule them all](#one-example-to-rule-them-all)
 * [Views and Groups](#views-and-groups)
   * [Views](#views)
+    * [View pack](#view-pack)
   * [Runtime views](#runtime-views)
   * [Groups](#groups)
     * [Full-owning groups](#full-owning-groups)
@@ -1405,6 +1406,66 @@ for(auto entity: view) {
 **Note**: prefer the `get` member function of a view instead of that of a
 registry during iterations to get the types iterated by the view itself.
 
+### View pack
+
+The view pack allows users to combine multiple views into a single iterable
+object, while also giving them full control over which view should lead the
+iteration.<br/>
+This class returns all and only the entities present in all views. Its intended
+primary use is for custom storage and views, but it can also be very convenient
+in everyday use.
+
+The creation of a view pack tries to mimic C++20 ranges:
+
+```cpp
+auto view = registry.view<position>();
+auto other = registry.view<velocity>();
+
+auto pack = view | other;
+```
+
+The return type is a specialization of the class template `entt::view_pack`.
+This is nothing more than an iterable object that combines two or more views
+into a single instance.<br/>
+The first view used to create a pack will also be the same that will lead the
+iteration.
+
+A view pack offers functionalities similar to those of a view, at least as
+regards the possibilities of iteration. In particular, it only returns entities
+if iterated directly:
+
+```cpp
+for(auto entt: pack) {
+    // ...
+}
+```
+
+On the other hand, both the (optional) entity and the components are returned
+when the `each` member function is used, be it with callback or to get an
+extended iterable object:
+
+```cpp
+// with a callback
+pack.each([](const auto entt, auto &pos, auto &vel) { /* ... */ });
+
+// with an extended iterable object
+for(auto [entt, pos, vel]: pack.each()) {
+    // ...
+}
+```
+
+Furthermore, the constness of the types returned by a view pack is directly
+inherited by the views that compose it:
+
+```
+(registry.view<position>() | registry.view<const velocity>()).each([](auto &pos, const auto &vel) {
+    // ...
+});
+```
+
+Read also the dedicated section to know how a view pack is involved in the
+creation and use of custom storage and pools.
+
 ## Runtime views
 
 Runtime views iterate entities that have at least all the given components in