Start adding documentation on renderer

docs/src/SUMMARY.md

@@ -38,3 +38,4 @@
 - [Overview](runtime_internals/overview.md)
 - [Contributing](runtime_internals/contributing.md)
 - [ECS](runtime_internals/ecs.md)
+- [Renderer](runtime_internals/renderer.md)

docs/src/runtime_internals/ecs.md

@@ -1,6 +1,22 @@
 # ECS
 
-## What is the `components!` macro in host code?
+The ECS is archetypal, where each component configuration. I.e. `translation, name, scale` and `translation, name, hitpoints` would be two archetypes, and for each of them
+each component is just a `Vec<T>` for the component type.
+
+## Change detection
+
+At a conceptual level, we keep an circular buffer of all changes for each component/archetype. That means that doing a change query is extremely fast;
+it will only need to iterate over the changes. However, a component can change twice or more in a frame, in which case it should still just output
+one change event. To handle that, we also keep track of content generation of each component for each entity.
+
+## GpuECS
+
+The Ambient ECS also supports storing data on the GPU, through the gpu_ecs crate. This gives you a way to define components that live on the gpu,
+and ways to synchronize data to those components.
+
+Cpu-to-gpu syncs are chunked, so in a lot of cases it takes the same time to update one element as it does CHUNK_SIZE elements (currently 256).
+
+## `components!` macro
 
 At the root of the repository, there is an `ambient.toml` that defines all of the guest-visible components for Ambient. This is what runtime developers will typically add to when they want to add new components to Ambient.
 

docs/src/runtime_internals/overview.md

@@ -1,7 +1,9 @@
 # Runtime internals
 
 This part of the documentation covers how the runtime works internally,
-and how you can make changes to it.
+and how you can make changes to it. This is mostly if you want to contribute
+to the Ambient repository itself; for most end users the user and reference
+sections of the book should be enough.
 
 ## Getting started
 

docs/src/runtime_internals/renderer.md

@@ -0,0 +1,13 @@
+# Renderer
+
+Rendering a frame roughly looks like this:
+
+1. The [gpu ecs](./ecs.md) synchronizes any changed values to the gpu. Note; this only happens when values have changed, and is batched for performance.
+2. The renderer run culling. Only some entities are cullable; for instance, if you spawn a character which has a bunch of sub-entities (like a sword and a shield),
+   only the root entity will be culled. Culling happens entirely on the GPU.
+3. We run the collect phase; this is per-primitive. Note that each entity may have multiple primitives. This also runs on the gpu, and the output is a compacted list
+   of draw calls.
+4. On native, we run a `multi_draw_indirect_count` call for each shader/material configuration. Note that on native, the CPU does very little work each frame; most work
+   happens on the gpu and the cpu doesn't need to wait for it. On web and mac we currently don't have access to multi_draw_indirect_count, so we're currently dispatching
+   draw calls one by one, but we're working on improvements to this.
+