mvPrimaryAudio(3dm)

NAME
     mvSetPrimaryAudio, mvGetPrimaryAudio - Set/get the movie instance with
     control over the audio hardware


SYNOPSIS
     #include <dmedia/moviefile.h>
     #include <dmedia/movieplay.h>


     void mvSetPrimaryAudio(MVid movieid);

     MVid mvGetPrimaryAudio(void);


DESCRIPTION
     mvSetPrimaryAudio(3dm) tells the Movie Playback Library to favor a
     particular movie's audio sampling rate for playback. The preferred audio
     sample rate of a movie is the sample rate of the movie's first audio
     track.  You may designate a movie as primary regardless of whether or not
     it is currently playing.

     The default value for the primary audio movie is MV_PRIMARY_AUDIO_NOTSET.

     When the primary audio movie is set to something other than
     MV_PRIMARY_AUDIO_NOTSET, the movie library will use a "rude" policy for
     setting the system audio hardware sampling rate.  When this is the case
     and whenever the primary audio movie is playing, the Movie Playback
     Library will set the audio hardware sampling rate based on the preferred
     audio sample rate of the primary audio movie.

     When the primary audio movie is MV_PRIMARY_AUDIO_NOTSET, the movie
     library use a "polite" policy for setting the system audio hardware
     sample rate.  The Movie Playback Library opens an output ALport for each
     movie that has at least one audio track and is currently bound to a
     window (see mvBindOpenGLWindow(3dm)).  When the primary audio movie is
     MV_PRIMARY_AUDIO_NOTSET and such a movie starts playing (see
     mvPlay(3dm)), the Movie Playback Library checks to see if the system has
     any other currently open output ALports (see alGetParams(3dm)).  These
     other ALports could belong to other movies currently opened by the same
     process (or process group), movies open in other applications, or other
     processes that use output ALports.  If there are no other currently open
     output ALports, the Movie Playback Library will set the audio hardware
     sample based on that movie. If there is at least one other currently open
     output ALport, the Movie Playback Library will use linear sample rate
     conversion (when necessary) to ensure that the movie's audio will play
     using the current audio hardware sampling rate.

     The Movie Playback library does not follow this protocol for movies bound
     directly to a movie library audio port (MV_PORT_AUDIO) with
     mvBindMovieToPorts(3dm) with the ownsRate set to DM_TRUE.  When these
     movies start playing, a "rude" policy is used.  See the section on
     MV_PORT_AUDIO in mvPort(3dm) for details.

     Once you designate a primary movie, it owns the audio hardware until you
     designate another with a subsequent call to mvSetPrimaryAudio(3dm), or
     you close the movie by calling mvClose(3dm).  If you close the primary
     movie, the primary movie will revert to MV_PRIMARY_AUDIO_NOTSET.

     To remove primary audio status from a particular movie, but not assign to
     another movie, you may call mvSetPrimaryAudio(3dm) with the value
     MV_PRIMARY_AUDIO_NOTSET.

     mvGetPrimaryAudio(3dm) returns the movie ID which currently has primary
     audio status, or MV_PRIMARY_AUDIO_NOTSET if no movie has primary audio
     status.

     Only one movie may have primary audio status at any given time.


SEE ALSO
     ALintro(3dm), alGetDefaults(3dm), alOpenPort(3dm), alSetParams(3dm),
     mvBindWindow(3dm), mvIntro(3dm), mvPlay(3dm), mvPort(3dm).