Make bounds update toggleable (off by default) and add visual example

Copilot · riccardobl · Copilot · commit f4661dcffe55 · 2026-03-28T10:22:22.000Z
Agent-Logs-Url: https://github.com/jMonkeyEngine/jmonkeyengine/sessions/1528c7f1-8585-400f-9b82-851054cf0408 Co-authored-by: riccardobl <4943530+riccardobl@users.noreply.github.com>
diff --git a/jme3-core/src/main/java/com/jme3/anim/SkinningControl.java b/jme3-core/src/main/java/com/jme3/anim/SkinningControl.java
@@ -133,6 +133,13 @@ public class SkinningControl extends AbstractControl implements JmeCloneable {
      */
     private transient Matrix4f[] boneOffsetMatrices;
 
+    /**
+     * When true, the bounding volumes of animated geometries are updated each
+     * frame to match the current pose, ensuring correct frustum culling.
+     * Disabled by default because it adds CPU cost every frame.
+     */
+    private boolean updateBounds = false;
+
     private MatParamOverride numberOfJointsParam = new MatParamOverride(VarType.Int, "NumberOfBones", null);
     private MatParamOverride jointMatricesParam = new MatParamOverride(VarType.Matrix4Array, "BoneMatrices", null);
 
@@ -248,6 +255,32 @@ public boolean isHardwareSkinningUsed() {
         return hwSkinningEnabled;
     }
 
+    /**
+     * Enables or disables per-frame bounding-volume updates for animated
+     * geometries. When enabled, the bounding volume of each deformed geometry
+     * is recomputed every render frame to match the current animation pose,
+     * ensuring correct frustum culling at the cost of additional CPU work.
+     * Disabled by default.
+     *
+     * @param updateBounds true to update bounds each frame, false to keep
+     *                     static bind-pose bounds (default=false)
+     * @see #isUpdateBounds()
+     */
+    public void setUpdateBounds(boolean updateBounds) {
+        this.updateBounds = updateBounds;
+    }
+
+    /**
+     * Returns whether per-frame bounding-volume updates are enabled for
+     * animated geometries.
+     *
+     * @return true if bounds are updated each frame, false otherwise
+     * @see #setUpdateBounds(boolean)
+     */
+    public boolean isUpdateBounds() {
+        return updateBounds;
+    }
+
     /**
      * Recursively finds and adds animated geometries to the targets list.
      *
@@ -299,8 +332,10 @@ private void controlRenderSoftware() {
             // NOTE: This assumes code higher up has already ensured this mesh is animated.
             // Otherwise, a crash will happen in skin update.
             applySoftwareSkinning(mesh, boneOffsetMatrices);
-            // Update the mesh bounding volume to reflect the animated vertex positions.
-            geometry.updateModelBound();
+            if (updateBounds) {
+                // Update the mesh bounding volume to reflect the animated vertex positions.
+                geometry.updateModelBound();
+            }
         }
     }
 
@@ -311,13 +346,15 @@ private void controlRenderHardware() {
         boneOffsetMatrices = armature.computeSkinningMatrices();
         jointMatricesParam.setValue(boneOffsetMatrices);
 
-        // Hardware skinning transforms vertices on the GPU, so the CPU-side vertex
-        // buffer is not updated. Compute the animated bounding volume from the bind
-        // pose positions and the current skinning matrices so culling is correct.
-        for (Geometry geometry : targets) {
-            Mesh mesh = geometry.getMesh();
-            if (mesh != null && mesh.isAnimated()) {
-                updateSkinnedMeshBound(geometry, mesh, boneOffsetMatrices);
+        if (updateBounds) {
+            // Hardware skinning transforms vertices on the GPU, so the CPU-side vertex
+            // buffer is not updated. Compute the animated bounding volume from the bind
+            // pose positions and the current skinning matrices so culling is correct.
+            for (Geometry geometry : targets) {
+                Mesh mesh = geometry.getMesh();
+                if (mesh != null && mesh.isAnimated()) {
+                    updateSkinnedMeshBound(geometry, mesh, boneOffsetMatrices);
+                }
             }
         }
     }
@@ -879,6 +916,7 @@ public void write(JmeExporter ex) throws IOException {
         super.write(ex);
         OutputCapsule oc = ex.getCapsule(this);
         oc.write(armature, "armature", null);
+        oc.write(updateBounds, "updateBounds", false);
     }
 
     /**
@@ -893,6 +931,7 @@ public void read(JmeImporter im) throws IOException {
         super.read(im);
         InputCapsule in = im.getCapsule(this);
         armature = (Armature) in.readSavable("armature", null);
+        updateBounds = in.readBoolean("updateBounds", false);
 
         for (MatParamOverride mpo : spatial.getLocalMatParamOverrides().getArray()) {
             if (mpo.getName().equals("NumberOfBones") || mpo.getName().equals("BoneMatrices")) {
diff --git a/jme3-core/src/main/java/com/jme3/animation/SkeletonControl.java b/jme3-core/src/main/java/com/jme3/animation/SkeletonControl.java
@@ -108,6 +108,13 @@ public class SkeletonControl extends AbstractControl implements Cloneable, JmeCl
      */
     private transient Matrix4f[] offsetMatrices;
 
+    /**
+     * When true, the bounding volumes of animated geometries are updated each
+     * frame to match the current pose, ensuring correct frustum culling.
+     * Disabled by default because it adds CPU cost every frame.
+     */
+    private boolean updateBounds = false;
+
     private MatParamOverride numberOfBonesParam;
     private MatParamOverride boneMatricesParam;
 
@@ -193,6 +200,32 @@ public boolean isHardwareSkinningUsed() {
         return hwSkinningEnabled;
     }
 
+    /**
+     * Enables or disables per-frame bounding-volume updates for animated
+     * geometries. When enabled, the bounding volume of each deformed geometry
+     * is recomputed every render frame to match the current animation pose,
+     * ensuring correct frustum culling at the cost of additional CPU work.
+     * Disabled by default.
+     *
+     * @param updateBounds true to update bounds each frame, false to keep
+     *                     static bind-pose bounds (default=false)
+     * @see #isUpdateBounds()
+     */
+    public void setUpdateBounds(boolean updateBounds) {
+        this.updateBounds = updateBounds;
+    }
+
+    /**
+     * Returns whether per-frame bounding-volume updates are enabled for
+     * animated geometries.
+     *
+     * @return true if bounds are updated each frame, false otherwise
+     * @see #setUpdateBounds(boolean)
+     */
+    public boolean isUpdateBounds() {
+        return updateBounds;
+    }
+
     /**
      * Creates a skeleton control. The list of targets will be acquired
      * automatically when the control is attached to a node.
@@ -261,22 +294,26 @@ private void controlRenderSoftware() {
             // already ensured this mesh is animated.
             // Otherwise a crash will happen in skin update.
             softwareSkinUpdate(mesh, offsetMatrices);
-            // Update the mesh bounding volume to reflect the animated vertex positions.
-            geometry.updateModelBound();
+            if (updateBounds) {
+                // Update the mesh bounding volume to reflect the animated vertex positions.
+                geometry.updateModelBound();
+            }
         }
     }
 
     private void controlRenderHardware() {
         offsetMatrices = skeleton.computeSkinningMatrices();
         boneMatricesParam.setValue(offsetMatrices);
 
-        // Hardware skinning transforms vertices on the GPU, so the CPU-side vertex
-        // buffer is not updated. Compute the animated bounding volume from the bind
-        // pose positions and the current skinning matrices so culling is correct.
-        for (Geometry geometry : targets) {
-            Mesh mesh = geometry.getMesh();
-            if (mesh != null && mesh.isAnimated()) {
-                updateSkinnedMeshBound(geometry, mesh, offsetMatrices);
+        if (updateBounds) {
+            // Hardware skinning transforms vertices on the GPU, so the CPU-side vertex
+            // buffer is not updated. Compute the animated bounding volume from the bind
+            // pose positions and the current skinning matrices so culling is correct.
+            for (Geometry geometry : targets) {
+                Mesh mesh = geometry.getMesh();
+                if (mesh != null && mesh.isAnimated()) {
+                    updateSkinnedMeshBound(geometry, mesh, offsetMatrices);
+                }
             }
         }
     }
@@ -827,6 +864,7 @@ public void write(JmeExporter ex) throws IOException {
 
         oc.write(numberOfBonesParam, "numberOfBonesParam", null);
         oc.write(boneMatricesParam, "boneMatricesParam", null);
+        oc.write(updateBounds, "updateBounds", false);
     }
 
     @Override
@@ -837,6 +875,7 @@ public void read(JmeImporter im) throws IOException {
 
         numberOfBonesParam = (MatParamOverride) in.readSavable("numberOfBonesParam", null);
         boneMatricesParam = (MatParamOverride) in.readSavable("boneMatricesParam", null);
+        updateBounds = in.readBoolean("updateBounds", false);
 
         if (numberOfBonesParam == null) {
             numberOfBonesParam = new MatParamOverride(VarType.Int, "NumberOfBones", null);
diff --git a/jme3-core/src/test/java/com/jme3/test/PreventCoreIssueRegressions.java b/jme3-core/src/test/java/com/jme3/test/PreventCoreIssueRegressions.java
@@ -150,6 +150,8 @@ public void testIssue343() {
 
         // Force software skinning so bounds are computed from CPU vertex positions.
         sControl.setHardwareSkinningPreferred(false);
+        // Enable per-frame bounds update (off by default).
+        sControl.setUpdateBounds(true);
 
         // Record the world bound in the bind pose.
         cgModel.updateGeometricState();
diff --git a/jme3-examples/src/main/java/jme3test/animation/TestAnimatedModelBound.java b/jme3-examples/src/main/java/jme3test/animation/TestAnimatedModelBound.java
@@ -0,0 +1,167 @@
+/*
+ * Copyright (c) 2009-2025 jMonkeyEngine
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package jme3test.animation;
+
+import com.jme3.anim.AnimComposer;
+import com.jme3.anim.SkinningControl;
+import com.jme3.app.SimpleApplication;
+import com.jme3.bounding.BoundingBox;
+import com.jme3.bounding.BoundingVolume;
+import com.jme3.font.BitmapText;
+import com.jme3.input.KeyInput;
+import com.jme3.input.controls.ActionListener;
+import com.jme3.input.controls.KeyTrigger;
+import com.jme3.light.AmbientLight;
+import com.jme3.light.DirectionalLight;
+import com.jme3.material.Material;
+import com.jme3.math.ColorRGBA;
+import com.jme3.math.Vector3f;
+import com.jme3.scene.Geometry;
+import com.jme3.scene.Node;
+import com.jme3.scene.debug.WireBox;
+
+/**
+ * Demonstrates the toggleable per-frame bounding-volume update feature of
+ * {@link SkinningControl}.
+ *
+ * <p>The Elephant model plays its "legUp" animation in a loop. A wireframe
+ * box shows the world bounding volume of the model. Press {@code B} to
+ * toggle {@link SkinningControl#setUpdateBounds(boolean) updateBounds}:
+ *
+ * <ul>
+ *   <li><b>updateBounds OFF (default):</b> The bounding box stays fixed at
+ *       the bind pose — it will not grow when the leg extends upward.</li>
+ *   <li><b>updateBounds ON:</b> The bounding box tracks the animated pose
+ *       correctly, expanding and contracting as the leg moves.</li>
+ * </ul>
+ *
+ * @see SkinningControl#setUpdateBounds(boolean)
+ */
+public class TestAnimatedModelBound extends SimpleApplication {
+
+    /** Root node of the loaded model. */
+    private Node modelRoot;
+    /** SkinningControl whose updateBounds flag we toggle. */
+    private SkinningControl skinningControl;
+    /** Wireframe box visualizing the world bounding volume each frame. */
+    private Geometry boundGeom;
+    /** Label shown in the top-left corner. */
+    private BitmapText statusText;
+
+    public static void main(String[] args) {
+        TestAnimatedModelBound app = new TestAnimatedModelBound();
+        app.start();
+    }
+
+    @Override
+    public void simpleInitApp() {
+        // ---------- lighting ----------
+        rootNode.addLight(new AmbientLight(new ColorRGBA(0.3f, 0.3f, 0.3f, 1f)));
+        DirectionalLight sun = new DirectionalLight(
+                new Vector3f(-1f, -1f, -1f).normalizeLocal(),
+                ColorRGBA.White);
+        rootNode.addLight(sun);
+
+        // ---------- camera ----------
+        cam.setLocation(new Vector3f(0f, 2f, 8f));
+        cam.lookAt(Vector3f.ZERO, Vector3f.UNIT_Y);
+        flyCam.setMoveSpeed(5f);
+
+        // ---------- model ----------
+        modelRoot = (Node) assetManager.loadModel("Models/Elephant/Elephant.mesh.xml");
+        float scale = 0.04f;
+        modelRoot.scale(scale);
+        rootNode.attachChild(modelRoot);
+
+        skinningControl = modelRoot.getControl(SkinningControl.class);
+        // updateBounds is OFF by default — the bounding box will stay static.
+        skinningControl.setHardwareSkinningPreferred(false); // easier to visualize with SW skinning
+
+        AnimComposer composer = modelRoot.getControl(AnimComposer.class);
+        composer.setCurrentAction("legUp");
+
+        // ---------- bounding-box visualizer ----------
+        // Create an unshaded wireframe geometry; we reposition it every frame.
+        Material wireMat = new Material(assetManager,
+                "Common/MatDefs/Misc/Unshaded.j3md");
+        wireMat.setColor("Color", ColorRGBA.Yellow);
+        wireMat.getAdditionalRenderState().setWireframe(true);
+
+        boundGeom = new Geometry("boundingBox", new WireBox(1f, 1f, 1f));
+        boundGeom.setMaterial(wireMat);
+        rootNode.attachChild(boundGeom);
+
+        // ---------- HUD ----------
+        guiFont = assetManager.loadFont("Interface/Fonts/Default.fnt");
+        statusText = new BitmapText(guiFont);
+        statusText.setSize(guiFont.getCharSet().getRenderedSize());
+        statusText.setLocalTranslation(10f,
+                settings.getHeight() - 10f, 0f);
+        guiNode.attachChild(statusText);
+        updateStatusText();
+
+        // ---------- key binding ----------
+        inputManager.addMapping("ToggleBounds",
+                new KeyTrigger(KeyInput.KEY_B));
+        inputManager.addListener(new ActionListener() {
+            @Override
+            public void onAction(String name, boolean isPressed, float tpf) {
+                if (isPressed) {
+                    boolean current = skinningControl.isUpdateBounds();
+                    skinningControl.setUpdateBounds(!current);
+                    updateStatusText();
+                }
+            }
+        }, "ToggleBounds");
+    }
+
+    @Override
+    public void simpleUpdate(float tpf) {
+        // Update the wireframe box to match the current world bounding volume.
+        modelRoot.updateGeometricState();
+        BoundingVolume wb = modelRoot.getWorldBound();
+        if (wb instanceof BoundingBox) {
+            BoundingBox bbox = (BoundingBox) wb;
+            Vector3f center = bbox.getCenter();
+            ((WireBox) boundGeom.getMesh()).updatePositions(
+                    bbox.getXExtent(), bbox.getYExtent(), bbox.getZExtent());
+            boundGeom.setLocalTranslation(center);
+        }
+    }
+
+    /** Refreshes the HUD label that shows the current updateBounds state. */
+    private void updateStatusText() {
+        boolean on = skinningControl.isUpdateBounds();
+        statusText.setText(
+                "Press B to toggle updateBounds\n"
+                + "updateBounds: " + (on ? "ON  — bounding box tracks the animated pose"
+                                         : "OFF — bounding box stays at bind pose (default)"));
+    }
+}
