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));
}