Class: Seal::Listener

Inherits:

Object

• Object
• Seal::Listener

Defined in:

src/rubyext.c,
src/rubyext.c

Overview

Interfaces for manipulating the listener singleton object. The listener object abstractly represents the main object in a sound application which “hears” all the sound. For example, the listener object can be used to represent the main character moving around on the map in a role-playing game. The properties of the listener (position, velocity, etc.) combined with those of the existing sources determine how the sound should be rendered.

Instance Method Summary

• #listener.gain ⇒ Object

  Gets the gain of the listener.

• #listener.gain( = flt) ⇒ Array

  Sets the master scalar amplitude multiplier of the listener which applies to all the sources.

• #move ⇒ Object

  Moves the listener (changes the position) based on the source velocity.

• #listener.orientation ⇒ Array

  Gets the orientation of the listener.

• #orientation=(rarr) ⇒ Object

  Sets the orientation of the listener.

• #listener.position ⇒ Array

  Gets the position of the listener.

• #listener.position( = [flt, flt, flt]) ⇒ Array

  Sets the position of the listener in a right-handed Cartesian coordinate system.

• #listener.velocity ⇒ Array

  Gets the velocity of the listener.

• #listener.velocity( = flt, flt, flt) ⇒ Array

  Sets the velocity of the listener in a right-handed Cartesian coordinate system.

Instance Method Details

#listener.gain ⇒ Object

Gets the gain of the listener. The default is 1.0.

# File 'src/rubyext.c', line 1746

static
VALUE
get_listener_gain(VALUE rlistener, VALUE value)
{
    return get_listener_float(seal_get_listener_gain);
}

#listener.gain( = flt) ⇒ Array

Sets the master scalar amplitude multiplier of the listener which applies to all the sources. 1.0 means that the sound is unattenuated; 0.5 means an attenuation of 6 dB; 0.0 means silence. The valid range is [0.0, +inf.).

Returns:

• (Array)

# File 'src/rubyext.c', line 1733

static
VALUE
set_listener_gain(VALUE rlistener, VALUE value)
{
    return set_listener_float(value, seal_set_listener_gain);
}

#move ⇒ Object

Moves the listener (changes the position) based on the source velocity. This is a syntactic sugar for adding the velocity vector and position vector. See Source#move.

# File 'src/rubyext.c', line 1716

static
VALUE
move_listener(VALUE rlistener)
{
    check_seal_err(seal_move_listener());

    return rlistener;
}

#listener.orientation ⇒ Array

Gets the orientation of the listener. The default is ((0.0, 0.0, -1.0), (0.0, 1.0, 0.0)).

Examples:

# at references the `at' vector [flt, flt, flt]
# up references the `up' vector [flt, flt, flt]
at, up = Seal.listener.orientation
# at_x references the x component of the `at' vector
# ...
# up_z references the z component of the `up' vector
(at_x, at_y, ay_z), (up_x, up_y, up_z) = Seal.listener.orientation

Returns:

• (Array, Array)

# File 'src/rubyext.c', line 1851

static
VALUE
get_listener_orien(VALUE rlistener)
{
    float tuple[6];
    VALUE rtuple[6];
    VALUE orien[2];

    check_seal_err(seal_get_listener_orien(tuple));
    convert_bulk_float(rtuple, tuple, 6);
    orien[0] = rb_ary_new4(3, rtuple);
    orien[1] = rb_ary_new4(3, rtuple + 3);

    return rb_ary_new4(2, orien);
}

#listener.orientation( = [flt, flt, flt], [flt, flt, flt]) ⇒ Object #- ⇒ Object

Sets the orientation of the listener. The argument must be a pair of 3-tuple consisting of an ‘at’ vector and an ‘up’ vector, where the ‘at’ vector represents the ‘forward’ direction of the listener and the ‘up’ vector represents the ‘up’ direction for the listener. These two vectors must be linearly independent, must not be NaN and must not be normalized. Otherwise, the operation is undefined.

# File 'src/rubyext.c', line 1821

static
VALUE
set_listener_orien(VALUE rlistener, VALUE rarr)
{
    float orien[6];

    rarr = rb_convert_type(rarr, T_ARRAY, "Array", "to_a");
    extract_3float(rb_ary_entry(rarr, 0), orien, orien + 1, orien + 2);
    extract_3float(rb_ary_entry(rarr, 1), orien + 3, orien + 4, orien + 5);
    check_seal_err(seal_set_listener_orien(orien));

    return rarr;
}

#listener.position ⇒ Array

Gets the position of the listener. The default is ( 0.0, 0.0, 0.0 ).

Returns:

• (Array)

# File 'src/rubyext.c', line 1773

static
VALUE
get_listener_pos(VALUE rlistener, VALUE value)
{
    return get_listener_3float(seal_get_listener_pos);
}

#listener.position( = [flt, flt, flt]) ⇒ Array

Sets the position of the listener in a right-handed Cartesian coordinate system. Use of NaN and infinity is undefined.

Returns:

• (Array)

# File 'src/rubyext.c', line 1760

static
VALUE
set_listener_pos(VALUE rlistener, VALUE value)
{
    return set_listener_3float(value, seal_set_listener_pos);
}

#listener.velocity ⇒ Array

Gets the velocity of the listener. The default is ( 0.0, 0.0, 0.0 ).

Returns:

• (Array)

# File 'src/rubyext.c', line 1802

static
VALUE
get_listener_vel(VALUE rlistener, VALUE value)
{
    return get_listener_3float(seal_get_listener_vel);
}

#listener.velocity( = flt, flt, flt) ⇒ Array

Sets the velocity of the listener in a right-handed Cartesian coordinate system. The velocity of the listener does not affect its position but is a factor used during the Doppler effect emulation.

Returns:

• (Array)

# File 'src/rubyext.c', line 1788

static
VALUE
set_listener_vel(VALUE rlistener, VALUE value)
{
    return set_listener_3float(value, seal_set_listener_vel);
}