|
|
@@ -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
|