preparing to alter Spatial

VulkanDesign.txt

@@ -1,137 +1,5 @@
-Some resources require copies per concurrent frame. There are some unresolved problems with implementing this:
+Spatial: Current problems:
 
-    1. UniformSets need to have a DescriptorSet per concurrent frame, but only if at least one uniform requires resource copies.
-    2. Resources need to know the current frame's index so the correct copy is used.
-    3. Not all resources need to have copies per frame. This should be configurable by this user even after resources have been created (either by changing a state or replacing the resource entirely).
-
-There are a couple different levels at which the copy split can happen:
-
-    1. Inside GpuBuffer and Image implementations (very low-level).
-    2. Each geometry has materials and meshes for each frame.
-
-I like solution 1 because it gives more control over what resources are copied per-frame (neatly solving problem 3). If a mesh contains a buffer that doesn't need copies and another that does, solution 2 would require both buffers have copies. Using the buffer copy feature, users can swap out buffers with any other implementation.
-
-Solution 1 could solve problem 2 by either setting the current frame when the frame begins, or pass as an argument for buffer functions. I lean toward setting at the start of the frame, because it would simplify the API. Each resource could have a method for that, and it is up to the implementors what to do with the current frame. The only problem here is how to ensure all resources get updated correctly.
-
-Solution 1 struggles a bit with problem 1. UniformSet already has a system for choosing one DescriptorSet among several cached sets, so that shouldn't be a huge problem. The main problem is that uniforms need some way to indicate whether they use frame copies or not. Ideally, this shouldn't be a setting on the uniform, but rather on the underlying resource. This could be solved by providing a method for resources which returns their preference.
-
-Here's the rough implementation plan for solution 1: make a low-level interface (maybe RenderResource) which supplies methods for frame interaction (knowing the current frame and indicating whether copies are being used). Uniforms and UniformSets will base their functionality on whether any resource is using frame copies. Other than that, copies are solely up to the specific resource implementations. With this in mind, the current problems are:
-
-    1. How to ensure all resources are properly updated. Not updating a resource may lead to read/write conflicts with the GPU.
-    2. I'm not happy with having an API method whose sole purpose is to communicate a boolean, where most implementations will simply return true or false without any calculation. It feels wrong, maybe because of how wishy-washy this is.
-    3. How will resources know how many frames are available. Sure, they could wait N frames to see where the index goes back to zero, but I don't like this limitation.
-
-Problem 2 could be solved by having only resources that use copies to implement RenderResource (it would have to renamed). This would more rigidly enforce the API, but it doesn't completely solve the original problem of UniformSets knowing which resources use multiple copies. UniformSet could check if the resource implements RenderResource, but I'm not entirely happy with that either (I do think it's better than before, though).
-
-Problem 1 could possibly be solved using a registry. The obvious problem with that is how the resources know about the registry, and I really don't want to make the registry static.
-
--------
-
-I suppose I'm probably missing the real problem here. Requirements:
-
-    1. Some resources have multiple copies.
-    2. The copy that should be interacted with is determined by the active frame.
-    3. When a resource is destroyed, all its copies should also be destroyed.
-
-We already have a system that can support requirement 1 and partially requirement 2. A buffer can delegate to the correct copy, perhaps through a chain of delegates.
-
-    1. Buffers delegate to a downstream copy depending on the current frame. Similar to a LinkedList.
-        PRO: Depends only on the implementation.
-        PRO: Automatically generates copies on demand.
-        CON: Too automatic. No way to indicate that no copies should be generated.
-        CON: Seems a bit too finicky. It'll probably outsmart itself.
-    2. Create a buffer implementation that delegates to one of many internal buffers depending on the current frame.
-        PRO: No need to alter current implementations. Works out of the box.
-        PRO: Simple to understand.
-
-#1 is the way to go here. No downsides that I can see (although that does depend on future decisions).
-The other half of requirement 2 is informing the buffer which copy should be interacted with. There are three options:
-
-    1. Inform the buffer at command time.
-        PRO: Flexible. Another copy besides the one for the active frame can be interacted with if desired.
-        PRO: Clear. It's easy to tell at a glance exactly what copy is being interacted with.
-        CON: Makes the API much messier. A lot of methods will have to take an extra argument.
-        CON: It is difficult to tell whether any given buffer supports concurrency via copies. You're basically dropped in a minefield.
-    2. Inform the buffer when the frame changes.
-        PRO: Doesn't touch the existing public API.
-        CON: Inflexible. Either impossible or difficult to interact with another copy.
-        CON: Unclear. You have to know context to know which copy is being interacted with.
-        CON: Accidental saving. Users may accidentally reference a copy thinking it is the managing buffer.
-        CON: Difficult to ensure all buffers are properly registered for such notifications.
-
-Just by looking at the number of cons, #2 is clearly not the way to go. I'm liking #1 much better now, too. We still have to address the two cons #1 has. Starting with the first con, the methods that will require changing are:
-
-    1. GpuBuffer#map(MemoryStack, int, int int)
-        + all related helper methods (map and copy)
-    2. GpuBuffer#unmap()
-    3. GpuBuffer#getId()
-        * Since GpuBuffer is not a Native<>, getNativeObject is left untouched :)
-    4. Image#createView(VkImageViewCreateInfo)
-        + all related helper methods
-
-Likewise, in order to avoid changing Native#getNativeObject, Image will gain getId() and will no longer implement Native<>. It's silly to expect an Image to be Native<> anyway. That's an implementation thing.
-
-The second con for #1 is more serious, in my opinion. #1 is mostly an implementation solution, meaning an unsafely-mutable buffer (with no copies) could easily be passed into a mutator not designed for that sort of mutation.
-
-    1. Make a "SafelyMutableBuffer" interface extending GpuBuffer. The buffer manager will implement this.
-        PRO: Strictly enforces that unsafe buffers cannot be thrown into any mutator.
-        PLUS! Could even replace the need to change GpuBuffer API.
-            CON: Ends up having duplicate methods that have unclear functionality (what to do with getId() with no frame indicator?).
-                BUT... What about splitting SafelyMutableBuffer from GpuBuffer entirely? When would you want to treat a regular GpuBuffer like a SafelyMutableBuffer? For reading, of course. Nevermind.
-                BUT... This is not really a con. The methods GpuBuffer provides should only be used with special handling. SafelyMutableBuffer extends it to provide seperate safe methods. GpuBuffer's methods could act on, say, the first copy or the last interacted copy.
-            CON: Yeah, this isn't very maintainable... simply too many extra methods.
-            CON: And this whole thing is getting too complicated.
-    2. Add a method to GpuBuffer indicating safety.
-        CON: Weak, completely on the mutators to enforce.
-
----------
-
-After more thought, I decided to move towards a "data pipeline" approach. The pipeline(s) transform the input data into the correct format. Pipelines, as I see them, would address several key issues:
-
-    1. Different versions per frame. Pipelines could descretely present different inputs/outputs depending on the frame.
-    2. Jankiness in the different buffer types in order to have staging buffers. Pipelines will handle transfers from the staging buffer to the GPU-side buffer(s), and it will be much more flexible, too, since pipelines can also handle per-frame versions.
-
-There are a couple issues pipelines raise or don't adequately solve:
-
-    1. How do uniforms determine what resource version is currently being dealt with?
-        - The most straightforward approach would be to store the resources themselves in the frame index rather than the resource index. This seems all right to me, except we would need to use WeakReferences to not interfere with resources getting GC'd.
-            - Done. That turned out pretty well, actually.
-    2. Name conflict: Pipeline is already a thing. DataPipeline would just seem like a vulkan pipeline that processes data.
-        - DataGraph. Since I do envision it functioning similar to a graph.
-        - Resource. Rather bland, but it does encompass the general idea.
-        - Data. Ditto.
-    3. How should internals be properly synchronized?
-        - Pipelines requiring that commands be submitted will be given a command buffer on init. Pipelines only need to submit commands to the command buffer.
-
-Well, that turned out much better than I anticipated. The only problem now is that I accidentally locked the input data behind an anonymous hierarchy of DataPipes.
-
-    1. Make uniforms able to store the necessary terminal data pipes.
-        - I don't like this method. The user would have to manually provide the terminal pipes, and they may not actually affect the uniform anyway.
-    2. Have a second structure (I'll call it Parameters, for now) mirroring Material which is specifically for storing the data pipes. The data pipes are configured for transfering data from slots in Parameters to corresponding uniforms.
-        - I like this method better. It's more structured than the other solution, but also allows uniforms to be informed by multiple parameter slots (or even none), if desired.
-        - I wonder if this could be transformed into something much bigger...
-
-There is actually one more problem I overlooked with DataPipes. CommandBuffers need to be passed at pipe execution time, because each frame has its own set of CommandBuffers (for the most part). I could simply pass a CommandBuffer as an argument, except I'm not sure if all the pipes in the same pipeline are gauranteed to be happy submitting under to a single CommandBuffer. It'd be perfectly fine for them to do so (and they really shouldn't care), the question is more about performance.
-
-    1. Pass one CommandBuffer through the pipeline. All pipes submit commands to only that CommandBuffer.
-        - Could possibly be missing out on performance benefits, but I really can't think of a specific case off the top of my head.
-    2. Pass a CommandBuffer manager which will return the optimal CommandBuffer for the situation.
-        - Again, I'm fuzzy on exactly what situations would warrant multiple CommandBuffers, so I'm not willing to implement this at the moment.
-        - I could do a simple version of this just out of principle. Perhaps in the future we will know enough to implement such a system.
-
-For now, I'll go with #1.
-
------
-
-Well, I've run into a new problem. I'm not sure what it is exactly, but the DataPipe system isn't working as smoothly as I'd hoped. It doesn't handle different forms of buffers very well (static, dynamic, adaptive). For example, in order for a static buffer to work, the staging buffer should be deleted after the transfer is complete. DataPipes have no clean way to handle that (and really, niether does any other available system). At the same time, DataPipes need a "needs update" check so that certain operations can be skipped if the incoming buffer hasn't changed.
-
-My original idea was to have a Buffer implementation that deferred to one of N internal buffers depending on the frame could still possibly work.
-
------
-
-Yesterday, the occured to me that there are two main issues I'm trying to combat:
-
-    1. Updating items (buffers especially) at the correct time.
-    2. Ensuring the proper items are used at any given time (i.e. per-frame versions).
-
-Now, a new solution to the first problem would be an update registry system. On creation, you register the item with a particular update batch, which will then update the item at the correct time. Furthermore, this will centralize CommandBuffer usage and make it easier to fine-tune synchronization (which would have otherwise been a fairly major problem).
+    * The transform refresh only works when transform setter methods are used. I propose that the world transform should be recalculated on every frame. It will make the system a lot simpler, I think.
+    * An explicit world light list is unnecessary. All that needs to be done to capture all lights affecting a spatial is to iterate up the hierarchy and collect lights from the local light lists. Iterating up the hierarchy is extremely cheap and I want to take more advantage of it.
+    * There should be at most one method in Spatial for iterating over an entire tree. It should use depth-first traversal. Breadth-first traversal isn't used within the engine and is obviously more expensive. collideWith() is also counted as a traversal method. If possible, I'd like to take more advantage of SceneGraphIterator, since I think it is the most powerful traversal available.

jme3-examples/src/main/java/jme3test/vulkan/VulkanHelperTest.java

@@ -178,7 +178,7 @@ public void simpleInitApp() {
         descriptorLayout = new DescriptorSetLayout(device,
                 new SetLayoutBinding(Descriptor.UniformBuffer, 0, 1, ShaderStage.Vertex),
                 new SetLayoutBinding(Descriptor.CombinedImageSampler, 1, 1, ShaderStage.Fragment));
-        descriptorPool = new DescriptorPool(device, 3,
+        descriptorPool = new DescriptorPool(device, 10,
                 new PoolSize(Descriptor.UniformBuffer, 3),
                 new PoolSize(Descriptor.StorageBuffer, 4),
                 new PoolSize(Descriptor.CombinedImageSampler, 2));

jme3-lwjgl3/src/main/java/com/jme3/vulkan/scene/Geometry.java

@@ -0,0 +1,5 @@
+package com.jme3.vulkan.scene;
+
+public class Geometry {
+
+}

jme3-lwjgl3/src/main/java/com/jme3/vulkan/scene/Node.java

@@ -0,0 +1,32 @@
+package com.jme3.vulkan.scene;
+
+import com.jme3.util.SafeArrayList;
+
+public class Node extends Spatial {
+
+    private SafeArrayList<Spatial> children = new SafeArrayList<>(Spatial.class);
+
+    public void attachChild(Spatial child) {
+        children.add(child);
+        child.setParent(this);
+    }
+
+    public boolean detachChild(Spatial child) {
+        if (children.remove(child)) {
+            child.setParent(null);
+            return true;
+        }
+        return false;
+    }
+
+    @Override
+    protected void findNextIteration(GraphIterator iterator) {
+        int i = iterator.advanceIndex();
+        if (i >= children.size()) {
+            iterator.moveUp();
+        } else {
+            iterator.moveDown(children.get(i));
+        }
+    }
+
+}

jme3-lwjgl3/src/main/java/com/jme3/vulkan/scene/Spatial.java

@@ -0,0 +1,104 @@
+package com.jme3.vulkan.scene;
+
+import java.util.*;
+
+public abstract class Spatial implements Iterable<Spatial> {
+
+    private Node parent;
+
+    public void removeFromParent() {
+
+    }
+
+    public Node getParent() {
+        return parent;
+    }
+
+    protected void setParent(Node parent) {
+        this.parent = parent;
+    }
+
+    protected abstract void findNextIteration(GraphIterator iterator);
+
+    @Override
+    public Iterator<Spatial> iterator() {
+        return new GraphIterator(this);
+    }
+
+    public static class GraphIterator implements Iterator<Spatial> {
+
+        private final Stack<Integer> childIndices = new Stack<>();
+        private Spatial current;
+        private int currentIndex = 0;
+        private int iteration = -1;
+
+        public GraphIterator(Spatial start) {
+            current = Objects.requireNonNull(start);
+        }
+
+        @Override
+        public boolean hasNext() {
+            return current != null;
+        }
+
+        @Override
+        public Spatial next() {
+            if (++iteration > 0) {
+                current.findNextIteration(this);
+            }
+            return current;
+        }
+
+        @Override
+        public void remove() {
+            if (current.getParent() != null) {
+                current.removeFromParent();
+                moveUp();
+                currentIndex--;
+            }
+        }
+
+        protected void moveUp() {
+            if (!childIndices.isEmpty()) {
+                current = current.getParent();
+                currentIndex = childIndices.pop();
+                if (current != null) {
+                    current.findNextIteration(this);
+                }
+            } else {
+                current = null;
+            }
+        }
+
+        protected void moveDown(Spatial node) {
+            if (node.getParent() != current) {
+                throw new IllegalArgumentException("Next node must be a child of the current node.");
+            }
+            current = node;
+            childIndices.push(currentIndex);
+            currentIndex = 0;
+        }
+
+        protected int advanceIndex() {
+            return currentIndex++;
+        }
+
+        protected int getCurrentIndex() {
+            return currentIndex;
+        }
+
+        public void skipChildren() {
+            moveUp();
+        }
+
+        public int getDepth() {
+            return childIndices.size();
+        }
+
+        public int getIteration() {
+            return iteration;
+        }
+
+    }
+
+}