finalized user value sources and targets

FrameGraphComponents

@@ -0,0 +1,36 @@
+What is a render resource?
+
+A render resource is a wrapper for a render object. It also tracks references and lifetime, and knows its producer and resource definition. When a resource is not
+
+What is a resource ticket?
+
+A resource ticket points to a resource. It is used to tell the resource manager which resource various operations should be performed on.
+
+What does declaring a resource do?
+
+Declaring a resource makes the resource manager create a new virtual resource that does not yet hold an actual value. Passes should declare all resources they plan on creating during execution in the preperation step.
+
+What does referencing a resource do?
+
+Referencing is similar to declaring, except it acts on an existing resource. It tells the resource manager that that resource will be used in the future. This is used by passes referencing resources produced by other passes.
+
+What does acquiring a resource do?
+
+Acquiring a resource either returns the actual object held by the resource if the resource is not virtual, otherwise creates and returns a new object or returns an existing unused object.
+
+What does releasing a resource do?
+
+Releasing indicates that the resource is not used by a pass anymore. Resources track how many passes are using them using declarations and references. Once a resource finds that all passes that declared or referenced it have also released it, the resource will be deleted, and the object held by the resource will be posted for reallocation.
+
+What does setting a resource as constant do?
+
+This command does not actually change the resource, but it does set a flag on the object held by the resource (if the resource is not virtual) indicating that the object should not be reallocated for the remainder of rendering. The Attribute pass uses this to ensure that user-provided or user-consumed objects do not change unexpectedly.
+
+What does setting a resource as undefined do?
+
+Setting a resource as undefined makes it real (not virtual) but unable to hold an actual object. This is used by the Attribute pass when no (non-null) value is provided for output. Exceptions can occur if a pass attempts to acquire (without using an optional acquire) an undefined resource.
+
+What is a resource definition?
+
+A resource definition determines how new objects should be built or how existing objects should be adapted for the resource the definition is assigned to. It also defines how the resource and object should be handled in various situations.
+

FrameGraphTutorial.md

@@ -0,0 +1,36 @@
+
+/**
+ * For this tutorial, we will create a simple FrameGraph that renders
+ * the opaque, sky, and transparent buckets in that order, followed
+ * by a pass that renders the result to the screen.
+ */
+
+// Begin by declaring a new FrameGraph.
+FrameGraph fg = new FrameGraph();
+
+// Add the passes we will use, in the correct order.
+// Make sure to specify the correct bucket on each pass.
+BucketPass opaque = fg.add(new BucketPass(Bucket.Opaque));
+BucketPass sky = fg.add(new BucketPass(Bucket.Sky));
+BucketPass transparent = fg.add(new BucketPass(Bucket.Transparent));
+OutputPass output = fg.add(new OutputPass());
+
+// Now, each pass needs to pass its resulting color and depth to the next pass.
+// We will do that by connecting certain tickets belonging to the passes.
+sky.makeInput(opaque, "Color", "Color");
+sky.makeInput(opaque, "Depth", "Depth");
+transparent.makeInput(sky, "Color", "Color");
+transparent.makeInput(sky, "Depth", "Depth");
+output.makeInput(transparent, "Color", "Color");
+output.makeInput(transparent, "Depth", "Depth");
+
+// The graph now, visually, looks like this:
+//
+//  Opaque:   Sky:      Transparent:    Output:
+//  color  -> color  -> color  -------> color
+//  depth  -> depth  -> depth  -------> depth
+
+// Finally, assign the FrameGraph to the ViewPort.
+viewPort.setFrameGraph(fg);
+
+

jme3-core/src/main/java/com/jme3/export/InputCapsule.java

@@ -113,7 +113,15 @@ public interface InputCapsule {
     public Savable readSavable(String name, Savable defVal) throws IOException;
     public Savable[] readSavableArray(String name, Savable[] defVal) throws IOException;
     public Savable[][] readSavableArray2D(String name, Savable[][] defVal) throws IOException;
-
+    public default <T extends Savable> T readSavable(String name, Class<T> type, T defVal) throws IOException {
+        Savable s = readSavable(name, defVal);
+        if (s != defVal && type.isAssignableFrom(s.getClass())) {
+            return (T)s;
+        } else {
+            return defVal;
+        }
+    }
+
 
     // ArrayLists
 

jme3-core/src/main/java/com/jme3/renderer/RenderManager.java

@@ -48,7 +48,6 @@
 import com.jme3.profile.VpStep;
 import com.jme3.renderer.framegraph.FrameGraph;
 import com.jme3.renderer.framegraph.RenderObjectMap;
-import com.jme3.renderer.framegraph.RenderingBlackboard;
 import com.jme3.renderer.queue.GeometryList;
 import com.jme3.renderer.queue.RenderQueue;
 import com.jme3.renderer.queue.RenderQueue.Bucket;
@@ -72,10 +71,10 @@
 import java.util.function.Predicate;
 
 /**
- * A high-level rendering interface that is
- * above the Renderer implementation. RenderManager takes care
- * of rendering the scene graphs attached to each viewport and
- * handling SceneProcessors.
+ * A high-level rendering interface that is above the Renderer implementation.
+ * <p>
+ * RenderManager takes care of rendering the scene graphs attached to each
+ * viewport and handling SceneProcessors.
  *
  * @see SceneProcessor
  * @see ViewPort
@@ -89,7 +88,6 @@ public class RenderManager {
     private final ArrayList<ViewPort> viewPorts = new ArrayList<>();
     private final ArrayList<ViewPort> postViewPorts = new ArrayList<>();
     private final RenderObjectMap renderObjects = new RenderObjectMap();
-    private final RenderingBlackboard blackboard = new RenderingBlackboard();
     private FrameGraph frameGraph;
     private Camera prevCam = null;
     private Material forcedMaterial = null;
@@ -135,10 +133,6 @@ public RenderObjectMap getRenderObjectsMap() {
         return renderObjects;
     }
 
-    public RenderingBlackboard getBlackboard() {
-        return blackboard;
-    }
-
     /**
      * Sets the GeometryRenderHandler used to render geometry.
      * <p>

jme3-core/src/main/java/com/jme3/renderer/framegraph/DepthRange.java

@@ -4,11 +4,18 @@
  */
 package com.jme3.renderer.framegraph;
 
+import com.jme3.export.InputCapsule;
+import com.jme3.export.JmeExporter;
+import com.jme3.export.JmeImporter;
+import com.jme3.export.OutputCapsule;
+import com.jme3.export.Savable;
+import java.io.IOException;
+
 /**
  *
  * @author codex
  */
-public class DepthRange {
+public class DepthRange implements Savable {
 
     public static final DepthRange IDENTITY = new DepthRange();
     public static final DepthRange FRONT = new DepthRange(0, 0);
@@ -40,6 +47,18 @@ public final DepthRange set(DepthRange range) {
         return this;
     }
 
+    public final DepthRange setStart(float start) {
+        validateRange(start, end);
+        this.start = start;
+        return this;
+    }
+
+    public final DepthRange setEnd(float end) {
+        validateRange(start, end);
+        this.end = end;
+        return this;
+    }
+
     public float getStart() {
         return start;
     }
@@ -81,10 +100,21 @@ public int hashCode() {
         hash = 79 * hash + Float.floatToIntBits(this.end);
         return hash;
     }
-
     @Override
     public String toString() {
         return "DepthRange["+start+" -> "+end+"]";
     }
+    @Override
+    public void write(JmeExporter ex) throws IOException {
+        OutputCapsule out = ex.getCapsule(this);
+        out.write(start, "start", 0);
+        out.write(end, "end", 1);
+    }
+    @Override
+    public void read(JmeImporter im) throws IOException {
+        InputCapsule in = im.getCapsule(this);
+        start = in.readFloat("start", 0);
+        end = in.readFloat("end", 1);
+    }
 
 }

jme3-core/src/main/java/com/jme3/renderer/framegraph/FGRenderContext.java

@@ -149,9 +149,6 @@ public RenderQueue getRenderQueue() {
     public FullScreenQuad getScreen() {
         return screen;
     }
-    public RenderingBlackboard getBlackboard() {
-        return renderManager.getBlackboard();
-    }
     public float getTpf() {
         return tpf;
     }

jme3-core/src/main/java/com/jme3/renderer/framegraph/FrameGraph.java

@@ -6,7 +6,15 @@
 
 import com.jme3.renderer.framegraph.passes.RenderPass;
 import com.jme3.asset.AssetManager;
+import com.jme3.export.InputCapsule;
+import com.jme3.export.JmeExporter;
+import com.jme3.export.JmeImporter;
+import com.jme3.export.OutputCapsule;
+import com.jme3.export.Savable;
 import com.jme3.renderer.RenderManager;
+import java.io.IOException;
+import java.util.Arrays;
+import java.util.HashMap;
 import java.util.Iterator;
 import java.util.LinkedList;
 
@@ -15,7 +23,7 @@
  * 
  * @author codex
  */
-public class FrameGraph {
+public class FrameGraph implements Savable {
 
     private static int nextId = 0;
 
@@ -49,7 +57,7 @@ public void execute() {
         // execute passes
         context.pushRenderSettings();
         for (RenderPass p : passes) {
-            if (p.isReferenced()) {
+            if (p.isUsed()) {
                 p.executeRender(context);
                 context.popRenderSettings();
             }
@@ -174,5 +182,17 @@ public RenderManager getRenderManager() {
     public boolean isDebug() {
         return debug;
     }
+
+    @Override
+    public void write(JmeExporter ex) throws IOException {
+        OutputCapsule out = ex.getCapsule(this);
+        out.write(passes.toArray(RenderPass[]::new), "passes", new RenderPass[0]);
+    }
+    @Override
+    public void read(JmeImporter im) throws IOException {
+        InputCapsule in = im.getCapsule(this);
+        RenderPass[] array = (RenderPass[])in.readSavableArray("passes", new RenderPass[0]);
+        passes.addAll(Arrays.asList(array));
+    }
 
 }

jme3-core/src/main/java/com/jme3/renderer/framegraph/GraphTarget.java

@@ -0,0 +1,19 @@
+/*
+ * Click nbfs://nbhost/SystemFileSystem/Templates/Licenses/license-default.txt to change this license
+ * Click nbfs://nbhost/SystemFileSystem/Templates/Classes/Interface.java to edit this template
+ */
+package com.jme3.renderer.framegraph;
+
+import com.jme3.renderer.ViewPort;
+
+/**
+ * Receives values from a FrameGraph.
+ * 
+ * @author codex
+ * @param <T>
+ */
+public interface GraphTarget <T> {
+
+    public void setGraphValue(ViewPort viewPort, T value);
+
+}

jme3-core/src/main/java/com/jme3/renderer/framegraph/RenderObject.java

@@ -19,9 +19,9 @@ public class RenderObject <T> {
     private static final Consumer<Object> DEFAULT = object -> {};
     private static final Consumer<NativeObject> NATIVE = object -> object.dispose();
 
-    private static int nextId = 0;
+    private static long nextId = 0;
 
-    private final int id;
+    private final long id;
     private final T object;
     private final BitSet reservations = new BitSet();
     private int timeoutDuration;
@@ -48,14 +48,7 @@ else if (object instanceof NativeObject) {
             this.disposer = DEFAULT;
         }
     }
-
-    public boolean acquire(TimeFrame time, boolean reserved) {
-        if (acquired || (!reserved && isReserved(time))) {
-            return false;
-        }
-        acquire();
-        return true;
-    }
+
     public void acquire() {
         timeout = timeoutDuration;
         acquired = true;
@@ -84,7 +77,7 @@ public void setConstant(boolean constant) {
         this.constant = constant;
     }
 
-    public int getId() {
+    public long getId() {
         return id;
     }
     public T getObject() {
@@ -93,7 +86,10 @@ public T getObject() {
     public boolean isAcquired() {
         return acquired;
     }
-    public boolean isReserved(TimeFrame frame) {
+    public boolean isReservedAt(int index) {
+        return reservations.get(index);
+    }
+    public boolean isReservedWithin(TimeFrame frame) {
         if (frame.getStartIndex() >= reservations.size()) {
             return false;
         }
@@ -109,7 +105,7 @@ public boolean isConstant() {
         return constant;
     }
 
-    public static int getNextId() {
+    public static long getNextId() {
         return nextId;
     }