MusStartEffect2()

Start a sound effect, with parameters.

Syntax

  musHandle MusStartEffect2(int number, int volume, int pan, int overwrite, int priority);

Arguments

• number is the sound effect number

• volume is the volume scale

• pan is the pan scale

• overwrite overwrites sound effects of the same number

• priority is the priority level

Explanation
Start a sound effect with control parameters. This function will start a sound effect allowing the programmer to specify volume and pan scale values, flag the channel allocation function to overwrite sound effects of the same number and specify a priority value.

The sound effect started will use the default sound effect bank unless an override has been set with the MusFxBankSetSingle() function. If a sound effect bank override has been specified, this function will use it and then clear the override.

The sound effect started will use the default sample bank unless an override is defined in the sound effect bank with the MusFxBankSetPtrBank() function or set with the higher priority sample bank override function MusPtrBankSetSingle(). If a sample bank override has been set using the MusPtrBankSetSingle() function, this function will use it and then clear the override.

The number is a value in the range of 0 to the number of sound effects stored in the sound effect bank. The number of available sound effects can be found by using the MusFxBankNumberOfEffects() function. Currently, a list of "#defines" is located in the header file associated with the sound effect bank, which can be included by the programmer to allow access to the sound effects by name rather than by number.

The volume value should be within the range of 0 to 0x100 (256), with this range representing 0% to 200% of the value defined in the original sound data. The default volume scale value for all channels is 0x80 (100%). This value is the same as the volume value required by the MusHandleSetVolume() function.

The pan value should be within the range of 0 to 0x100 (256), with this range representing 0% to 200% of the value defined in the original sound data. The default pan position scale value for all channels is 0x80 (100%). This value is the same as the pan value required by the MusHandleSetPan()function.

The overwrite flag influences the channel allocation process. If the flag is set to a value other than zero, and the sound effect number is currently playing, then its channels are used by the new sound effect.

The priority value allows the programmer to supply a custom priority level. If this value is set to -1, then the sound effect is started with the priority value supplied in the sound data.

Return Value
Sound handle or 0 if sound effect could not be triggered.

Example

  unsigned long Start3DSfx(int effect, float distance, float angle)
  {
    int scale;          /* distance scale 16-bit fraction */
    int priority;       /* adjusted priority level */
    int pan;            /* pan scale value */
    int volume; /* volume level */

    /* calculate distance scale */
    if (distance>=MAX_DISTANCE)
      return (0); /* sound is too far away! */
    distance = (MAX_DISTANCE-distance)*(65536.0/MAX_DISTANCE);
    scale = (int)distance;

    /* calculate pan position */
    if (angle>180.0)
      angle -= 180.0;
    else
    angle = 180.0-angle;
    angle = angle*(256.0/180.0);
    pan = (int)angle;

    /* calculate priority value */
    priority = Priority[effect]+((scale*MAX_PRI_CHANGE)>>16);

    /* calculate volume level */
    volume = (0x80*scale)>>16;

    return (StartSoundEffect2(effect, volume, pan, 1, priority));
  }