Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

NXPlayStream

	Inherits From:	NXSoundStream : Object
	Declared In:	soundkit/NXPlayStream.h

Class Description

The NXPlayStream class defines methods that initiate and control sound playback.  To play sounds with an NXPlayStream object, you must first connect it to an NXSoundOut object and then activate it; these tasks are done through the initOnDevice: and activate methods (as described in NXSoundStream). Once it's connected and activated, an NXPlayStream will accept and play buffers of sound data.  You supply it with these buffers through the playBuffer:size:tag: method.  The enqueuing of buffers must be timely and constant--a gap in playback occurs if the underlying sound device isn't supplied with buffers quickly enough (it "underruns").  You can prevent this sort of underrun by using larger buffers; if you're playing a determinate amount of existing data, there's no loss in enqueuing the entire sound in one large buffer.  Of course, this isn't possible if you're creating or controlling sound data dynamically; in particular, if you've set the size or number of DMA transfer buffers to yield a better response time (through messages to the NXSoundOut object), then the size of the buffers that you feed to the NXPlayStream should be no greater than DMA buffer size times the DMA buffer count.  In any case, you should note that you don't have to wait for a stream buffer to play before enqueuing the next one. The sound data in the buffers that you enqueue with an NXPlayStream can be one or two channels of 16-bit linear sound samples at either the 44.1 kHz or 22.05 kHz sampling rate.  Sounds in other formats and sampling rates must be converted before they can be played through an NXPlayStream. One of the features of an NXPlayStream is that it allows stream-independent amplitude scaling.  Amplitude-scaling, or gain, is a (stereo) factor that's applied linearly to the left and right channels to increase or decrease the amplitude of a stream before it's mixed with the other coincident playback streams.  The setGainLeft:right: method sets the left- and right-channel gain factors. Error Codes Many of the methods described here access underlying sound devices.  Such methods return error codes that declare success or describe failure.  A catalog of these error codes can be found in the section "Types and Constants" under the heading "NXSoundDeviceError."

Instance Variables

None declared in this class.

Method Types

	Initializing an NXPlayStream	initOnDevice:
	Activating and playing	activate

playBuffer:size:tag:

Gain and peak detection

setGainLeft:right:

getGainLeft:right: getPeakLeft:right:

Instance Methods

activate

(NXSoundDeviceError)activate

Activates the NXPlayStream so it can be used to play sounds.  This augments the superclass implementation by setting playback-specific attributes.  Returns an error code. See also:  activate (NXSoundStream)

getGainLeft:right:

getGainLeft:(float *)leftScale right:(float *)rightScale

Returns, by reference in the arguments, the general scaling factors that are applied to the left and right channels of this NXPlayStream.  By default, the gain in both channels is 1.0 (the sound is unmodified).  Returns self. See also:  setGainLeft:right:

getPeakLeft:right:

(NXSoundDeviceError)getPeakLeft:(float *)leftAmp right:(float *)rightAmp

Returns, by reference in the arguments, the most recently detected peak amplitudes for this NXPlayStream.  The peak values are normalized to fall within (0.0, 1.0), where 0.0 is no amplitude and 1.0 is maximum amplitude.  You typically set up a timed entry to invoke this method while sound is playing.

initOnDevice:

initOnDevice:anObject

The designated initializer for NXPlayStream, this method invokes the superclass version of initOnDevice: and then sets the the gain in both channels to 1.0.

playBuffer:size:tag:

(NXSoundDeviceError)playBuffer:(void *)data

size:(unsigned int)bytes tag:(int)aTag

Enqueues a buffer for playback. The arguments are as follows:

	Argument	Value
	data	A pointer to the buffer that you're enqueuing.
	bytes	The size of the buffer, in bytes
	aTag	A non-negative integer that's used to identify the buffer in subsequent delegate messags.

setGainLeft:right:

(NXSoundDeviceError)setGainLeft:(float)leftAmp right:(float)rightAmp

Set the NXPlayStream's general gain.  These gains are multiplied by the individual buffer gains (as set through playBuffer:size:tag:) to get the final amplitude gain for a particular buffer on this NXPlayStream. See also:  getGainLeft:right:

Methods Implemented by the Delegate

soundStreamDidUnderrun:

soundStreamDidUnderrun:sender

Invoked when the sound driver "underruns," or can't transfer data to the sound hardware quickly enough.  Underrun occurs if you're playing too many sounds at the same time, if the DMA transfer buffers are too small or too few, or if the overall system load is too high.  It results in a gap in playback.