sfml3.rb

Class: SFML::Music

Inherits:
Object
  • Object
show all
Defined in:
ext/audio/music.c,
ext/audio/music.c

Overview

Music streamed from a file, memory buffer or InputStream rather than held fully decoded in memory, so it's suited to long tracks that would be wasteful to load whole as a SoundBuffer.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.from_file(path) ⇒ Music

Creates a music stream that reads from an audio file.

Returns:

Returns:

Raises:

  • (RuntimeError) —

    if the file cannot be opened or decoded



86
87
88
 
# File 'ext/audio/music.c', line 86

static VALUE Music_from_file(VALUE klass, VALUE rb_path) {
    return Music_wrap(klass, sfMusic_createFromFile(StringValueCStr(rb_path)), Qnil);
}

.from_memory(data) ⇒ Music

Creates a music stream that reads from audio held in a String.

Returns:

Returns:

Raises:

  • (RuntimeError) —

    if data cannot be decoded



98
99
100
101
102
103
 
# File 'ext/audio/music.c', line 98

static VALUE Music_from_memory(VALUE klass, VALUE rb_data) {
    StringValue(rb_data);

    return Music_wrap(
        klass, sfMusic_createFromMemory(RSTRING_PTR(rb_data), (size_t)RSTRING_LEN(rb_data)), Qnil);
}

.from_stream(stream) ⇒ Music

Creates a music stream that reads from a custom InputStream.

Returns:

Returns:

Raises:

  • (RuntimeError) —

    if the stream cannot be decoded



113
114
115
116
117
118
 
# File 'ext/audio/music.c', line 113

static VALUE Music_from_stream(VALUE klass, VALUE rb_stream) {
    VALUE holder = Qnil;
    sfInputStream* stream = input_stream_from_rb(rb_stream, &holder);

    return Music_wrap(klass, sfMusic_createFromStream(stream), holder);
}

Instance Method Details

#attenuation ⇒ Float

Returns the distance-attenuation factor.

Returns:

  • (Float)

#attenuation=(value) ⇒ Float

Sets the distance-attenuation factor.

Returns:

  • (Float)

#channel_count ⇒ Integer

Returns the number of audio channels in the music.

Returns:

  • (Integer)

Returns:

  • (Integer) 


136
137
138
 
# File 'ext/audio/music.c', line 136

static VALUE Music_channel_count(VALUE self) {
    return UINT2NUM(sfMusic_getChannelCount(Get_Music_Struct(self)));
}

#channel_map ⇒ Array<Symbol>

Returns the channel layout of the music.

Returns:

  • (Array<Symbol>)

Returns:

  • (Array<Symbol>) —

    one entry per channel, e.g. [:front_left, :front_right]



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'ext/audio/music.c', line 157

static VALUE Music_channel_map(VALUE self) {
    size_t count = 0;
    const sfSoundChannel* map = sfMusic_getChannelMap(Get_Music_Struct(self), &count);
    VALUE rb_array;
    size_t i;

    if (map == NULL) {
        return rb_ary_new();
    }

    rb_array = rb_ary_new_capa((long)count);

    for (i = 0; i < count; i++) {
        rb_ary_push(rb_array, ID2SYM(rb_intern(sound_channel_name(map[i]))));
    }

    return rb_array;
}

#cone ⇒ SoundSourceCone

Returns the source's directional attenuation cone.

Returns:

#cone=(value) ⇒ SoundSourceCone

Sets the source's directional attenuation cone.

Returns:

#direction ⇒ Vector3

Returns the direction the source is facing.

Returns:

#direction=(value) ⇒ Vector3

Sets the direction the source is facing.

Returns:

#directional_attenuation_factor ⇒ Float

Returns the factor controlling directional attenuation.

Returns:

  • (Float)

#directional_attenuation_factor=(value) ⇒ Float

Sets the factor controlling directional attenuation.

Returns:

  • (Float)

#doppler_factor ⇒ Float

Returns the factor by which the Doppler effect is scaled.

Returns:

  • (Float)

#doppler_factor=(value) ⇒ Float

Sets the factor by which the Doppler effect is scaled.

Returns:

  • (Float)

#duration ⇒ Time

Returns the total duration of the music.

Returns:

Returns:

  • (Time) —

    total duration of the music



126
127
128
 
# File 'ext/audio/music.c', line 126

static VALUE Music_duration(VALUE self) {
    return time_to_rb(sfMusic_getDuration(Get_Music_Struct(self)));
}

#effect_processor=(proc) ⇒ Proc

Installs a Proc that post-processes this source's audio in real time.

Returns:

  • (Proc) —

    proc

#loop_points ⇒ Array, Time

Returns the loop points as an [offset, length] pair.

Returns ].

Returns:

  • (Array, Time) —

    ]

Returns:

  • (Array<Time>) —

    a two-element [offset, length] pair



184
185
186
187
188
 
# File 'ext/audio/music.c', line 184

static VALUE Music_loop_points(VALUE self) {
    sfTimeSpan span = sfMusic_getLoopPoints(Get_Music_Struct(self));

    return rb_ary_new_from_args(2, time_to_rb(span.offset), time_to_rb(span.length));
}

#loop_points=(value) ⇒ Array, Time

Sets the loop points as a two-element [offset, length] pair.

Returns ].

Returns:

  • (Array, Time) —

    ]

Returns:

  • (Array<Time>) —

    value

Raises:

  • (ArgumentError) —

    if value is not a two-element Array



198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'ext/audio/music.c', line 198

static VALUE Music_set_loop_points(VALUE self, VALUE rb_span) {
    sfTimeSpan span;

    if (!RB_TYPE_P(rb_span, T_ARRAY) || RARRAY_LEN(rb_span) != 2) {
        rb_raise(rb_eArgError, "loop points must be a two-element [offset, length] array");
    }

    span.offset = time_from_rb(rb_ary_entry(rb_span, 0));
    span.length = time_from_rb(rb_ary_entry(rb_span, 1));

    sfMusic_setLoopPoints(Get_Music_Struct(self), span);

    return rb_span;
}

#looping=(value) ⇒ Boolean

Enables or disables looping.

Returns:

  • (Boolean)

#looping? ⇒ Boolean

Returns true if playback loops back to the start on completion.

Returns:

  • (Boolean)

#max_distance ⇒ Float

Returns the maximum distance of the distance-attenuation model.

Returns:

  • (Float)

#max_distance=(value) ⇒ Float

Sets the maximum distance of the distance-attenuation model.

Returns:

  • (Float)

#max_gain ⇒ Float

Returns the maximum gain of the distance-attenuation model.

Returns:

  • (Float)

#max_gain=(value) ⇒ Float

Sets the maximum gain of the distance-attenuation model.

Returns:

  • (Float)

#min_distance ⇒ Float

Returns the minimum distance of the distance-attenuation model.

Returns:

  • (Float)

#min_distance=(value) ⇒ Float

Sets the minimum distance of the distance-attenuation model.

Returns:

  • (Float)

#min_gain ⇒ Float

Returns the minimum gain of the distance-attenuation model.

Returns:

  • (Float)

#min_gain=(value) ⇒ Float

Sets the minimum gain of the distance-attenuation model.

Returns:

  • (Float)

#pan ⇒ Float

Returns the source's stereo pan.

Returns:

  • (Float) —

    stereo pan, -1 (left) to 1 (right)

#pan=(value) ⇒ Float

Sets the source's stereo pan.

Returns:

  • (Float)

#pause ⇒ self

Pauses playback, keeping the current playing offset.

Returns:

  • (self)

#pitch ⇒ Float

Returns the pitch scaling factor.

Returns:

  • (Float)

#pitch=(value) ⇒ Float

Sets the pitch scaling factor.

Returns:

  • (Float)

#play ⇒ self

Starts playback, or resumes it when paused.

Returns:

  • (self)

#playing_offset ⇒ Time

Returns the current playing offset.

Returns:

#playing_offset=(value) ⇒ Time

Seeks to the given playing offset.

Returns:

#position ⇒ Vector3

Returns the source's position in 3D space.

Returns:

#position=(value) ⇒ Vector3

Sets the source's position in 3D space.

Returns:

#relative_to_listener=(value) ⇒ Boolean

Makes the source relative to, or independent of, the listener.

Returns:

  • (Boolean)

#relative_to_listener? ⇒ Boolean

Returns true if the source is positioned relative to the listener.

Returns:

  • (Boolean)

#sample_rate ⇒ Integer

Returns the music's sample rate in samples per second.

Returns:

  • (Integer)

Returns:

  • (Integer) 


146
147
148
 
# File 'ext/audio/music.c', line 146

static VALUE Music_sample_rate(VALUE self) {
    return UINT2NUM(sfMusic_getSampleRate(Get_Music_Struct(self)));
}

#spatialization_enabled=(value) ⇒ Boolean

Enables or disables 3D spatialization.

Returns:

  • (Boolean)

#spatialization_enabled? ⇒ Boolean

Returns true if 3D spatialization is enabled.

Returns:

  • (Boolean)

#status ⇒ Symbol

Returns the current playback status.

Returns:

  • (Symbol) —

    one of :stopped, :paused, :playing

#stop ⇒ self

Stops playback and rewinds to the beginning. May briefly block the calling thread if an audio-thread callback for this source is in flight.

Returns:

  • (self)

#velocity ⇒ Vector3

Returns the source's velocity, used for Doppler calculations.

Returns:

#velocity=(value) ⇒ Vector3

Sets the source's velocity for Doppler calculations.

Returns:

#volume ⇒ Float

Returns the source's volume.

Returns:

  • (Float) —

    0 to 100

#volume=(value) ⇒ Float

Sets the source's volume.

Returns:

  • (Float)