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:

  • 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:

    • 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.