Update BillboardControl.java

Author: capdevon

jme3-core/src/main/java/com/jme3/scene/control/BillboardControl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009-2021 jMonkeyEngine
+ * Copyright (c) 2009-2025 jMonkeyEngine
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -46,12 +46,31 @@
 import com.jme3.scene.Spatial;
 import java.io.IOException;
 
+/**
+ * <code>BillboardControl</code> is a special control that makes a spatial always
+ * face the camera. This is useful for health bars, or other 2D elements
+ * that should always be oriented towards the viewer in a 3D scene.
+ * <p>
+ * The alignment can be customized to different modes:
+ * <ul>
+ * <li>Screen: The billboard always faces the screen, keeping its 'up' vector aligned with camera's 'up'.</li>
+ * <li>Camera: The billboard always faces the camera position directly.</li>
+ * <li>AxialY: The billboard faces the camera but keeps its local Y-axis fixed.</li>
+ * <li>AxialZ: The billboard faces the camera but keeps its local Z-axis fixed.</li>
+ * </ul>
+ */
 public class BillboardControl extends AbstractControl {
 
-    private Matrix3f orient;
-    private Vector3f look;
-    private Vector3f left;
-    private Alignment alignment;
+    // Member variables for calculations, reused to avoid constant object allocation.
+    private final Matrix3f orient = new Matrix3f();
+    private final Vector3f look = new Vector3f();
+    private final Vector3f left = new Vector3f();
+    private final Quaternion tempQuat = new Quaternion();
+
+    /**
+     * The current alignment mode for the billboard.
+     */
+    private Alignment alignment = Alignment.Screen;
 
     /**
      * Determines how the billboard is aligned to the screen/camera.
@@ -61,38 +80,36 @@ public enum Alignment {
          * Aligns this Billboard to the screen.
          */
         Screen,
-
         /**
          * Aligns this Billboard to the camera position.
          */
         Camera,
-
         /**
           * Aligns this Billboard to the screen, but keeps the Y axis fixed.
           */
         AxialY,
-
         /**
          * Aligns this Billboard to the screen, but keeps the Z axis fixed.
          */
         AxialZ;
     }
 
+    /**
+     * Constructs a new `BillboardControl` with the default alignment set to
+     * {@link Alignment#Screen}.
+     */
     public BillboardControl() {
-        super();
-        orient = new Matrix3f();
-        look = new Vector3f();
-        left = new Vector3f();
-        alignment = Alignment.Screen;
     }
 
-    // default implementation from AbstractControl is equivalent
-    //public Control cloneForSpatial(Spatial spatial) {
-    //    BillboardControl control = new BillboardControl();
-    //    control.alignment = this.alignment;
-    //    control.setSpatial(spatial);
-    //    return control;
-    //}
+    /**
+     * Constructs a new `BillboardControl` with the specified alignment.
+     *
+     * @param alignment The desired alignment type for the billboard.
+     * See {@link Alignment} for available options.
+     */
+    public BillboardControl(Alignment alignment) {
+        this.alignment = alignment;
+    }
 
     @Override
     protected void controlUpdate(float tpf) {
@@ -102,25 +119,26 @@ protected void controlUpdate(float tpf) {
     protected void controlRender(RenderManager rm, ViewPort vp) {
         Camera cam = vp.getCamera();
         rotateBillboard(cam);
+        updateRefreshFlags();
     }
 
-    private void fixRefreshFlags(){
+    private void updateRefreshFlags() {
         // force transforms to update below this node
         spatial.updateGeometricState();
 
         // force world bound to update
         Spatial rootNode = spatial;
-        while (rootNode.getParent() != null){
+        while (rootNode.getParent() != null) {
             rootNode = rootNode.getParent();
         }
         rootNode.getWorldBound();
     }
 
     /**
-     * rotate the billboard based on the type set
+     * Rotates the billboard based on the alignment type set.
+     * This method is called every frame during the render phase.
      *
-     * @param cam
-     *            Camera
+     * @param cam The current Camera used for rendering.
      */
     private void rotateBillboard(Camera cam) {
         switch (alignment) {
@@ -140,10 +158,11 @@ private void rotateBillboard(Camera cam) {
     }
 
     /**
-     * Aligns this Billboard so that it points to the camera position.
+     * Aligns this Billboard so that it points directly to the camera position.
+     * The billboard's local rotation is set to ensure its positive Z-axis
+     * points towards the camera's location.
      *
-     * @param camera
-     *            Camera
+     * @param camera The current Camera.
      */
     private void rotateCameraAligned(Camera camera) {
         look.set(camera.getLocation()).subtractLocal(
@@ -173,40 +192,47 @@ private void rotateCameraAligned(Camera camera) {
         orient.set(2, 1, xzp.z * -look.y);
         orient.set(2, 2, xzp.z * cosp);
 
-        // The billboard must be oriented to face the camera before it is
-        // transformed into the world.
+        // Set the billboard's local rotation based on the computed orientation matrix.
         spatial.setLocalRotation(orient);
-        fixRefreshFlags();
     }
 
     /**
      * Rotates the billboard so it points directly opposite the direction the
-     * camera is facing.
+     * camera is facing (screen-aligned). This means the billboard will always
+     * be flat against the screen, regardless of its position in 3D space.
+     * Its Z-axis will point against the camera's direction, and its Y-axis
+     * will align with the camera's Y-axis.
      *
-     * @param camera
-     *            Camera
+     * @param camera The current Camera.
      */
     private void rotateScreenAligned(Camera camera) {
         // co-opt diff for our in direction:
         look.set(camera.getDirection()).negateLocal();
         // co-opt loc for our left direction:
         left.set(camera.getLeft()).negateLocal();
         orient.fromAxes(left, camera.getUp(), look);
+
         Node parent = spatial.getParent();
-        Quaternion rot = new Quaternion().fromRotationMatrix(orient);
+        tempQuat.fromRotationMatrix(orient);
+        Quaternion rot = tempQuat;
+
         if (parent != null) {
-            rot =  parent.getWorldRotation().inverse().multLocal(rot);
+            rot = parent.getWorldRotation().inverse().multLocal(rot);
             rot.normalizeLocal();
         }
+
+        // Apply the calculated local rotation to the spatial.
         spatial.setLocalRotation(rot);
-        fixRefreshFlags();
     }
 
     /**
-     * Rotate the billboard towards the camera, but keeping a given axis fixed.
+     * Rotates the billboard towards the camera, but keeps a given axis fixed.
+     * This is used for {@link Alignment#AxialY} (fixed Y-axis) or
+     * {@link Alignment#AxialZ} (fixed Z-axis) alignments. The billboard will
+     * only rotate around the specified axis.
      *
-     * @param camera
-     *            Camera
+     * @param camera The current Camera.
+     * @param axis The fixed axis (e.g., {@link Vector3f#UNIT_Y} for AxialY).
      */
     private void rotateAxial(Camera camera, Vector3f axis) {
         // Compute the additional rotation required for the billboard to face
@@ -220,33 +246,51 @@ private void rotateAxial(Camera camera, Vector3f axis) {
         left.z *= 1.0f / spatial.getWorldScale().z;
 
         // squared length of the camera projection in the xz-plane
-        float lengthSquared = left.x * left.x + left.z * left.z;
+//        float lengthSquared = left.x * left.x + left.z * left.z;
+
+        // Calculate squared length of the camera projection on the plane perpendicular
+        // to the fixed axis. This determines the magnitude of the projection used
+        // for axial rotation.
+        float lengthSquared;
+        if (axis.y == 1) { // AxialY: projection on XZ plane
+            lengthSquared = left.x * left.x + left.z * left.z;
+        } else if (axis.z == 1) { // AxialZ: projection on XY plane
+            lengthSquared = left.x * left.x + left.y * left.y;
+        } else {
+            // This case should ideally not be reached with the current Alignment enum,
+            // but provides robustness for unexpected 'axis' values.
+            return;
+        }
+
+        // Check for edge case: camera is directly on the fixed axis relative to the billboard.
+        // If the projection length is too small, the rotation is undefined.
         if (lengthSquared < FastMath.FLT_EPSILON) {
-            // camera on the billboard axis, rotation not defined
+            // Rotation is undefined, so no rotation is applied.
             return;
         }
 
-        // unitize the projection
+        // Unitize the projection to get a normalized direction vector in the plane.
         float invLength = FastMath.invSqrt(lengthSquared);
         if (axis.y == 1) {
             left.x *= invLength;
-            left.y = 0.0f;
+            left.y = 0.0f; // Fix Y-component to 0 as it's axial, forcing rotation only around Y.
             left.z *= invLength;
 
             // compute the local orientation matrix for the billboard
             orient.set(0, 0, left.z);
             orient.set(0, 1, 0);
             orient.set(0, 2, left.x);
             orient.set(1, 0, 0);
-            orient.set(1, 1, 1);
+            orient.set(1, 1, 1); // Y-axis remains fixed (no rotation along Y).
             orient.set(1, 2, 0);
             orient.set(2, 0, -left.x);
             orient.set(2, 1, 0);
             orient.set(2, 2, left.z);
+
         } else if (axis.z == 1) {
             left.x *= invLength;
             left.y *= invLength;
-            left.z = 0.0f;
+            left.z = 0.0f; // Fix Z-component to 0 as it's axial, forcing rotation only around Z.
 
             // compute the local orientation matrix for the billboard
             orient.set(0, 0, left.y);
@@ -257,13 +301,11 @@ private void rotateAxial(Camera camera, Vector3f axis) {
             orient.set(1, 2, 0);
             orient.set(2, 0, 0);
             orient.set(2, 1, 0);
-            orient.set(2, 2, 1);
+            orient.set(2, 2, 1); // Z-axis remains fixed (no rotation along Z).
         }
 
-        // The billboard must be oriented to face the camera before it is
-        // transformed into the world.
+        // Apply the calculated local rotation matrix to the spatial.
         spatial.setLocalRotation(orient);
-        fixRefreshFlags();
     }
 
     /**
@@ -277,32 +319,26 @@ public Alignment getAlignment() {
 
     /**
      * Sets the type of rotation this Billboard will have. The alignment can
-     * be Camera, Screen, AxialY, or AxialZ. Invalid alignments will
-     * assume no billboard rotation.
+     * be {@link Alignment#Camera}, {@link Alignment#Screen},
+     * {@link Alignment#AxialY}, or {@link Alignment#AxialZ}.
      *
-     * @param alignment the desired alignment (Camera/Screen/AxialY/AxialZ)
+     * @param alignment The desired {@link Alignment} for the billboard's rotation behavior.
      */
     public void setAlignment(Alignment alignment) {
         this.alignment = alignment;
     }
 
     @Override
-    public void write(JmeExporter e) throws IOException {
-        super.write(e);
-        OutputCapsule capsule = e.getCapsule(this);
-        capsule.write(orient, "orient", null);
-        capsule.write(look, "look", null);
-        capsule.write(left, "left", null);
-        capsule.write(alignment, "alignment", Alignment.Screen);
+    public void write(JmeExporter ex) throws IOException {
+        super.write(ex);
+        OutputCapsule oc = ex.getCapsule(this);
+        oc.write(alignment, "alignment", Alignment.Screen);
     }
 
     @Override
-    public void read(JmeImporter importer) throws IOException {
-        super.read(importer);
-        InputCapsule capsule = importer.getCapsule(this);
-        orient = (Matrix3f) capsule.readSavable("orient", null);
-        look = (Vector3f) capsule.readSavable("look", null);
-        left = (Vector3f) capsule.readSavable("left", null);
-        alignment = capsule.readEnum("alignment", Alignment.class, Alignment.Screen);
+    public void read(JmeImporter im) throws IOException {
+        super.read(im);
+        InputCapsule ic = im.getCapsule(this);
+        alignment = ic.readEnum("alignment", Alignment.class, Alignment.Screen);
     }
 }