Class SoundObj

See Also: Class ReferenceTarget, Class Animatable.

class SoundObj : public ReferenceTarget

Description:

This is the base class for the creation of sound plug-ins. The 3ds max user may choose a sound plug-in using the File / Preferences... Animation Tab / Sound Plug-In option.

There is always one sound object in the scene. A sound object's primary purpose is to provide a sound track for the scene. The sound object also serves as a clock that controls timing when an animation is played. This ensure the animation is synched to the sound object. This class has methods to start and stop the sound playing, play a specified range of the sound, and toggle the sound on and off.

A sound plug-in can participate in Track View by implementing the methods of Animatable such as PaintTrack(). See the Advanced Topics section Track View for details.

Sound Object plug-ins use a Super Class ID of SOUNDOBJ_CLASS_ID.

Methods:

Prototype:

virtual BOOL Play(TimeValue tStart,TimeValue t0,TimeValue t1,TimeValue frameStep)=0;

Remarks:

Implemented by the Plug-In.

When the system calls this method the plug-in should loop the playing of sound from time t0 to t1 beginning at time tStart. It should continue to loop until Stop() is called.

Parameters:

TimeValue tStart

The time to start playing the sound.

TimeValue t0

The loop begin range.

TimeValue t1

The loop end range.

TimeValue frameStep

The frame increment.

Return Value:

TRUE if the sound was played; FALSE otherwise.

Prototype:

virtual void Scrub(TimeValue t0,TimeValue t1)=0;

Remarks:

Implemented by the Plug-In.

Implementation of this method is optional. The plug-in should play the amount of sound between time t0 and t1. The sound should only be played once.

Parameters:

TimeValue t0

The start time for playback.

TimeValue t1

The end time for playback.

Prototype:

virtual TimeValue Stop()=0;

Remarks:

Implemented by the Plug-In.

This stops the sound from playing.

Return Value:

The time at which the sound was stopped.

Prototype:

virtual TimeValue GetTime()=0;

Remarks:

Implemented by the Plug-In.

This returns the current time as managed by the SoundObj.

Return Value:

The current time.

Prototype:

virtual BOOL Playing()=0;

Remarks:

Implemented by the Plug-In.

Returns TRUE if the sound is playing; otherwise FALSE.

Prototype:

virtual void SaveSound(PAVIFILE pfile,TimeValue t0,TimeValue t1)=0;

Remarks:

Implemented by the Plug-In.

This saves the sound between the specified times to the specified file.

Parameters:

PAVIFILE pfile

The file to save the sound track to.

TimeValue t0

The start of the time range to save.

TimeValue t1

The end of the time range to save.

Prototype:

virtual void SetMute(BOOL mute)=0;

Remarks:

Implemented by the Plug-In.

Sets the sound to mute or toggles it back on. This will be called if the Active checkbox is toggled for example.

Parameters:

BOOL mute

Specifies if the sound should be muted. TRUE indicates the sound should be muted; FALSE indicates the sound should be enabled.

Prototype:

virtual BOOL IsMute()=0;

Remarks:

Implemented by the Plug-In.

Returns TRUE if the sound is muted; otherwise FALSE.

The following function is not a method of class SoundObj but is used by the system internally:

Function:

SoundObj *NewDefaultSoundObj();

Remarks:

Implemented by the System.

Returns a new default sound object. This is the standard one provided by 3ds max.