atavism.server.voice
Class PositionalVoiceGroup

java.lang.Object
  atavism.server.voice.BasicVoiceGroup
      atavism.server.voice.PositionalVoiceGroup

All Implemented Interfaces:

VoiceGroup

public class PositionalVoiceGroup
extends BasicVoiceGroup

This class implements VoiceGroup interface, and is used to implement positional voice groups. In a positional voice group, each listener hears the players who are nearby, and the speaker volume falls off as the distance between speaker and listener increases.

Nested Class Summary

static class

PositionalVoiceGroup.CompareLocations A comparator class that compares locations of speakers to order the closest ones near the front of the list.

Field Summary

protected float	audibleRadius Initialized by the constructor; the maximum distance in millimeters between players in a positional voice group at which they can hear each other, adjusted by the hystericalMargin.
protected float	hystericalMargin The hysteresis constant: don't change whether a pair of positonal group members are in-radius of each other if the distance in millimeters is within this distance of the audibleRadius.

Fields inherited from class atavism.server.voice.BasicVoiceGroup

allowedMembers, association, defaultPriority, groupOid, lock, loggingRecomputeVoices, maxVoices, members, voiceSender

Constructor Summary

PositionalVoiceGroup(OID groupOid, java.lang.Object association, VoiceSender voiceSender, int maxVoices, float audibleRadius, float hystericalMargin)
Create a PositionalVoiceGroup

Method Summary

byte	addListenerVoice(PositionalGroupMember speaker, PositionalGroupMember listener) Allocate a listener voice number for the given sound speaker.
GroupMember	addMember(OID memberOid, VoiceConnection memberCon, int priority, boolean allowedSpeaker) Create a member with the given oid, and associate it with memberCon.
protected void	addSpeakerListenerPair(PositionalGroupMember speaker, PositionalGroupMember listener) Create a positional speaker/listener pair.
void	addTrackedPerceiver(PositionalGroupMember perceiverMember, OID instanceOid) Called by the VoicePlugin to indicate that a member's location should be tracked when a member is added to a positional group
protected void	changeListening(GroupMember listener, boolean add) Change a listener from not listening to listening, or vice versa
protected void	changeSpeaking(GroupMember gspeaker, boolean add) Change a speaker from not speaking to speaking, or vice versa
protected void	clearMembersPerceived(PositionalGroupMember perceiverMember) Clear the set of perceivedOids and membersInRadius for a member, but if the member itself is in the membersInRadius, add it back, because this is how the listenToYourself mechanism works.
void	handlePositionalSpeakerChange(PositionalGroupMember speaker, PositionalGroupMember listener, boolean inRadius) Handle a positional speaker moving in and out of the audible radius of positional listener.
boolean	isPositional() Return true if the group is a positional group; that is, if membership in the group is determined by being near the listener, and the priority of speakers is determined by how near any speaker is.
protected java.lang.String	makeOidString(java.util.Collection<OID> oids) Return a string of comma-separated oids from a collection of oids, used for logging.
protected java.lang.String	makeOidStringFromMembers(java.util.Collection<PositionalGroupMember> members) Return a string of comma-separated oids from a collection of members, used for logging.
void	maybeChangePerceivedObject(PositionalGroupMember perceiverMember, OID perceivedOid, boolean added) Called by the VoicePlugin in response to a PerceptionMessage to indicate that another member should be added or removed from the member's perceivedOids.
java.util.List<GroupMember>	membersListeningToSpeaker(PositionalGroupMember speaker) Return a list of members listening to this member.
boolean	nowListeningTo(PositionalGroupMember speaker, PositionalGroupMember listener) Return true if the listener is now listening to the speaker.
protected void	recomputeListenersInRadius(PositionalGroupMember speaker) For each listener in radius of the speaker, recompute the voices for the listener.
protected void	recomputeListenerVoices(GroupMember glistener) Recompute the voice channels for the given listener
protected void	recomputeListenerVoices(PositionalGroupMember listener, java.util.Set<PositionalGroupMember> membersToConsider) Recompute the voice channels for the given listener, drawing potential speakers from the membersToConsider.
protected void	removeSpeakerListenerPair(PositionalGroupMember speaker, PositionalGroupMember listener) Remove a positional speaker/listener pair.
void	removeTrackedPerceiver(OID playerOid) Called by the VoicePlugin to indicate that a member's location should be no longer be tracked when a member is removed from a positional group, or the member changes instances.
void	removeTrackedPerceiver(PositionalGroupMember perceiverMember) Called by the VoicePlugin to indicate that a member's location should be no longer be tracked when a member is removed from a positional group, or the member changes instances.
void	testProximity(PositionalGroupMember perceiverMember, PositionalGroupMember perceivedMember, boolean interpolatePerceiver, boolean interpolatePerceived) Test if the perceived object has come in or out of range of the perceiver object; if so, we change the inRangeOids set for the perceiver and the perceived members.
void	unloadInstance(OID instanceOid) Called by the VoicePlugin when an instance is terminated.
void	updateWorldNode(PositionalGroupMember perceiverMember, BasicWorldNode bwnode) Called by the voice plugin when an UpdateWorldNode message is received for a player in the group.

Methods inherited from class atavism.server.voice.BasicVoiceGroup

addMember, addMemberAllowed, addString, eligibleSpeakerListenerPair, endListeningToSpeaker, getAllMembers, getAllowedMembers, getDefaultPriority, getGroupOid, getMember, isAllowedSpeaker, isListener, isMember, isMemberSpeaking, onAfterAddMember, onAfterRemoveMember, recomputeVoicesFromSpeakerIterator, removeMember, sendVoiceFrameToListeners, setAllowedMembers, setAllowedSpeaker, setAllowedSpeaker, setListener, setListener, setMemberSpeaking, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

audibleRadius

protected float audibleRadius

Initialized by the constructor; the maximum distance in millimeters between players in a positional voice group at which they can hear each other, adjusted by the hystericalMargin.

hystericalMargin

protected float hystericalMargin

The hysteresis constant: don't change whether a pair of positonal group members are in-radius of each other if the distance in millimeters is within this distance of the audibleRadius.

Constructor Detail

PositionalVoiceGroup

public PositionalVoiceGroup(OID groupOid,
                            java.lang.Object association,
                            VoiceSender voiceSender,
                            int maxVoices,
                            float audibleRadius,
                            float hystericalMargin)

Create a PositionalVoiceGroup

Parameters:

groupOid - The oid of the group, which is unique across all voice groups.

association - An object-valued data member that is unused in BasicVoiceGroup, but available to derived classes.

voiceSender - The abstraction that allows the voice group to send messages to listeners.

maxVoices - The maximum number of voice channels that may ever be simultaneously in use by any client

audibleRadius - The maximum distance in millimeters between players in a positional voice group at which they can hear each other, adjusted by the hystericalMargin.

hystericalMargin - The distance in millimeters of hysteresis in initiating or terminating a pair of players hearing each other. The hysterical margin ensures that when a player moves back and forth slightly, we don't continuously initiate and terminate the voice channel to other players.

Method Detail

addMember

public GroupMember addMember(OID memberOid,
                             VoiceConnection memberCon,
                             int priority,
                             boolean allowedSpeaker)

Create a member with the given oid, and associate it with memberCon.

Specified by:

addMember in interface VoiceGroup

Specified by:

addMember in class BasicVoiceGroup

Parameters:

memberOid - The oid of the member.

memberCon - The VoiceConnection object connecting the voice server with the client

priority - The speaking priority that the member should be assigned; speakers with higher priorities will be heard over speakers with lower priorities.

allowedSpeaker - If true, the new member is allowed to speak in the group; if false they will not be heard by members by members of the group.

Returns:

The newly-created group member.

changeSpeaking

protected void changeSpeaking(GroupMember gspeaker,
                              boolean add)

Change a speaker from not speaking to speaking, or vice versa

Specified by:

changeSpeaking in class BasicVoiceGroup

Parameters:

gspeaker - A GroupMember instance whose speaking state is to be changed.

add - If true, change the speaker from not speaking to speaking, if false, from speaking to not speaking.

changeListening

protected void changeListening(GroupMember listener,
                               boolean add)

Change a listener from not listening to listening, or vice versa

Specified by:

changeListening in class BasicVoiceGroup

Parameters:

listener - A GroupMember instance whose listening state is to be changed.

add - If true, change the listener from not listening to listening, if false, from listening to not listening.

updateWorldNode

public void updateWorldNode(PositionalGroupMember perceiverMember,
                            BasicWorldNode bwnode)

Called by the voice plugin when an UpdateWorldNode message is received for a player in the group.

Parameters:

perceiverMember - The member whose position/direction/orientation should be updated.

bwnode - The BasicWorldNode containing the new position/direction/orientation.

testProximity

public void testProximity(PositionalGroupMember perceiverMember,
                          PositionalGroupMember perceivedMember,
                          boolean interpolatePerceiver,
                          boolean interpolatePerceived)

Test if the perceived object has come in or out of range of the perceiver object; if so, we change the inRangeOids set for the perceiver and the perceived members.

Parameters:

perceiverMember - The member who received the UpdateWorldNodeMessage or PerceptionMessage

perceivedMember - A member in the perceivedOids set of the perceiverMember.

interpolatePerceiver - If true, we should interpolate the location of the perceiver; if false, we should use the lastLoc of the perceiver.

interpolatePerceived - If true, we should interpolate the location of the perceived; if false, we should use the lastLoc of the perceived.

handlePositionalSpeakerChange

public void handlePositionalSpeakerChange(PositionalGroupMember speaker,
                                          PositionalGroupMember listener,
                                          boolean inRadius)

Handle a positional speaker moving in and out of the audible radius of positional listener.

Parameters:

speaker - The speaker member whose position has changed.

listener - The listener member who may be inside the radius of the speaker.

inRadius - True if the speaker and listener are now in listening range of each other; false otherwise.

isPositional

public boolean isPositional()

Description copied from class: BasicVoiceGroup

Return true if the group is a positional group; that is, if membership in the group is determined by being near the listener, and the priority of speakers is determined by how near any speaker is.

Specified by:

isPositional in interface VoiceGroup

Specified by:

isPositional in class BasicVoiceGroup

Returns:

True, because this is a positional voice group.

addSpeakerListenerPair

protected void addSpeakerListenerPair(PositionalGroupMember speaker,
                                      PositionalGroupMember listener)

Create a positional speaker/listener pair.

Parameters:

speaker - The speaker group member of the pair.

listener - The listener group member of the pair.

removeSpeakerListenerPair

protected void removeSpeakerListenerPair(PositionalGroupMember speaker,
                                         PositionalGroupMember listener)

Remove a positional speaker/listener pair.

Parameters:

speaker - The speaker group member of the pair.

listener - The listener group member of the pair.

recomputeListenersInRadius

protected void recomputeListenersInRadius(PositionalGroupMember speaker)

For each listener in radius of the speaker, recompute the voices for the listener.

Parameters:

speaker - The speaker group member of the pair.

recomputeListenerVoices

protected void recomputeListenerVoices(GroupMember glistener)

Recompute the voice channels for the given listener

Specified by:

recomputeListenerVoices in class BasicVoiceGroup

Parameters:

glistener - The listener group member whose voice channels will be recomputed.

recomputeListenerVoices

protected void recomputeListenerVoices(PositionalGroupMember listener,
                                       java.util.Set<PositionalGroupMember> membersToConsider)

Recompute the voice channels for the given listener, drawing potential speakers from the membersToConsider.

Parameters:

listener - The listener group member whose voice channels will be recomputed.

membersToConsider - The set of speakers within radius from the listener.

addListenerVoice

public byte addListenerVoice(PositionalGroupMember speaker,
                             PositionalGroupMember listener)

Allocate a listener voice number for the given sound speaker. This doesn't send a message; just modifies the lists of listeners.

Parameters:

speaker - The speaker group member of the speaker/listener pair.

listener - The listener group member of the speaker/listener pair.

Returns:

The voiceNumber of the added voice from the point of view of the listener.

membersListeningToSpeaker

public java.util.List<GroupMember> membersListeningToSpeaker(PositionalGroupMember speaker)

Return a list of members listening to this member. Currently unused

Parameters:

speaker - The speaker group member whose listeners should be returned.

Returns:

The list of members listening to the speaker.

nowListeningTo

public boolean nowListeningTo(PositionalGroupMember speaker,
                              PositionalGroupMember listener)

Return true if the listener is now listening to the speaker. Currently unused

Parameters:

speaker - The speaker group member of the pair.

listener - The listener group member of the pair.

Returns:

True if the listener is now listening to the speaker.

unloadInstance

public void unloadInstance(OID instanceOid)

Called by the VoicePlugin when an instance is terminated. At that point, there should be no members in the instance.

Parameters:

instanceOid - The oid of the instance being unloaded.

addTrackedPerceiver

public void addTrackedPerceiver(PositionalGroupMember perceiverMember,
                                OID instanceOid)

Called by the VoicePlugin to indicate that a member's location should be tracked when a member is added to a positional group

Parameters:

perceiverMember - The member to be tracked.

instanceOid - The oid of the instance to which the member belongs.

makeOidString

protected java.lang.String makeOidString(java.util.Collection<OID> oids)

Return a string of comma-separated oids from a collection of oids, used for logging.

Parameters:

oids - A collection of oids to be formatted.

Returns:

A string containing the comma-separated oids.

makeOidStringFromMembers

protected java.lang.String makeOidStringFromMembers(java.util.Collection<PositionalGroupMember> members)

Return a string of comma-separated oids from a collection of members, used for logging.

Parameters:

members - A collection of members whose oids are to be formatted.

Returns:

A string containing the comma-separated oids.

clearMembersPerceived

protected void clearMembersPerceived(PositionalGroupMember perceiverMember)

Clear the set of perceivedOids and membersInRadius for a member, but if the member itself is in the membersInRadius, add it back, because this is how the listenToYourself mechanism works.

Parameters:

perceiverMember - The member whose perceivedOids and membersInRadius sets should be cleared.

removeTrackedPerceiver

public void removeTrackedPerceiver(OID playerOid)

Called by the VoicePlugin to indicate that a member's location should be no longer be tracked when a member is removed from a positional group, or the member changes instances.

Parameters:

playerOid - The oid of the member that should no longer be tracked.

removeTrackedPerceiver

public void removeTrackedPerceiver(PositionalGroupMember perceiverMember)

Called by the VoicePlugin to indicate that a member's location should be no longer be tracked when a member is removed from a positional group, or the member changes instances.

Parameters:

perceiverMember - The member that should no longer be tracked.

maybeChangePerceivedObject

public void maybeChangePerceivedObject(PositionalGroupMember perceiverMember,
                                       OID perceivedOid,
                                       boolean added)

Called by the VoicePlugin in response to a PerceptionMessage to indicate that another member should be added or removed from the member's perceivedOids.

Parameters:

perceiverMember - The member whose perceivedOids should be adjusted.

perceivedOid - The oid of the member that should be added or removed from the perceiverMember's perceivedOids.

added - If true, the perceivedOid should be added; if false, removed.