Module com.gw2tb.gw2ml

Package com.gw2tb.gw2ml

Class MumbleLink

java.lang.Object

com.gw2tb.gw2ml.MumbleLink

All Implemented Interfaces:

AutoCloseable

public final class MumbleLink
extends Object
implements AutoCloseable

A MumbleLink object serves as a view for the data provided by a Guild Wars 2 game client in MumbleLink format. The data may either be provided by the game client via the MumbleLink mechanism or by a custom source. An instance for the former can be obtained by calling open() - the primary entry point of GW2ML.

Since:

0.1.0

See Also:

• Mumble Wiki
• Guild Wars 2 Wiki

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
final class	MumbleLink.Context	See getContext().

Field Summary

Fields

Modifier and Type	Field	Description
static final int	BYTES	The size of the MumbleLink buffer in bytes.

Method Summary

Modifier and Type	Method	Description
void	clear()	Clears the underlying buffer by setting all bytes to zero.
void	close()	Closes this resource.
void	copy(byte[] dest)	Shorthand for copy(0, dest, 0, BYTES).
void	copy(int srcOffset, byte[] dest, int destOffset, int length)	Copies the underlying data beginning at the specified offset, to the specified offset of the destination array.
void	copy(int srcOffset, MemorySegment dest, int destOffset, int length)	Copies the underlying data beginning at the specified offset, to the specified offset of the destination buffer.
void	copy(int srcOffset, ByteBuffer dest, int destOffset, int length)	Deprecated, for removal: This API element is subject to removal in a future version. This method is deprecated in favor of copy(int, MemorySegment, int, int).
void	copy(MemorySegment dest)	Shorthand for copy(0, dest, 0, BYTES).
void	copy(ByteBuffer dest)	Deprecated, for removal: This API element is subject to removal in a future version. This method is deprecated in favor of copy(MemorySegment).
float[]	getAvatarFront(float[] dest)	Returns the unit vector pointing out of the avatar's eyes.
float[]	getAvatarPosition(float[] dest)	Returns the position of the avatar (in meters).
float[]	getAvatarTop(float[] dest)	Returns the unit vector pointing out of the top of the avatar's head.
float[]	getCameraFront(float[] dest)	Returns the unit vector pointing out of the camera.
float[]	getCameraPosition(float[] dest)	Returns the position of the camera (in meters).
float[]	getCameraTop(float[] dest)	Returns the unit vector pointing out of the top of the camera.
MumbleLink.Context	getContext()	Returns a Context object that may be used to access the additional context information.
long	getContextLength()	Returns the length of the context (in bytes) that will be used by a MumbleServer to determine whether two users can hear each other positionally.
String	getDescription()	Returns the description that may provide additional information about the game's current state.
String	getIdentity()	Returns a JSON-formatted String with additional information.
String	getName()	Returns the name of the application which updated the underlying data last.
long	getUITick()	Returns an integral identifier that is incremented every time the MumbleLink data is updated.
long	getUIVersion()	Returns the version number as specified by the MumbleLink standard.
boolean	isClosed()	Returns whether this object is invalid.
static MumbleLink	open()	Opens a MumbleLink view of the data provided by Guild Wars 2 via the MumbleLink mechanism.
static MumbleLink	open(String handle)	Opens a MumbleLink view of the data provided by Guild Wars 2 via the MumbleLink mechanism using a custom handle.
static MumbleLink	viewOf(MemorySegment segment)	Returns a MumbleLink view of the given memory segment.
static MumbleLink	viewOf(ByteBuffer buffer)	Deprecated, for removal: This API element is subject to removal in a future version. This method is deprecated in favor of viewOf(MemorySegment).

Methods inherited from class java.lang.Object

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

Field Details

BYTES

public static final int BYTES

The size of the MumbleLink buffer in bytes.

Since:

0.1.0

Method Details

open

public static MumbleLink open()

Opens a MumbleLink view of the data provided by Guild Wars 2 via the MumbleLink mechanism.

This method is shorthand for MumbleLink.open("MumbleLink");

Returns:

a MumbleLink object that may be used to read the data provided by Guild Wars 2 via the MumbleLink mechanism

Throws:

IllegalStateException - if an unexpected error occurs

Since:

0.1.0

Implementation Note:

For better performance, this implementation reuses native resources whenever possible. In practice, this means that closing a MumbleLink object might not immediately close the underlying native resources.

open

public static MumbleLink open(String handle)

Opens a MumbleLink view of the data provided by Guild Wars 2 via the MumbleLink mechanism using a custom handle.

The object returned by this method must be explicitly closed.

It is recommended to open a MumbleLink object once and keep it around for the lifetime of the application when possible.

Parameters:

handle - the handle of the shared memory which will back the view

Returns:

a MumbleLink object that may be used to read the data provided by Guild Wars 2 via the MumbleLink mechanism

Throws:

IllegalStateException - if an unexpected error occurs

Since:

1.4.0

viewOf

@Deprecated(since="3.0.0",
            forRemoval=true)
public static MumbleLink viewOf(ByteBuffer buffer)

Deprecated, for removal: This API element is subject to removal in a future version.

This method is deprecated in favor of viewOf(MemorySegment).

Returns a MumbleLink view of the given buffer.

The buffer must be a direct buffer.

Parameters:

buffer - the buffer to provide a MumbleLink view of

Returns:

a MumbleLink object that may be used to read the data provided by the given buffer in the MumbleLink format

Throws:

IllegalArgumentException - if the given buffer is not direct

Since:

1.3.0

viewOf

public static MumbleLink viewOf(MemorySegment segment)

Returns a MumbleLink view of the given memory segment.

The segment must be aligned.

Parameters:

segment - the segment to provide a MumbleLink view of

Returns:

a MumbleLink object that may be used to read the data provided by the given segment in the MumbleLink format

Throws:

IllegalArgumentException - if the given segment is not aligned

Since:

3.0.0

clear

public void clear()

Clears the underlying buffer by setting all bytes to zero.

Since:

2.2.0

API Note:

It may be useful to clear a MumbleLink instance when launching multiple Guild Wars 2 processes with the same mumble handle sequentially.

close

public void close()

Closes this resource.

This method does nothing if this view is backed by a custom buffer or if it has already been closed.

Specified by:

close in interface AutoCloseable

Since:

0.1.0

isClosed

public boolean isClosed()

Returns whether this object is invalid.

Returns:

whether this object is invalid

Since:

0.1.0

See Also:

• close()

copy

public void copy(byte[] dest)

Shorthand for copy(0, dest, 0, BYTES).

See copy(int, byte[], int, int).

Parameters:

dest - the destination array

Throws:

IllegalStateException - if this view was invalidated

IndexOutOfBoundsException - if any index is violated

NullPointerException - if dest is null

Since:

1.3.0

copy

@Deprecated(since="3.0.0",
            forRemoval=true)
public void copy(ByteBuffer dest)

Deprecated, for removal: This API element is subject to removal in a future version.

This method is deprecated in favor of copy(MemorySegment).

Shorthand for copy(0, dest, 0, BYTES).

See copy(int, ByteBuffer, int, int).

Parameters:

dest - the destination buffer

Throws:

IllegalStateException - if this view was invalidated

IndexOutOfBoundsException - if any index is violated

NullPointerException - if dest is null

Since:

1.3.0

copy

public void copy(MemorySegment dest)

Shorthand for copy(0, dest, 0, BYTES).

See copy(int, MemorySegment, int, int).

Parameters:

dest - the destination segment

Throws:

IllegalStateException - if this view was invalidated

IndexOutOfBoundsException - if any index is violated

NullPointerException - if dest is null

Since:

3.0.0

copy

public void copy(int srcOffset,
 byte[] dest,
 int destOffset,
 int length)

Copies the underlying data beginning at the specified offset, to the specified offset of the destination array.

If any of the following is true, an IndexOutOfBoundsException is thrown and the destination is not modified:

• The srcOffset argument is negative.
• The destOffset argument is negative.
• The length argument is negative.
• srcOffset + length is greater than BYTES, the length the MumbleLink buffer
• destOffset + length is greater than dest.length, the length of the destination array.

Parameters:

srcOffset - starting position in the MumbleLink buffer

dest - the destination array

destOffset - starting position in the destination data

length - the number of bytes to be copied

Throws:

IllegalStateException - if this view was invalidated

IndexOutOfBoundsException - if any index is violated

NullPointerException - if dest is null

Since:

1.3.0

copy

@Deprecated(since="3.0.0",
            forRemoval=true)
public void copy(int srcOffset,
 ByteBuffer dest,
 int destOffset,
 int length)

Deprecated, for removal: This API element is subject to removal in a future version.

This method is deprecated in favor of copy(int, MemorySegment, int, int).

Copies the underlying data beginning at the specified offset, to the specified offset of the destination buffer.

If any of the following is true, an IndexOutOfBoundsException is thrown and the destination is not modified:

• The srcOffset argument is negative.
• The destOffset argument is negative.
• The length argument is negative.
• srcOffset + length is greater than BYTES, the length the MumbleLink buffer
• destOffset + length is greater than dest.length, the length of the destination buffer.

Parameters:

srcOffset - starting position in the MumbleLink buffer

dest - the destination buffer

destOffset - starting position in the destination data

length - the number of bytes to be copied

Throws:

IllegalStateException - if this view was invalidated

IndexOutOfBoundsException - if any index is violated

NullPointerException - if dest is null

Since:

1.3.0

copy

public void copy(int srcOffset,
 MemorySegment dest,
 int destOffset,
 int length)

Copies the underlying data beginning at the specified offset, to the specified offset of the destination buffer.

If any of the following is true, an IndexOutOfBoundsException is thrown and the destination is not modified:

• The srcOffset argument is negative.
• The destOffset argument is negative.
• The length argument is negative.
• srcOffset + length is greater than BYTES, the length the MumbleLink buffer
• destOffset + length is greater than dest.length, the length of the destination buffer.

Parameters:

srcOffset - starting position in the MumbleLink buffer

dest - the destination buffer

destOffset - starting position in the destination data

length - the number of bytes to be copied

Throws:

IllegalStateException - if this view was invalidated

IndexOutOfBoundsException - if any index is violated

NullPointerException - if dest is null

Since:

3.0.0

getUIVersion

public long getUIVersion()

Returns the version number as specified by the MumbleLink standard.

This is part of the MumbleLink standard and useless to most applications.

Returns:

the version number as specified by the MumbleLink standard

Throws:

IllegalStateException - if this view was invalidated

Since:

0.1.0

getUITick

public long getUITick()

Returns an integral identifier that is incremented every time the MumbleLink data is updated.

Notes:

• At the time of writing MumbleLink data is not updated during loading screens. Thus, this identifier may be used to (roughly) detect whether game client is currently in one. (Keep in mind that is behavior might change.)

Returns:

an integral identifier that is incremented every time the MumbleLink data is updated

Throws:

IllegalStateException - if this view was invalidated

Since:

0.1.0

getAvatarPosition

public float[] getAvatarPosition(float[] dest)

Returns the position of the avatar (in meters).

Notes:

• Guild Wars 2's units correspond to inches.
• The coordinate system used by MumbleLink is left-handed.
• Due to limitations of the MumbleLink mechanism, it is possible that the underlying data is modified while reading, thus the returned position may be incorrect. (In practice, this is fairly rare and can just be ignored for the most part. Implement basic interpolation, if necessary.)

Parameters:

dest - the array to store the data in

Returns:

the dest array

Throws:

IllegalArgumentException - if dest.length != 3

IllegalStateException - if this view was invalidated

Since:

0.1.0

getAvatarFront

public float[] getAvatarFront(float[] dest)

Returns the unit vector pointing out of the avatar's eyes.

Notes:

• This is commonly referred to as "look-at-vector" in computer graphics.

Parameters:

dest - the array to store the data in

Returns:

the dest array

Throws:

IllegalArgumentException - if dest.length != 3

IllegalStateException - if this view was invalidated

Since:

0.1.0

getAvatarTop

public float[] getAvatarTop(float[] dest)

Returns the unit vector pointing out of the top of the avatar's head.

Notes:

• This is commonly referred to as "up-vector" in computer graphics.

Parameters:

dest - the array to store the data in

Returns:

the dest array

Throws:

IllegalArgumentException - if dest.length != 3

IllegalStateException - if this view was invalidated

Since:

0.1.0

getName

public String getName()

Returns the name of the application which updated the underlying data last.

Returns:

the name of the application which updated the underlying data last

Throws:

IllegalStateException - if this view was invalidated

Since:

0.1.0

API Note:

In practice this should always be "Guild Wars 2" when the game client has focus and is the owner of the link data. It is common practice to use this value to check which application is currently writing to the MumbleLink data.

getCameraPosition

public float[] getCameraPosition(float[] dest)

Returns the position of the camera (in meters).

Notes:

• Guild Wars 2's units correspond to inches.
• The coordinate system used by MumbleLink is left-handed.
• Due to limitations of the MumbleLink mechanism, it is possible that the underlying data is modified while reading, thus the returned position may be incorrect. (In practice, this is fairly rare and can just be ignored for the most part. Implement basic interpolation, if necessary.)

Parameters:

dest - the array to store the data in

Returns:

the dest array

Throws:

IllegalArgumentException - if dest.length != 3

IllegalStateException - if this view was invalidated

Since:

0.1.0

getCameraFront

public float[] getCameraFront(float[] dest)

Returns the unit vector pointing out of the camera.

Notes:

• This is commonly referred to as "look-at-vector" in computer graphics.

Parameters:

dest - the array to store the data in

Returns:

the dest array

Throws:

IllegalArgumentException - if dest.length != 3

IllegalStateException - if this view was invalidated

Since:

0.1.0

getCameraTop

public float[] getCameraTop(float[] dest)

Returns the unit vector pointing out of the top of the camera.

Notes:

• This is commonly referred to as "up-vector" in computer graphics.

Parameters:

dest - the array to store the data in

Returns:

the dest array

Throws:

IllegalArgumentException - if dest.length != 3

IllegalStateException - if this view was invalidated

Since:

0.1.0

getIdentity

public String getIdentity()

Returns a JSON-formatted String with additional information.

Returns:

a JSON-formatted String with additional information

Throws:

IllegalStateException - if this view was invalidated

Since:

0.1.0

getContextLength

public long getContextLength()

Returns the length of the context (in bytes) that will be used by a MumbleServer to determine whether two users can hear each other positionally.

Returns:

the length of the context (in bytes) that will be used by a MumbleServer to determine whether two users can hear each other positionally

Throws:

IllegalStateException - if this view was invalidated

Since:

0.1.0

getContext

public MumbleLink.Context getContext()

Returns a Context object that may be used to access the additional context information.

The returned object is strongly tied to this object and is only valid as long as this object is valid.

Returns:

a Context object that may be used to access the additional context information

Since:

0.1.0

getDescription

public String getDescription()

Returns the description that may provide additional information about the game's current state.

Returns:

the description that may provide additional information about the game's current state

Throws:

IllegalStateException - if this view was invalidated

Since:

0.1.0

API Note:

This field is currently not used by the game client.