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.



230
231
232
233
 
# File 'mixer.c', line 230

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:



428
429
430
431
432
433
 
# File 'mixer.c', line 428

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:



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

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:



448
449
450
451
452
453
 
# File 'mixer.c', line 448

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:



506
507
508
509
510
 
# File 'mixer.c', line 506

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:



409
410
411
412
413
414
 
# File 'mixer.c', line 409

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:



373
374
375
376
377
378
 
# File 'mixer.c', line 373

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) 


481
482
483
484
485
 
# File 'mixer.c', line 481

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:



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

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) 


463
464
465
466
467
 
# File 'mixer.c', line 463

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:



522
523
524
525
526
 
# File 'mixer.c', line 522

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) 


243
244
245
246
 
# File 'mixer.c', line 243

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:



391
392
393
394
395
396
 
# File 'mixer.c', line 391

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:



277
278
279
280
 
# File 'mixer.c', line 277

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:



259
260
261
262
 
# File 'mixer.c', line 259

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