From 30aa1dbde38f51cc9b9d758e97dd760a67b81218 Mon Sep 17 00:00:00 2001 From: Wyatt Gillette Date: Fri, 2 May 2025 19:04:31 +0200 Subject: [PATCH 1/3] com.jme3.audio.Listener: format code + javadoc --- .../main/java/com/jme3/audio/Listener.java | 120 ++++++++++++++++-- 1 file changed, 107 insertions(+), 13 deletions(-) diff --git a/jme3-core/src/main/java/com/jme3/audio/Listener.java b/jme3-core/src/main/java/com/jme3/audio/Listener.java index 5ef28b4f09..8fa10c81fb 100644 --- a/jme3-core/src/main/java/com/jme3/audio/Listener.java +++ b/jme3-core/src/main/java/com/jme3/audio/Listener.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009-2012 jMonkeyEngine + * Copyright (c) 2009-2025 jMonkeyEngine * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -34,6 +34,11 @@ import com.jme3.math.Quaternion; import com.jme3.math.Vector3f; +/** + * Represents the audio listener in the 3D sound scene. + * The listener defines the point of view from which sound is heard, + * influencing spatial audio effects like panning and Doppler shift. + */ public class Listener { private final Vector3f location; @@ -42,72 +47,161 @@ public class Listener { private float volume = 1; private AudioRenderer renderer; + /** + * Constructs a new {@code Listener} with default parameters. + */ public Listener() { location = new Vector3f(); velocity = new Vector3f(); rotation = new Quaternion(); } + /** + * Constructs a new {@code Listener} by copying the properties of another {@code Listener}. + * + * @param source The {@code Listener} to copy the properties from. + */ public Listener(Listener source) { - location = source.location.clone(); - velocity = source.velocity.clone(); - rotation = source.rotation.clone(); - volume = source.volume; + this.location = source.location.clone(); + this.velocity = source.velocity.clone(); + this.rotation = source.rotation.clone(); + this.volume = source.volume; + this.renderer = source.renderer; // Note: Renderer is also copied } + /** + * Sets the {@link AudioRenderer} associated with this listener. + * The renderer is responsible for applying the listener's parameters + * to the audio output. + * + * @param renderer The {@link AudioRenderer} to associate with. + */ public void setRenderer(AudioRenderer renderer) { this.renderer = renderer; } + /** + * Gets the current volume of the listener. + * + * @return The current volume. + */ public float getVolume() { return volume; } + /** + * Sets the volume of the listener. + * If an {@link AudioRenderer} is set, it will be notified of the volume change. + * + * @param volume The new volume. + */ public void setVolume(float volume) { this.volume = volume; - if (renderer != null) - renderer.updateListenerParam(this, ListenerParam.Volume); + updateListenerParam(ListenerParam.Volume); } + /** + * Gets the current location of the listener in world space. + * + * @return The listener's location as a {@link Vector3f}. + */ public Vector3f getLocation() { return location; } + /** + * Gets the current rotation of the listener in world space. + * + * @return The listener's rotation as a {@link Quaternion}. + */ public Quaternion getRotation() { return rotation; } + /** + * Gets the current velocity of the listener. + * This is used for Doppler effect calculations. + * + * @return The listener's velocity as a {@link Vector3f}. + */ public Vector3f getVelocity() { return velocity; } + /** + * Gets the left direction vector of the listener. + * This vector is derived from the listener's rotation. + * + * @return The listener's left direction as a {@link Vector3f}. + */ public Vector3f getLeft() { return rotation.getRotationColumn(0); } + /** + * Gets the up direction vector of the listener. + * This vector is derived from the listener's rotation. + * + * @return The listener's up direction as a {@link Vector3f}. + */ public Vector3f getUp() { return rotation.getRotationColumn(1); } + /** + * Gets the forward direction vector of the listener. + * This vector is derived from the listener's rotation. + * + * @return The listener's forward direction. + */ public Vector3f getDirection() { return rotation.getRotationColumn(2); } + /** + * Sets the location of the listener in world space. + * If an {@link AudioRenderer} is set, it will be notified of the position change. + * + * @param location The new location of the listener. + */ public void setLocation(Vector3f location) { this.location.set(location); - if (renderer != null) - renderer.updateListenerParam(this, ListenerParam.Position); + updateListenerParam(ListenerParam.Position); } + /** + * Sets the rotation of the listener. + * This defines the listener's orientation in world space. + * If an {@link AudioRenderer} is set, it will be notified of the rotation change. + * + * @param rotation The new rotation of the listener. + */ public void setRotation(Quaternion rotation) { this.rotation.set(rotation); - if (renderer != null) - renderer.updateListenerParam(this, ListenerParam.Rotation); + updateListenerParam(ListenerParam.Rotation); } + /** + * Sets the velocity of the listener. + * This is used for Doppler effect calculations. + * If an {@link AudioRenderer} is set, it will be notified of the velocity change. + * + * @param velocity The new velocity of the listener. + */ public void setVelocity(Vector3f velocity) { this.velocity.set(velocity); - if (renderer != null) - renderer.updateListenerParam(this, ListenerParam.Velocity); + updateListenerParam(ListenerParam.Velocity); + } + + /** + * Updates the associated {@link AudioRenderer} with the specified listener parameter. + * This method checks if a renderer is set before attempting to update it. + * + * @param param The {@link ListenerParam} to update on the renderer. + */ + private void updateListenerParam(ListenerParam param) { + if (renderer != null) { + renderer.updateListenerParam(this, param); + } } } From e92ea4fcc1a830edcd678427bda3fcbc2c376a1d Mon Sep 17 00:00:00 2001 From: Wyatt Gillette Date: Fri, 2 May 2025 19:16:32 +0200 Subject: [PATCH 2/3] Update Listener.java update javadoc --- jme3-core/src/main/java/com/jme3/audio/Listener.java | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/jme3-core/src/main/java/com/jme3/audio/Listener.java b/jme3-core/src/main/java/com/jme3/audio/Listener.java index 8fa10c81fb..d111f7dabb 100644 --- a/jme3-core/src/main/java/com/jme3/audio/Listener.java +++ b/jme3-core/src/main/java/com/jme3/audio/Listener.java @@ -170,8 +170,7 @@ public void setLocation(Vector3f location) { } /** - * Sets the rotation of the listener. - * This defines the listener's orientation in world space. + * Sets the rotation of the listener in world space. * If an {@link AudioRenderer} is set, it will be notified of the rotation change. * * @param rotation The new rotation of the listener. From 10add9115519a08a6a1a48aa4dcf55ed394b8cf4 Mon Sep 17 00:00:00 2001 From: Wyatt Gillette Date: Sat, 3 May 2025 00:10:24 +0200 Subject: [PATCH 3/3] update javadoc --- jme3-core/src/main/java/com/jme3/audio/Listener.java | 1 - 1 file changed, 1 deletion(-) diff --git a/jme3-core/src/main/java/com/jme3/audio/Listener.java b/jme3-core/src/main/java/com/jme3/audio/Listener.java index d111f7dabb..d582df33cd 100644 --- a/jme3-core/src/main/java/com/jme3/audio/Listener.java +++ b/jme3-core/src/main/java/com/jme3/audio/Listener.java @@ -194,7 +194,6 @@ public void setVelocity(Vector3f velocity) { /** * Updates the associated {@link AudioRenderer} with the specified listener parameter. - * This method checks if a renderer is set before attempting to update it. * * @param param The {@link ListenerParam} to update on the renderer. */