Module: SDL2::Mixer::Channels

Defined in:
mixer.c,
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.



235
236
237
238
 
# File 'mixer.c', line 235

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:



433
434
435
436
437
438
 
# File 'mixer.c', line 433

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:



353
354
355
356
357
358
359
360
361
362
363
364
365
366
 
# File 'mixer.c', line 353

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:



453
454
455
456
457
458
 
# File 'mixer.c', line 453

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:



514
515
516
517
518
 
# File 'mixer.c', line 514

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:



414
415
416
417
418
419
 
# File 'mixer.c', line 414

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:



378
379
380
381
382
383
 
# File 'mixer.c', line 378

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

Returns:

  • (Boolean)

See Also:



489
490
491
492
493
 
# File 'mixer.c', line 489

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:



314
315
316
317
318
319
320
321
322
323
324
325
326
327
 
# File 'mixer.c', line 314

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

Returns:

  • (Boolean)

See Also:



470
471
472
473
474
 
# File 'mixer.c', line 470

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:



530
531
532
533
534
 
# File 'mixer.c', line 530

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) 


248
249
250
251
 
# File 'mixer.c', line 248

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:



396
397
398
399
400
401
 
# File 'mixer.c', line 396

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:



282
283
284
285
 
# File 'mixer.c', line 282

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:



264
265
266
267
 
# File 'mixer.c', line 264

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