N64® Functions Menu

al - Audio Library Functions
gDP - DP GBI Macros
gdSP - General GBI Macros
gSP - SP GBI Macros
gt - Turbo Microcode RDP
gu - Graphics Utilities
Math - Math Functions
Mus - Mus Library
nuSys - NuSystem
os - N64 Operating System
sp - Sprite Library Functions
uh - Host to Target IO
64DD - N64 Disk Drive

Nintendo® Confidential

Mus Library Reference

## 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));
      }

See Also
MusStartEffect()
MusHandleAsk()
MusHandleSetFreqOffset()
MusHandleSetPan()
MusHandleSetVolume()
MusHandleStop()
MusSetMasterVolume()
MusAsk()
MusStop()

Nintendo® Confidential Warning: all information in this document is confidential and covered by a non-disclosure agreement. You are responsible for keeping this information confidential and protected. Nintendo will vigorously enforce this responsibility.
Copyright © 1998-1999
Nintendo of America Inc. All rights reserved
Nintendo and N64 are registered trademarks of Nintendo
Last updated March 1999