MatParamOverride is a mechanism by which
+ * {@link MatParam material parameters} can be overridden on the scene graph.
+ *
+ * A scene branch which has a MatParamOverride applied to it will
+ * cause all material parameters with the same name and type to have their value
+ * replaced with the value set on the MatParamOverride. If those
+ * parameters are mapped to a define, then the define will be overridden as well
+ * using the same rules as the ones used for regular material parameters.
+ *
+ * MatParamOverrides are applied to a {@link Spatial} via the
+ * {@link Spatial#addMatParamOverride(com.jme3.material.MatParamOverride)}
+ * method. They are propagated to child Spatials via
+ * {@link Spatial#updateGeometricState()} similar to how lights are propagated.
+ *
+ * Example:
+ *
+ * {@code
+ *
+ * Geometry box = new Geometry("Box", new Box(1,1,1));
+ * Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
+ * mat.setColor("Color", ColorRGBA.Blue);
+ * box.setMaterial(mat);
+ * rootNode.attachChild(box);
+ *
+ * // ... later ...
+ * MatParamOverride override = new MatParamOverride(Type.Vector4, "Color", ColorRGBA.Red);
+ * rootNode.addMatParamOverride(override);
+ *
+ * // After adding the override to the root node, the box becomes red.
+ * }
+ *
+ *
+ * @author Kirill Vainer
+ * @see Spatial#addMatParamOverride(com.jme3.material.MatParamOverride)
+ * @see Spatial#getWorldMatParamOverrides()
+ */
public final class MatParamOverride extends MatParam {
private boolean enabled = true;
+ /**
+ * Serialization only. Do not use.
+ */
public MatParamOverride() {
super();
}
+ /**
+ * Create a new MatParamOverride.
+ *
+ * Overrides are created enabled by default.
+ *
+ * @param type The type of parameter.
+ * @param name The name of the parameter.
+ * @param value The value to set the material parameter to.
+ */
public MatParamOverride(VarType type, String name, Object value) {
super(type, name, value);
}
@@ -56,10 +111,26 @@ public final class MatParamOverride extends MatParam {
hash = 59 * hash + (enabled ? 1 : 0);
return hash;
}
+
+ /**
+ * Determine if the MatParamOverride is enabled or disabled.
+ *
+ * @return true if enabled, false if disabled.
+ * @see #setEnabled(boolean)
+ */
public boolean isEnabled() {
return enabled;
}
+ /**
+ * Enable or disable this MatParamOverride.
+ *
+ * When disabled, the override will continue to propagate through the scene
+ * graph like before, but it will have no effect on materials. Overrides are
+ * enabled by default.
+ *
+ * @param enabled Whether to enable or disable this override.
+ */
public void setEnabled(boolean enabled) {
this.enabled = enabled;
}
diff --git a/jme3-core/src/main/java/com/jme3/scene/Spatial.java b/jme3-core/src/main/java/com/jme3/scene/Spatial.java
index ce637b5fc..ce66275b4 100644
--- a/jme3-core/src/main/java/com/jme3/scene/Spatial.java
+++ b/jme3-core/src/main/java/com/jme3/scene/Spatial.java
@@ -607,12 +607,23 @@ public abstract class Spatial implements Savable, Cloneable, Collidable, Cloneab
setMatParamOverrideRefresh();
}
+ /**
+ * Remove a local material parameter override if it exists.
+ *
+ * @param override The override to remove.
+ * @see MatParamOverride
+ */
public void removeMatParamOverride(MatParamOverride override) {
if (localOverrides.remove(override)) {
setMatParamOverrideRefresh();
}
}
+ /**
+ * Remove all local material parameter overrides.
+ *
+ * @see #addMatParamOverride(com.jme3.material.MatParamOverride)
+ */
public void clearMatParamOverrides() {
if (!localOverrides.isEmpty()) {
setMatParamOverrideRefresh();
diff --git a/jme3-core/src/test/java/com/jme3/material/MaterialMatParamOverrideTest.java b/jme3-core/src/test/java/com/jme3/material/MaterialMatParamOverrideTest.java
index 2cc71b3cc..78671ca1c 100644
--- a/jme3-core/src/test/java/com/jme3/material/MaterialMatParamOverrideTest.java
+++ b/jme3-core/src/test/java/com/jme3/material/MaterialMatParamOverrideTest.java
@@ -55,6 +55,11 @@ import com.jme3.texture.Texture2D;
import java.util.HashMap;
import java.util.Map;
+/**
+ * Validates how {@link MatParamOverride MPOs} work on the material level.
+ *
+ * @author Kirill Vainer
+ */
public class MaterialMatParamOverrideTest {
private static final HashSet