Class: Seal::Listener

Inherits:
Object
  • Object
show all
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 (collapse)

Instance Method Details

- (Object) listener.gain

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



1746
1747
1748
1749
1750
1751
 
# File 'src/rubyext.c', line 1746

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

- (Array) listener.gain( = flt)

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) 


1733
1734
1735
1736
1737
1738
 
# File 'src/rubyext.c', line 1733

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

- (Object) move

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.



1716
1717
1718
1719
1720
1721
1722
1723
 
# File 'src/rubyext.c', line 1716

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

    return rlistener;
}

- (Array) listener.orientation

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) 


1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
 
# 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);
}

- (Object) listener.orientation( = [flt, flt, flt], [flt, flt, flt]) - (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.



1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
 
# 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;
}

- (Array) listener.position

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

Returns:

  • (Array) 


1773
1774
1775
1776
1777
1778
 
# File 'src/rubyext.c', line 1773

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

- (Array) listener.position( = [flt, flt, flt])

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

Returns:

  • (Array) 


1760
1761
1762
1763
1764
1765
 
# File 'src/rubyext.c', line 1760

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

- (Array) listener.velocity

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

Returns:

  • (Array) 


1802
1803
1804
1805
1806
1807
 
# File 'src/rubyext.c', line 1802

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

- (Array) listener.velocity( = flt, flt, flt)

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) 


1788
1789
1790
1791
1792
1793
 
# File 'src/rubyext.c', line 1788

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