Module: SDL2::Mixer::Channels

Defined in:
ext/sdl2_ext/mixer.c,
ext/sdl2_ext/mixer.c

Overview

This module plays Chunk objects in parallel.

Each virtual sound output device is called channel, and the number of channels determines the f

Defined Under Namespace

Classes: Group

Class Method Summary collapse

Class Method Details

.allocate(num_channels) ⇒ Integer

Set the number of channels being mixed.

Parameters:

  • num_channels (Integer) —

    Number of channels prepared for mixing.

Returns:

  • (Integer) —

    the number of prepared channels.



229
230
231
232
 
# File 'ext/sdl2_ext/mixer.c', line 229

static VALUE Channels_s_allocate(VALUE self, VALUE num_channels)
{
    return INT2NUM(Mix_AllocateChannels(NUM2INT(num_channels)));
}

.expire(channel, ticks) ⇒ nil

Halt playing of a specified channel after ticks milliseconds.

Parameters:

  • channel (Integer) —

    the channel to be halted, or -1 for all channels.

  • ticks (Integer) —

    milliseconds untils the channel halts playback.

Returns:

  • (nil)

See Also:



427
428
429
430
431
432
 
# File 'ext/sdl2_ext/mixer.c', line 427

static VALUE Channels_s_expire(VALUE self, VALUE channel, VALUE ticks)
{
    check_channel(channel, 1);
    Mix_ExpireChannel(NUM2INT(channel), NUM2INT(ticks));
    return Qnil;
}

.fade_in(channel, chunk, loops, ms, ticks = -1) ⇒ Integer

Play a SDL2::Mixer::Chunk on channel with fading in.

Parameters:

  • channel (Integer) —

    the channel to play, or -1 for the first free unreserved channel

  • chunk (SDL2::Mixer::Chunk) —

    the chunk to play

  • loops (Integer) —

    the number of loops, or -1 for infite loops. passing 1 plays the sample twice (1 loop).

  • ms (Integer) —

    milliseconds of time of fade-in effect.

  • ticks (Integer) (defaults to: -1) —

    milliseconds limit to play, at most. If the chunk is long enough and loops is large enough, the play will stop after ticks milliseconds. Otherwise, the play will stop when the loop ends. -1 means infinity.

Returns:

  • (Integer) —

    the channel that plays the chunk.

Raises:

  • (SDL2::Error) —

    raised on a playing error. For example, channel is out of the allocated channels, or there is no free channels when channel is -1.

See Also:



347
348
349
350
351
352
353
354
355
356
357
358
359
360
 
# File 'ext/sdl2_ext/mixer.c', line 347

static VALUE Channels_s_fade_in(int argc, VALUE* argv, VALUE self)
{
    VALUE channel, chunk, loops, ms, ticks;
    int ch;
    rb_scan_args(argc, argv, "41", &channel, &chunk, &loops, &ms, &ticks);
    if (ticks == Qnil)
        ticks = INT2FIX(-1);
    check_channel(channel, 1);
    ch = Mix_FadeInChannelTimed(NUM2INT(channel), Get_Mix_Chunk(chunk),
                                NUM2INT(loops), NUM2INT(ms), NUM2INT(ticks));
    HANDLE_MIX_ERROR(ch);
    protect_playing_chunk_from_gc(ch, chunk);
    return INT2FIX(ch);
}

.fade_out(channel, ms) ⇒ nil

Halt playing of a specified channel with fade-out effect.

Parameters:

  • channel (Integer) —

    the channel to be halted, or -1 for all channels.

  • ms (Integer) —

    milliseconds of fade-out effect

Returns:

  • (nil)

See Also:



447
448
449
450
451
452
 
# File 'ext/sdl2_ext/mixer.c', line 447

static VALUE Channels_s_fade_out(VALUE self, VALUE channel, VALUE ms)
{
    check_channel(channel, 1);
    Mix_FadeOutChannel(NUM2INT(channel), NUM2INT(ms));
    return Qnil;
}

.fading(channel) ⇒ Integer

Return the fading state of a specified channel.

The return value is one of the following:

Parameters:

  • channel (Integer) —

    channel to test

Returns:

  • (Integer)

See Also:



505
506
507
508
509
 
# File 'ext/sdl2_ext/mixer.c', line 505

static VALUE Channels_s_fading(VALUE self, VALUE which)
{
    check_channel(which, 0);
    return INT2FIX(Mix_FadingChannel(NUM2INT(which)));
}

.halt(channel) ⇒ nil

Halt playing of a specified channel.

Parameters:

  • channel (Integer) —

    the channel to be halted, or -1 for all channels.

Returns:

  • (nil)

See Also:



408
409
410
411
412
413
 
# File 'ext/sdl2_ext/mixer.c', line 408

static VALUE Channels_s_halt(VALUE self, VALUE channel)
{
    check_channel(channel, 1);
    Mix_HaltChannel(NUM2INT(channel));
    return Qnil;
}

.pause(channel) ⇒ nil

Pause a specified channel.

Parameters:

  • channel (Integer) —

    the channel to pause, or -1 for all channels.

Returns:

  • (nil)

See Also:



372
373
374
375
376
377
 
# File 'ext/sdl2_ext/mixer.c', line 372

static VALUE Channels_s_pause(VALUE self, VALUE channel)
{
    check_channel(channel, 1);
    Mix_Pause(NUM2INT(channel));
    return Qnil;
}

.pause?(channel) ⇒ Boolean

Note:

This method returns true if a paused channel is halted by halt, or any other halting methods.

Return true if a specified channel is paused.

Parameters:

  • channel (Integer) —

    channel to test

See Also:

Returns:

  • (Boolean) 


480
481
482
483
484
 
# File 'ext/sdl2_ext/mixer.c', line 480

static VALUE Channels_s_pause_p(VALUE self, VALUE channel)
{
    check_channel(channel, 0);
    return INT2BOOL(Mix_Paused(NUM2INT(channel)));
}

.play(channel, chunk, loops, ticks = -1) ⇒ Integer

Play a SDL2::Mixer::Chunk on channel.

Parameters:

  • channel (Integer) —

    the channel to play, or -1 for the first free unreserved channel

  • chunk (SDL2::Mixer::Chunk) —

    the chunk to play

  • loops (Integer) —

    the number of loops, or -1 for infite loops. passing 1 plays the sample twice (1 loop).

  • ticks (Integer) (defaults to: -1) —

    milliseconds limit to play, at most. If the chunk is long enough and loops is large enough, the play will stop after ticks milliseconds. Otherwise, the play will stop when the loop ends. -1 means infinity.

Returns:

  • (Integer) —

    the channel that plays the chunk.

Raises:

  • (SDL2::Error) —

    raised on a playing error. For example, channel is out of the allocated channels, or there is no free channels when channel is -1.

See Also:



308
309
310
311
312
313
314
315
316
317
318
319
320
321
 
# File 'ext/sdl2_ext/mixer.c', line 308

static VALUE Channels_s_play(int argc, VALUE* argv, VALUE self)
{
    VALUE channel, chunk, loops, ticks;
    int ch;
    rb_scan_args(argc, argv, "31", &channel, &chunk, &loops, &ticks);
    if (ticks == Qnil)
        ticks = INT2FIX(-1);
    check_channel(channel, 1);
    ch = Mix_PlayChannelTimed(NUM2INT(channel), Get_Mix_Chunk(chunk),
                              NUM2INT(loops), NUM2INT(ticks));
    HANDLE_MIX_ERROR(ch);
    protect_playing_chunk_from_gc(ch, chunk);
    return INT2FIX(ch);
}

.play?(channel) ⇒ Boolean

Return true if a specified channel is playing.

Parameters:

  • channel (Integer) —

    channel to test

See Also:

Returns:

  • (Boolean) 


462
463
464
465
466
 
# File 'ext/sdl2_ext/mixer.c', line 462

static VALUE Channels_s_play_p(VALUE self, VALUE channel)
{
    check_channel(channel, 0);
    return INT2BOOL(Mix_Playing(NUM2INT(channel)));
}

.playing_chunk(channel) ⇒ SDL2::Mixer::Chunk?

Get the SDL2::Mixer::Chunk object most recently playing on channel.

If channel is out of allocated channels, or no chunk is played yet on channel, this method returns nil.

Parameters:

  • channel (Integer) —

    the channel to get the chunk object

Returns:



521
522
523
524
525
 
# File 'ext/sdl2_ext/mixer.c', line 521

static VALUE Channels_s_playing_chunk(VALUE self, VALUE channel)
{
    check_channel(channel, 0);
    return rb_ary_entry(playing_chunks, NUM2INT(channel));
}

.reserve(num) ⇒ Integer

Reserve channel from 0 to num-1 and reserved channels are not used by play and fade_in with channels==-1.

Parameters:

  • num (Integer)

Returns:

  • (Integer) 


242
243
244
245
 
# File 'ext/sdl2_ext/mixer.c', line 242

static VALUE Channels_s_reserve(VALUE self, VALUE num)
{
    return INT2NUM(Mix_ReserveChannels(NUM2INT(num)));
}

.resume(channel) ⇒ nil

Note:

This method has no effect to unpaused channels.

Resume a specified channel that already pauses.

Parameters:

  • channel (Integer) —

    the channel to be resumed, or -1 for all channels.

Returns:

  • (nil)

See Also:



390
391
392
393
394
395
 
# File 'ext/sdl2_ext/mixer.c', line 390

static VALUE Channels_s_resume(VALUE self, VALUE channel)
{
    check_channel(channel, 1);
    Mix_Resume(NUM2INT(channel));
    return Qnil;
}

.set_volume(channel, volume) ⇒ void

This method returns an undefined value.

Set the volume of specified channel.

The volume should be from 0 to MAX_VOLUME(128). If the specified channel is -1, set volume for all channels.

Parameters:

  • channel (Integer) —

    the channel to set volume for.

  • volume (Integer) —

    the volume to use

See Also:



276
277
278
279
 
# File 'ext/sdl2_ext/mixer.c', line 276

static VALUE Channels_s_set_volume(VALUE self, VALUE channel, VALUE volume)
{
    return INT2NUM(Mix_Volume(NUM2INT(channel), NUM2INT(volume)));
}

.volume(channel) ⇒ Integer

Get the volume of specified channel.

Parameters:

  • channel (Integer) —

    the channel to get volume for. If the specified channel is -1, this method returns the average volume of all channels.

Returns:

  • (Integer) —

    the volume, 0-128

See Also:



258
259
260
261
 
# File 'ext/sdl2_ext/mixer.c', line 258

static VALUE Channels_s_volume(VALUE self, VALUE channel)
{
    return INT2NUM(Mix_Volume(NUM2INT(channel), -1));
}