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..d582df33cd 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,159 @@ 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 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. + * + * @param param The {@link ListenerParam} to update on the renderer. + */ + private void updateListenerParam(ListenerParam param) { + if (renderer != null) { + renderer.updateListenerParam(this, param); + } } }