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

NXSoundParameters

	Adopted By:	NXSoundParameters (the class) NXSoundDevice
	Declared In:	soundkit/NXSoundParameters.h

Protocol Description

The NXSoundParameters protocol defines methods that set and retrieve the values of particular sound attribute, or "parameters".  Each parameter is identified by an integer constant called a parameter key.  Parameters always take numeric values; some of these values are represented by integer constants called parameter values.  Cumulatively, the constants that represent parameter keys and parameter values are called parameter tags; the list of parameter tags, divided into keys and values, that are defined by the Sound Kit is given in the section "Types and Constants."  (To avoid confusion, the parameter tags that represent parameter values are referred to as parameter value tags.) Hardware and Software Parameters A parameter key corresponds either to a hardware or a software sound attribute.  Hardware parameter keys take the form "NX_SoundDeviceAttribute"; for example, NX_SoundDeviceMuteSpeaker.  Software parameter keys take the form "NX_SoundStreamAttribute", as in NX_SoundStreamGainStereo. Software parameter keys are guaranteed to be applicable to any computer.  A similar assurance can't be made for the hardware parameter keys.  For example, the NX_SoundDeviceMuteSpeaker parameter key only makes sense for computers that have a built-in speaker.  The getParameters:count: is useful in determining which parameter keys are used on a particular hardware platform, as explained in the method descriptions below. Parameter Values To set a parameter's value, you use one of the setParameter:toType: methods, passing a parameter key as the first argument, and a value of type Type as the second.  Parameters only accept numeric values; the value-setting methods that are defined here let you set a parameter as an int, a float, or a BOOL. Some parameters take discrete values that are represented by parameter value tags.  For example, the NX_SoundDeviceAnalogInput parameter key accepts two values, NX_SoundDeviceAnalogInputSource_Microphone and NX_SoundDeviceAnalogInputSource_LineIn.  The list of parameters keys that take parameter value tags is given below: NX_SoundDeviceAnlogInputSource NX_SoundDeviceAnalogInputSource_Microphone NX_SoundDeviceAnalogInputSource_LineIn NX_SoundStreamDataEncoding NX_SoundStreamDataEncoding_Linear16 NX_SoundStreamDataEncoding_Linear8 NX_SoundStreamDataEncoding_Mulaw8 NX_SoundStreamDataEncoding_Alaw8 NX_SoundStreamDataEncoding_AES NX_SoundStreamSource NX_SoundStreamSource_Analog NX_SoundStreamSource_AES NX_SoundStreamSink NX_SoundStreamSink_Analog NX_SoundStreamSink_AES The getValues:count:forParameter: method returns the parameter value tags for the given (last argument) parameter key. Since not all parameter keys take parameter value tags, this method isn't meaningful for all parameter key arguments. Applying NXSoundParameters Objects A single NXSoundParameters object can hold key/value pairs for any number of parameters.  You can apply these settings to an NXSoundDevice or NXSoundStream object through methods defined in those classes.  The object takes and applies the parameters that are meaningful to it; in other words, NXSoundDevice objects set hardware parameters, NXSoundStream objects set software parameters. The Sound Kit provides the NXSoundParameters class as a convenient cover for this protocol.  Instances of the class implement the methods found here so you can encapsulate and "pass around" your favorite sound parameter settings. In addition, the NXSoundDevice class conforms to the protocol, allowing you to set hardware parameters directly in an NXSoundDevice object.  When you create an NXSoundDevice object, the parameter keys that represent the supported (hardware) parameters are automatically set to default values.

Method Types

Getting parameter values

boolValueForParameter:

floatValueForParameter: intValueForParameter:

Setting parameter values

setParameter:toBool:

setParameter:toFloat: setParameter:toInt:

Querying parameters

getParameters:count:

getValues:count:forParameter: isParameterPresent: removeParameter:

Instance Methods

boolValueForParameter:

(BOOL)boolValueForParameter:(NXSoundParameterTag)tag

Returns the value of the parameter represented by tag as a boolean, converting the value if necessary.

floatValueForParameter:

(float)floatValueForParameter:(NXSoundParameterTag)tag

Returns the value of the parameter represented by tag as a float, converting the value if necessary.

getParameters:count:

(void)getParameters:(const NXSoundParameterTag **)tagList

count:(unsigned int *)tagCount

Returns, in tagList, an array of the parameter keys that are present in the NXSoundParameters object.  The number of elements in the list is returned in count.  Note that if the receiver is a newly-initialized NXSoundDevice object, then the keys in the list represent the hardware parameters that are supported by the hardware.

getValues:count:forParameter:

(void)getValues:(const NXSoundParameterTag **)valueTagList

count:(unsigned int *)numValues forParameter:(NXSoundParameterTag)tag

Returns, in valueTagList, a list of the parameter values tags that are accepted by the parameter key tag tag.   If the parameter key doesn't accept parameter value tags, then the list will be empty.

intValueForParameter:

(int)intValueForParameter:(NXSoundParameterTag)ptag

Returns the value of the parameter represented by tag as an int, converting the value if necessary.

isParameterPresent:

(BOOL)isParameterPresent:(NXSoundParameterTag)tag

Returns YES if the parameter represented by tag is present (has been set) in the object.

removeParameter:

(void)removeParameter:(NXSoundParameterTag)tag

Removes the parameter represented by tag from the object.

setParameter:toBool:

(void)setParameter:(NXSoundParameterTag)tag toBool:(BOOL)flag

Sets the parameter represented by tag to the boolean value given by flag.

setParameter:toFloat:

(void)setParameter:(NXSoundParameterTag)ptag toFloat:(float)aFloat

Sets the parameter represented by tag to the floating-point value given by aFloat.

setParameter:toInt:

(void)setParameter:(NXSoundParameterTag)tag toInt:(int)anInt

Sets the parameter represented by tag to the integer value given by anInt.