libsswf: sswf::SoundInfo Class Reference

# sswf::SoundInfo Class Reference

Information about out to playback a sound effect. More...

`#include <libsswf.h>`

Inheritance diagram for sswf::SoundInfo:

List of all members.

## Public Member Functions
void | AddEnvelope (const Envelope &envelope)
| This function adds one Envelope to the SoundInfo object.
void | NoMultiple (bool no_multiple=true)
| Whether the referenced sound can be played multiple times in parallel.
ErrorManager::error_code_t | PreSave (void)
| Makes sure that the sound identifier was defined.
void | Save (Data &data) const
| Save the information in the specified Data buffer.
void | SetLoop (unsigned short loop)
| Set the number of times a sound shall be played.
void | SetRange (unsigned long start, unsigned long end)
| The start and end points to playback.
void | SetSoundID (sswf_id_t id)
| Set the reference to the sound to playback.
| SoundInfo (ErrorManager &error_manager)
| Initializes a sound information class.
void | StopSound (bool stop=true)
| Whether this SoundInfo is used to stop a sound.
## Private Attributes
unsigned long | f_end_position
Vectors | f_envelopes
ErrorManager & | f_error_manager
unsigned short | f_loop
bool | f_no_multiple
sswf_id_t | f_sound_id
unsigned long | f_start_position
bool | f_stop

## Detailed Description

A SoundInfo object defines how to playback a sound effect. In general, you play a sound effect from start to finish once. The sound info lets you have a large sound effect and only play a portion of it with different volume information (i.e. envelope)

A SoundInfo object is set in a TagStartSound object.

Warning:
  The volume goes from 0 to 32768. Larger values have an undefined result.

Bug:
  This object does not accept 0 as a sound object identifier. No object should have its identifier set to zero anyway.

See also:
  sswf::Envelope

  sswf::TagStartSound

  SWF Alexis' Reference—swf_soundinfo

## Constructor & Destructor Documentation

SoundInfo::SoundInfo | ( | ErrorManager & | error_manager | ) |

This constructor resets the SoundInfo object to defaults:

Stop the sound, the sound effect cannot be played more than once, the start and end position are 0 and end of the sound effect respectively, it loops just once and there is no envelopes by default.

Parameters:

  `[in]` | error_manager | A pointer to your TagHeader (i.e. it is the error manager!)

See also:
  sswf::Envelope

References f_end_position, f_loop, f_no_multiple, f_sound_id, f_start_position, and f_stop.

## Member Function Documentation

void SoundInfo::AddEnvelope | ( | const Envelope & | envelope | ) |

This function accepts an envelope to add to the SoundInfo.

The Envelope can be used to fade a sound in or out.

Note that a SoundInfo is limited to a maximum of 255 envelopes.

The input Envelope is duplicated in the SoundInfo.

Note that the new envelope is placed where it needs to be so as to be properly ordered by position (since version 1.8.1--in previous versions, additional envelopes would be appended so they had to be added in order.)

Parameters:

  `[in]` | envelope | The envelope to add

References sswf::Vectors::Count(), sswf::ErrorManager::ERROR_CODE_ENVELOPE_EXISTS, sswf::ErrorManager::ERROR_CODE_ENVELOPE_OVERFLOW, f_envelopes, f_error_manager, sswf::Vectors::Get(), sswf::MemoryManager::MemAttach(), sswf::ErrorManager::OnError(), sswf::Envelope::Position(), and sswf::Vectors::Set().

void SoundInfo::NoMultiple | ( | bool | no_multiple = `true` | ) |

This flag is used to determine whether the referenced sound can be played multiple times in parallel. In general, this flag is set to true but the default is false.

Parameters:

  `[in]` | no_multiple | Whether multiple instances will play in parallel

References f_no_multiple.

ErrorManager::error_code_t SoundInfo::PreSave | ( | void |  | ) |

This function ensures that:

- The sound identifier was set to a valid sound identifier;
- The loop counter is not zero;
- The start position is before the end position.

Returns:
  ErrorManager::ERROR_CODE_NONE or some other ErrorManager::error_code_t

References sswf::ErrorManager::ERROR_CODE_EMPTY_POSITION_RANGE, sswf::ErrorManager::ERROR_CODE_INVALID_IDENTIFIER, sswf::ErrorManager::ERROR_CODE_LOOP_ZERO, sswf::ErrorManager::ERROR_CODE_NONE, f_end_position, f_error_manager, f_loop, f_sound_id, f_start_position, f_stop, and sswf::ErrorManager::OnError().

Referenced by sswf::TagStartSound::PreSave().

void SoundInfo::Save | ( | Data & | data | ) | const

This function saves the SoundInfo parameters in the specified Data buffer.

Parameters:

  `[in,out]` | data | The buffer where the tag is saved

References sswf::Vectors::Count(), f_end_position, f_envelopes, f_loop, f_no_multiple, f_sound_id, f_start_position, f_stop, sswf::Vectors::Get(), sswf::Data::PutByte(), sswf::Data::PutLong(), sswf::Data::PutShort(), and sswf::Data::WriteBits().

Referenced by sswf::TagStartSound::Save().

void SoundInfo::SetLoop | ( | unsigned short | loop | ) |

This function changes the number of time a sound effect will be repeated. By default a sound effect is played just once.

Bug:
  The loop parameter cannot be set to zero.

Parameters:

  `[in]` | loop | The number of times the sound effect shall be played

References sswf::ErrorManager::ERROR_CODE_LOOP_ZERO, f_error_manager, f_loop, and sswf::ErrorManager::OnError().

void SoundInfo::SetRange | ( | unsigned long | start,
|  | unsigned long | end |
| ) |  |  |

The SoundInfo can be used to play only a small portion of a sound effect. This function can be used to define the start and end points in the sound samples.

The start parameter must be small than the end parameter unless one or the other is set to zero. (i.e. zero represents the default; for the start zero is zero and for the end zero represents the total number of samples of the referenced sound tag.)

The position is defined in number of samples. So when set to 1 with stereo 16 bits sample, the sound starts playing at byte offset 4.

Parameters:

  `[in]` | start | The start position
  `[in]` | end | The end position

References sswf::ErrorManager::ERROR_CODE_EMPTY_POSITION_RANGE, f_end_position, f_error_manager, f_start_position, and sswf::ErrorManager::OnError().

void SoundInfo::SetSoundID | ( | sswf_id_t | id | ) |

This function must be called with a valid identifier (i.e. an identifier to a sound effect object.)

The default value (0) is not valid. Thus you have to call this function at least once.

Parameters:

  `[in]` | id | The identifier of the corresponding TagSound

References sswf::ErrorManager::ERROR_CODE_INVALID_IDENTIFIER, f_error_manager, f_sound_id, and sswf::ErrorManager::OnError().

void SoundInfo::StopSound | ( | bool | stop = `true` | ) |

This function is used to mark a SoundInfo entry as a "Stop Button" (true) or a "Start Button" (false.)

When a sound is marked to be stopped (default), then the other parameters (except the sound identifier) are ignored.

Parameters:

  `[in]` | stop | If true, stop the sound.

References f_stop.

## Member Data Documentation

unsigned long sswf::SoundInfo::f_end_position`[private]`

Referenced by PreSave(), Save(), SetRange(), and SoundInfo().

Vectors sswf::SoundInfo::f_envelopes`[private]`

Referenced by AddEnvelope(), and Save().

ErrorManager& sswf::SoundInfo::f_error_manager`[private]`

Referenced by AddEnvelope(), PreSave(), SetLoop(), SetRange(), and SetSoundID().

unsigned short sswf::SoundInfo::f_loop`[private]`

Referenced by PreSave(), Save(), SetLoop(), and SoundInfo().

bool sswf::SoundInfo::f_no_multiple`[private]`

Referenced by NoMultiple(), Save(), and SoundInfo().

sswf_id_t sswf::SoundInfo::f_sound_id`[private]`

Referenced by PreSave(), Save(), SetSoundID(), and SoundInfo().

unsigned long sswf::SoundInfo::f_start_position`[private]`

Referenced by PreSave(), Save(), SetRange(), and SoundInfo().

bool sswf::SoundInfo::f_stop`[private]`

Referenced by PreSave(), Save(), SoundInfo(), and StopSound().

The documentation for this class was generated from the following files:

- libsswf.h
- libsswf_tag_sound.c++