Eiffel Media API
Overview Cluster Class Classes Index      Previous Next      Top Features

em.audio

Class EM_CHANNEL


Direct ancestors

EM_SHARED_ERROR_HANDLER, EM_SHARED_AUDIO_FACTORY, EM_AUDIO_CONSTANTS, SDL_MIXER_FUNCTIONS_EXTERNAL

Creation

Features

Invariants

indexing

description

Implements channels for use with audio mixer.

Use this class to play and pause sound files {EM_SOUND}.
You may also apply effects and do other manipulations.

Note: Whenever possible, don't create channels on your own.
Use {EM_CHANNELS}.extend instead, as channel numbering
must stay unique.

Fading is blocking as your application may crash if
closed while fading in or out.

date

$Date: 2005/10/22 13:22:42 $

revision

$Revision: 1.33 $

class

EM_CHANNEL

create

make (a_channel_volume: like volume; a_channel_number: like number)

-- Initalize channel with a_channel_volume and a_channel_number.

require
volume_in_range: 0 <= a_channel_volume and then a_channel_volume <= Em_max_volume
channel_number_positiv: a_channel_number > 0
ensure
number_set: number = a_channel_number
internal_number_set: internal_number = a_channel_number - 1
volume_set: volume = a_channel_volume

feature -- Access

current_sound: EM_SOUND

-- Last played (or still playing) sound sample on this channel
--
-- Note: Current sound may have been freed, so this pointer may not be valid anymore.
-- Sound chunk returned has no filename as created from pointer.

ensure
Result_set: Result = audio_factory.last_sound
effects: EM_EFFECTS

-- All applied effects to this channel

has_reversed_stereo: BOOLEAN

-- Is stereo reversed?

is_fading: BOOLEAN

-- Is channel fading in or out?

is_fading_in: BOOLEAN

-- Is channel fading in?

is_fading_out: BOOLEAN

-- Is channel fading out?

is_mute: BOOLEAN

-- is channel mute?

is_paused: BOOLEAN

-- Is channel paused?
--
-- Attention: If channel was halted after pausing, channel is still paused.

is_playing: BOOLEAN

-- Is channel playing?
--
-- Attention: A paused channel is also playing!

number: INTEGER

-- Current channel number

ensure
Result_set: Result = internal_number + 1
volume: INTEGER

-- Current channel volume

feature -- Setters

set_distance (a_distance: INTEGER)

-- Set a distance factor for this channel.
-- Distance range is [0..255].
--
-- Set a_distance to 0 to disable effect.

require
distance_valid: a_distance >= 0 and then a_distance <= 255
set_number (a_number: like number)

-- Set a number for the channel.
--
-- Note: Only use, if you know what you're doing.

require
number_positiv: a_number >= 0
ensure
internal_number_set: internal_number = a_number - 1
number_set: number = a_number
set_panning (left_volume: INTEGER; right_volume: INTEGER)

-- Set panning for this channel.
-- Volume range for both sides is [0..255].
--
-- Set left_volume and right_volume to 255 to disable panning.

require
left_volume_valid: left_volume >= 0 and then left_volume <= 255
right_volume_valid: right_volume >= 0 and then right_volume <= 255
set_position (an_angle: INTEGER; a_distance: INTEGER)

-- Set a postion with an_angle and a_distance for the channel.
-- Range of an_angle is [0..360] and range of a_distance is [0..255].
--
-- Values for `an_angle
: 0 = directly in front of you.
-- 90 = directly to your right.
-- 180 = directly behind you.
-- 270 = directly to your left.
--
-- Set an_angle and a_distance to 0 to disable positioning.

require
distance_valid: a_distance >= 0 and then a_distance <= 255
angle_valid: an_angle >= 0 and then an_angle <= 360
set_volume (a_channel_volume: like volume)

-- Set volume in range [0, Em_max_volume] of this channel.

require
volume_in_range: 0 <= a_channel_volume and then a_channel_volume <= Em_max_volume
ensure
volume_set: volume = a_channel_volume
toggle_mute

-- Mute or unmute channel based on is_mute.

ensure
toggled_mute: is_mute = not old is_mute
toggle_reverse_stereo

-- Reverse stereo for the channel according to has_reversed_stereo.

ensure
toggled_stereo: has_reversed_stereo = not old has_reversed_stereo

feature -- Effects

register_effect (an_effect: EM_EFFECT; an_argument: POINTER)

-- Apply an_effect to this channel.
-- Pass in an_argument if the effect uses some userparameters.
--
-- The effect will be added into effects for easy accessing.

require
effect_not_void: an_effect /= Void
ensure
effect_added: effects.count = old effects.count + 1
unregister_all_effects

-- Removes all registered effects.

ensure
effect_removed: effects.count = 0
unregister_effect (an_effect: EM_EFFECT)

-- Remove all effects corresponding to an_effect from the effect list.

require
effect_not_void: an_effect /= Void
ensure
effect_removed: effects.count < old effects.count

feature -- Playing

fade_in (a_sound: EM_SOUND; a_loop_count: INTEGER; a_duration: INTEGER)

-- Play a_sound for a_loop_count times with a fade in effect of
-- length a_duration milliseconds.
--
-- Passing in -1 for a_loop_count will loop infinite times.
-- Any other value will play the sample a_loop_count + 1 times.
--
-- Attention: This function is non-blocking.
-- Please check if the channel is fading before
-- you quit your application.

require
valid_duration: a_duration >= 0
sound_not_void: a_sound /= Void
fade_in_timed (a_sound: EM_SOUND; a_loop_count: INTEGER; a_duration: INTEGER; a_tick_count: INTEGER)

-- Play a_sound for a_loop_count times with a fade in effect of
-- length a_duration milliseconds and maximum time of a_tick_count
-- milliseconds.
--
-- Passing in -1 a_loop_count will loop infinite times.
-- Any other value will play the sample a_loop_count + 1 times.
--
-- Passing in -1 for a_tick_count will play sound forever.
--
-- Attention: This function is non-blocking.
-- Please check if the channel is fading before
-- you quit your application.

require
valid_duration: a_duration >= 0
sound_not_void: a_sound /= Void
play (a_sound: EM_SOUND; a_loop_count: INTEGER)

-- Play a_sound for a_loop_count times on this channel.
--
-- Passing in -1 for a_loop_count will loop infinite times.
-- Any other value will play the sample a_loop_count + 1 times.

require
sound_not_void: a_sound /= Void
play_timed (a_sound: EM_SOUND; a_loop_count: INTEGER; a_tick_count: INTEGER)

-- Play a_sound for a_loop_count times on this channel for a maximum
-- of a_tick_count milliseconds.
--
-- Passing in -1 for a_loop_count will loop infinite times.
-- Any other value will play the sample a_loop_count + 1 times.
--
-- Passing in -1 for a_tick_count will play sound forever.

require
sound_not_void: a_sound /= Void

feature -- Pausing

pause

-- Pause channel if actively playing.

require
is_playing: is_playing
ensure
is_paused: is_paused
resume

-- Resume paused channel.

require
is_paused: is_paused
ensure
is_playing: is_playing

feature -- Stopping

expire (a_tick_count: INTEGER)

-- Halt channel after a_tick_count milliseconds.

require
valid_tick_count: a_tick_count >= 0
fade_out (a_duration: INTEGER)

-- Stop playing channel after fade out of a_duration milliseconds.
--
-- Attention: This function is non-blocking.
-- Please check if the channel is fading before
-- you quit your application.

require
valid_duration: a_duration >= 0
stop

-- Stop playing channel.

require
not_stopped: is_paused or else is_playing
ensure
stopped: not (is_paused or else is_playing or else is_fading)

feature -- Default constants

em_max_volume: INTEGER

-- Maximum value for any volume setting.

-- (From EM_AUDIO_CONSTANTS)

invariant

number_is_positiv: internal_number >= 0
effects_created: effects /= Void

-- From ANY
reflexive_equality: standard_is_equal (Current)
reflexive_conformance: conforms_to (Current)

end