libASPL
Loading...
Searching...
No Matches
aspl::Stream Class Reference

Audio stream object. More...

#include <aspl/Stream.hpp>

Inheritance diagram for aspl::Stream:
aspl::Object

Public Member Functions

 Stream (std::shared_ptr< const Context > context, std::shared_ptr< Device > device, const StreamParameters &params={})
 Construct stream.
 
Getters and setters
virtual bool GetIsActive () const
 Tell whether the stream participates in I/O. By default returns the last value set by SetIsActive(). Initial value is true.
 
OSStatus SetIsActive (bool isActive)
 Activate or deactivate stream. Invokes SetIsActiveImpl() and NotifyPropertyChanged().
 
virtual Direction GetDirection () const
 Get stream direction. By default returns corresponding field of StreamParameters.
 
virtual UInt32 GetTerminalType () const
 Get terminal type. By default returns kAudioStreamTerminalTypeMicrophone if GetDirection() returns Direction::Input, and kAudioStreamTerminalTypeSpeaker if it return Direction::Output.
 
virtual UInt32 GetStartingChannel () const
 Absolute channel number for the first channel in the stream. For example, if a device has two output streams with two channels each, then the starting channel number for the first stream is 1 and thus starting channel number for the second stream is 3. By default returns StreamParameters::StartingChannel.
 
UInt32 GetChannelCount () const
 Get number of channels in stream. Return value is based on GetPhysicalFormat().
 
Float64 GetSampleRate () const
 Get stream sample rate. Return value is based on GetPhysicalFormat().
 
virtual UInt32 GetLatency () const
 Get any additional presentation latency the stream has. This latency is added to the device latency. By default returns value last set with SetLatencyAsync(). Initial value is StreamParameters::Latency.
 
OSStatus SetLatencyAsync (UInt32 latency)
 Asynchronously set stream presentation latency, Requests HAL to asynchronously invoke SetLatencyImpl().
 
virtual AudioStreamBasicDescription GetPhysicalFormat () const
 Get the current physical format of the stream. Physical format defines the underlying format supported natively by hardware. By default returns value set by last SetPhysicalFormatAsync() call. Initial value is StreamParameters::Format.
 
OSStatus SetPhysicalFormatAsync (AudioStreamBasicDescription format)
 Set current format of the stream. Requests HAL to asynchronously invoke SetPhysicalFormatImpl(). Fails if format is not present in GetAvailablePhysicalFormats(), which by default returns only one format, provided during initialization. If you want to make your stream supporting multiple formats, you typically need to override both of these methods.
 
virtual std::vector< AudioStreamRangedDescription > GetAvailablePhysicalFormats () const
 Get list of supported physical formats. Empty list means that any format is allowed. By default returns the last value set by SetAvailablePhysicalFormatsAsync(). If nothing was set, return a single-element list with the format returned by GetPhysicalFormat().
 
OSStatus SetAvailablePhysicalFormatsAsync (std::vector< AudioStreamRangedDescription > formats)
 Asynchronously set list of supported physical formats. See comments for GetAvailablePhysicalFormats(). Requests HAL to asynchronously invoke SetAvailablePhysicalFormatsImpl().
 
virtual AudioStreamBasicDescription GetVirtualFormat () const
 Get the current format of the stream. Virtual format defines the format used to present the device to the apps. For example, physical format may use integers, while virtual format may use floating point numbers. For devices that don't override the mix operation, the virtual format has to be the same as the physical format. By default returns value set by last SetVirtualFormatAsync() call. Initial value is StreamParameters::Format.
 
OSStatus SetVirtualFormatAsync (AudioStreamBasicDescription format)
 Set current virtual format of the stream. Requests HAL to asynchronously invoke SetVirtualFormatImpl(). Fails if format is not present in GetAvailableVirtualFormats(), which by default returns only one format, provided during initialization. If you want to make your stream supporting multiple formats, you typically need to override both of these methods.
 
virtual std::vector< AudioStreamRangedDescription > GetAvailableVirtualFormats () const
 Get list of supported virtual formats. Empty list means that any format is allowed. By default returns the last value set by SetAvailableVirtualFormatsAsync(). If nothing was set, return a single-element list with the format returned by GetVirtualFormat().
 
OSStatus SetAvailableVirtualFormatsAsync (std::vector< AudioStreamRangedDescription > formats)
 Asynchronously set list of supported virtual formats. See comments for GetAvailableVirtualFormats(). Requests HAL to asynchronously invoke SetAvailableVirtualFormatsImpl().
 
Processing
virtual UInt32 ConvertFramesToBytes (UInt32 numFrames) const
 Convert number of frame to the number of bytes. Result depends on the value returned by GetPhysicalFormat().
 
virtual UInt32 ConvertBytesToFrames (UInt32 numBytes) const
 Convert number of bytes to the number of frames. Result depends on the value returned by GetPhysicalFormat().
 
void AttachVolumeControl (std::shared_ptr< VolumeControl > control)
 Attach volume control to the stream. ApplyProcessing() will use control to apply volume settings to the stream.
 
void AttachMuteControl (std::shared_ptr< MuteControl > control)
 Attach mute control to the stream. ApplyProcessing() will use control to apply mute settings to the stream.
 
virtual void ApplyProcessing (Float32 *frames, UInt32 frameCount, UInt32 channelCount) const
 Apply processing to the stream's data. The provided buffer contains exactly frameCount * channelCount samples. Modifies frames in the provided buffer. Default implementation invokes ApplyProcessing() on attached volume and mute controls, if they are present.
 
Configuration
void RequestConfigurationChange (std::function< void()> func={})
 Request HAL to perform configuration update. Similar to Device::RequestConfigurationChange().
 
Property dispatch
AudioClassID GetClass () const override
 Get class ID.
 
AudioClassID GetBaseClass () const override
 Get base class ID.
 
bool IsInstance (AudioClassID classID) const override
 Check if this object is instance of given base class.
 
Boolean HasProperty (AudioObjectID objectID, pid_t clientPID, const AudioObjectPropertyAddress *address) const override
 Check whether given property is present.
 
OSStatus IsPropertySettable (AudioObjectID objectID, pid_t clientPID, const AudioObjectPropertyAddress *address, Boolean *outIsSettable) const override
 Check whether given property can be changed.
 
OSStatus GetPropertyDataSize (AudioObjectID objectID, pid_t clientPID, const AudioObjectPropertyAddress *address, UInt32 qualifierDataSize, const void *qualifierData, UInt32 *outDataSize) const override
 Get size of property value in bytes.
 
OSStatus GetPropertyData (AudioObjectID objectID, pid_t clientPID, const AudioObjectPropertyAddress *address, UInt32 qualifierDataSize, const void *qualifierData, UInt32 inDataSize, UInt32 *outDataSize, void *outData) const override
 Get property value.
 
OSStatus SetPropertyData (AudioObjectID objectID, pid_t clientPID, const AudioObjectPropertyAddress *address, UInt32 qualifierDataSize, const void *qualifierData, UInt32 inDataSize, const void *inData) override
 Change property value.
 
- Public Member Functions inherited from aspl::Object
 Object (std::shared_ptr< const Context > context, const char *className="Object", AudioObjectID objectID=kAudioObjectUnknown)
 Construct object. Class name is used for logging. It should be the name of the derived class. If objectID is kAudioObjectUnknown (zero), allocates new object ID. Otherwise uses given object ID.
 
 Object (const Object &)=delete
 
Objectoperator= (const Object &)=delete
 
std::shared_ptr< const ContextGetContext () const
 Get object context.
 
AudioObjectID GetID () const
 Get object ID. Returns objectID selected at construction time.
 
AudioObjectID GetOwnerID () const
 Get object owner. If the object has an owner, returns its ID. Otherwise, returns kAudioObjectUnknown (zero).
 
bool HasOwner () const
 Check if the object is part of the hierarchy. Returns true if GetOwnerID() is not equal to kAudioObjectUnknown.
 
std::vector< AudioObjectID > GetOwnedObjectIDs (AudioObjectPropertyScope scope=kAudioObjectPropertyScopeGlobal, AudioClassID classID=0) const
 Get owned objects. Returns the list of objects to which this object is the owner.
 
void AddOwnedObject (std::shared_ptr< Object > object, AudioObjectPropertyScope scope=kAudioObjectPropertyScopeGlobal)
 Add object to the list of owned objects. Also invokes SetOwner() on the added object.
 
void RemoveOwnedObject (AudioObjectID objectID)
 Remove object to the list of owned objects. Also invokes SetOwner() on the removed object.
 
void NotifyPropertyChanged (AudioObjectPropertySelector selector, AudioObjectPropertyScope scope=kAudioObjectPropertyScopeGlobal, AudioObjectPropertyElement element=kAudioObjectPropertyElementMain) const
 Notify HAL that a property was changed. This is automatically called by all setters.
 
void NotifyPropertiesChanged (std::vector< AudioObjectPropertySelector > selectors, AudioObjectPropertyScope scope=kAudioObjectPropertyScopeGlobal, AudioObjectPropertyElement element=kAudioObjectPropertyElementMain) const
 Notify HAL that some properties were changed. This is automatically called by all setters.
 
virtual std::vector< AudioServerPlugInCustomPropertyInfo > GetCustomProperties () const
 Get info about registered custom properties. Returns list of properties added using RegisterCustomProperty().
 
template<typename ObjectType , typename ValueType >
void RegisterCustomProperty (AudioObjectPropertySelector selector, ObjectType &object, GetterMethod< ObjectType, ValueType > getter, SetterMethod< ObjectType, ValueType > setter=nullptr)
 Register custom property with getter and optional setter.
 
template<typename GetterFunc >
void RegisterCustomProperty (AudioObjectPropertySelector selector, GetterFunc getter)
 Register custom property with getter and optional setter.
 
void RegisterCustomProperty (AudioObjectPropertySelector selector, std::function< CFStringRef()> getter, std::function< void(CFStringRef)> setter)
 Register custom property with getter and optional setter.
 
void RegisterCustomProperty (AudioObjectPropertySelector selector, std::function< CFPropertyListRef()> getter, std::function< void(CFPropertyListRef)> setter)
 Register custom property with getter and optional setter.
 

Protected Member Functions

Setters implementation
virtual OSStatus SetIsActiveImpl (bool isActive)
 Activate or deactivate stream. Should return zero if the state was successfully changed. By default just changes the value returned by GetIsActive(). Invoked by SetIsActive().
 
virtual OSStatus SetLatencyImpl (UInt32 latency)
 Set stream presentation latency. Invoked by SetLatencyAsync() to actually change the latency. Default implementation just changes the value returned by GetLatency().
 
virtual OSStatus SetPhysicalFormatImpl (const AudioStreamBasicDescription &format)
 Set current format of the stream. Invoked by SetPhysicalFormatAsync() to actually change the format. Default behavior is to change the format returned by GetPhysicalFormat() and to invoke Device::SetSampleRateAsync() to ensure that device and all its streams have the same rate.
 
virtual OSStatus SetAvailablePhysicalFormatsImpl (std::vector< AudioStreamRangedDescription > formats)
 Set list of supported physical formats. Invoked by SetAvailablePhysicalFormatsAsync(). Default implementation just changes the list returned by GetAvailablePhysicalFormats().
 
virtual OSStatus SetVirtualFormatImpl (const AudioStreamBasicDescription &format)
 Set current virtual format of the stream. Invoked by SetVirtualFormatAsync() to actually change the format. Default behavior is to change the format returned by GetVirtualFormat() and to invoke Device::SetSampleRateAsync() to ensure that device and all its streams have the same rate.
 
virtual OSStatus SetAvailableVirtualFormatsImpl (std::vector< AudioStreamRangedDescription > formats)
 Set list of supported virtual formats. Invoked by SetAvailableVirtualFormatsAsync(). Default implementation just changes the list returned by GetAvailableVirtualFormats().
 

Additional Inherited Members

- Public Types inherited from aspl::Object
template<typename ObjectType , typename ValueType >
using GetterMethod = ValueType (ObjectType::*)() const
 Pointer to custom property getter method. Used in RegisterCustomProperty().
 
template<typename ObjectType , typename ValueType >
using SetterMethod = void (ObjectType::*)(ValueType)
 Pointer to custom property setter method. Used in RegisterCustomProperty().
 

Detailed Description

Audio stream object.

Stream is part of a Device representing a source (input stream) or a destination (output stream) for samples. Clients connected to the device can read from its input streams and write to its output streams.

Each stream can have its own format, latency, and other parameters.

Stream does not do I/O by its own. Instead, it provides ApplyProcessing() method, which is invoked by ReaderWriter (in its default implementation).

Default implementation of Stream::ApplyProcessing() just invokes corresponding methods on attached VolumeControl and MuteControl objects, which you can set using AttachVolumeControl() and AttachMuteControl().

Definition at line 76 of file Stream.hpp.

Constructor & Destructor Documentation

◆ Stream()

aspl::Stream::Stream ( std::shared_ptr< const Context > context,
std::shared_ptr< Device > device,
const StreamParameters & params = {} )
explicit

Construct stream.

Member Function Documentation

◆ ApplyProcessing()

virtual void aspl::Stream::ApplyProcessing ( Float32 * frames,
UInt32 frameCount,
UInt32 channelCount ) const
virtual

Apply processing to the stream's data. The provided buffer contains exactly frameCount * channelCount samples. Modifies frames in the provided buffer. Default implementation invokes ApplyProcessing() on attached volume and mute controls, if they are present.

Note
Invoked by ReaderWriter on realtime thread.

◆ AttachMuteControl()

void aspl::Stream::AttachMuteControl ( std::shared_ptr< MuteControl > control)

Attach mute control to the stream. ApplyProcessing() will use control to apply mute settings to the stream.

◆ AttachVolumeControl()

void aspl::Stream::AttachVolumeControl ( std::shared_ptr< VolumeControl > control)

Attach volume control to the stream. ApplyProcessing() will use control to apply volume settings to the stream.

◆ ConvertBytesToFrames()

virtual UInt32 aspl::Stream::ConvertBytesToFrames ( UInt32 numBytes) const
virtual

Convert number of bytes to the number of frames. Result depends on the value returned by GetPhysicalFormat().

◆ ConvertFramesToBytes()

virtual UInt32 aspl::Stream::ConvertFramesToBytes ( UInt32 numFrames) const
virtual

Convert number of frame to the number of bytes. Result depends on the value returned by GetPhysicalFormat().

◆ GetAvailablePhysicalFormats()

virtual std::vector< AudioStreamRangedDescription > aspl::Stream::GetAvailablePhysicalFormats ( ) const
virtual

Get list of supported physical formats. Empty list means that any format is allowed. By default returns the last value set by SetAvailablePhysicalFormatsAsync(). If nothing was set, return a single-element list with the format returned by GetPhysicalFormat().

Note
Backs kAudioStreamPropertyAvailablePhysicalFormats property.

◆ GetAvailableVirtualFormats()

virtual std::vector< AudioStreamRangedDescription > aspl::Stream::GetAvailableVirtualFormats ( ) const
virtual

Get list of supported virtual formats. Empty list means that any format is allowed. By default returns the last value set by SetAvailableVirtualFormatsAsync(). If nothing was set, return a single-element list with the format returned by GetVirtualFormat().

Note
Backs kAudioStreamPropertyAvailableVirtualFormats property.

◆ GetBaseClass()

AudioClassID aspl::Stream::GetBaseClass ( ) const
overridevirtual

Get base class ID.

Reimplemented from aspl::Object.

◆ GetChannelCount()

UInt32 aspl::Stream::GetChannelCount ( ) const

Get number of channels in stream. Return value is based on GetPhysicalFormat().

◆ GetClass()

AudioClassID aspl::Stream::GetClass ( ) const
overridevirtual

Get class ID.

Reimplemented from aspl::Object.

◆ GetDirection()

virtual Direction aspl::Stream::GetDirection ( ) const
virtual

Get stream direction. By default returns corresponding field of StreamParameters.

See also
StreamParameters::Direction.
Note
Backs kAudioStreamPropertyDirection property.

◆ GetIsActive()

virtual bool aspl::Stream::GetIsActive ( ) const
virtual

Tell whether the stream participates in I/O. By default returns the last value set by SetIsActive(). Initial value is true.

Note
Backs kAudioStreamPropertyIsActive property.

◆ GetLatency()

virtual UInt32 aspl::Stream::GetLatency ( ) const
virtual

Get any additional presentation latency the stream has. This latency is added to the device latency. By default returns value last set with SetLatencyAsync(). Initial value is StreamParameters::Latency.

Note
Backs kAudioStreamPropertyLatency property.

◆ GetPhysicalFormat()

virtual AudioStreamBasicDescription aspl::Stream::GetPhysicalFormat ( ) const
virtual

Get the current physical format of the stream. Physical format defines the underlying format supported natively by hardware. By default returns value set by last SetPhysicalFormatAsync() call. Initial value is StreamParameters::Format.

Note
Backs kAudioStreamPropertyPhysicalFormat property.

◆ GetPropertyData()

OSStatus aspl::Stream::GetPropertyData ( AudioObjectID objectID,
pid_t clientPID,
const AudioObjectPropertyAddress * address,
UInt32 qualifierDataSize,
const void * qualifierData,
UInt32 inDataSize,
UInt32 * outDataSize,
void * outData ) const
overridevirtual

Get property value.

Reimplemented from aspl::Object.

◆ GetPropertyDataSize()

OSStatus aspl::Stream::GetPropertyDataSize ( AudioObjectID objectID,
pid_t clientPID,
const AudioObjectPropertyAddress * address,
UInt32 qualifierDataSize,
const void * qualifierData,
UInt32 * outDataSize ) const
overridevirtual

Get size of property value in bytes.

Reimplemented from aspl::Object.

◆ GetSampleRate()

Float64 aspl::Stream::GetSampleRate ( ) const

Get stream sample rate. Return value is based on GetPhysicalFormat().

◆ GetStartingChannel()

virtual UInt32 aspl::Stream::GetStartingChannel ( ) const
virtual

Absolute channel number for the first channel in the stream. For example, if a device has two output streams with two channels each, then the starting channel number for the first stream is 1 and thus starting channel number for the second stream is 3. By default returns StreamParameters::StartingChannel.

Note
Backs kAudioStreamPropertyStartingChannel property.

◆ GetTerminalType()

virtual UInt32 aspl::Stream::GetTerminalType ( ) const
virtual

Get terminal type. By default returns kAudioStreamTerminalTypeMicrophone if GetDirection() returns Direction::Input, and kAudioStreamTerminalTypeSpeaker if it return Direction::Output.

Remarks
Indicates what is at the other end of the stream such as a speaker or headphones, or a microphone. Values for this property are defined in <CoreAudio/AudioHardwareBase.h>
Note
Backs kAudioStreamPropertyTerminalType property.

◆ GetVirtualFormat()

virtual AudioStreamBasicDescription aspl::Stream::GetVirtualFormat ( ) const
virtual

Get the current format of the stream. Virtual format defines the format used to present the device to the apps. For example, physical format may use integers, while virtual format may use floating point numbers. For devices that don't override the mix operation, the virtual format has to be the same as the physical format. By default returns value set by last SetVirtualFormatAsync() call. Initial value is StreamParameters::Format.

Note
Backs kAudioStreamPropertyVirtualFormat property.

◆ HasProperty()

Boolean aspl::Stream::HasProperty ( AudioObjectID objectID,
pid_t clientPID,
const AudioObjectPropertyAddress * address ) const
overridevirtual

Check whether given property is present.

Reimplemented from aspl::Object.

◆ IsInstance()

bool aspl::Stream::IsInstance ( AudioClassID classID) const
overridevirtual

Check if this object is instance of given base class.

Reimplemented from aspl::Object.

◆ IsPropertySettable()

OSStatus aspl::Stream::IsPropertySettable ( AudioObjectID objectID,
pid_t clientPID,
const AudioObjectPropertyAddress * address,
Boolean * outIsSettable ) const
overridevirtual

Check whether given property can be changed.

Reimplemented from aspl::Object.

◆ RequestConfigurationChange()

void aspl::Stream::RequestConfigurationChange ( std::function< void()> func = {})

Request HAL to perform configuration update. Similar to Device::RequestConfigurationChange().

◆ SetAvailablePhysicalFormatsAsync()

OSStatus aspl::Stream::SetAvailablePhysicalFormatsAsync ( std::vector< AudioStreamRangedDescription > formats)

Asynchronously set list of supported physical formats. See comments for GetAvailablePhysicalFormats(). Requests HAL to asynchronously invoke SetAvailablePhysicalFormatsImpl().

◆ SetAvailablePhysicalFormatsImpl()

virtual OSStatus aspl::Stream::SetAvailablePhysicalFormatsImpl ( std::vector< AudioStreamRangedDescription > formats)
protectedvirtual

Set list of supported physical formats. Invoked by SetAvailablePhysicalFormatsAsync(). Default implementation just changes the list returned by GetAvailablePhysicalFormats().

◆ SetAvailableVirtualFormatsAsync()

OSStatus aspl::Stream::SetAvailableVirtualFormatsAsync ( std::vector< AudioStreamRangedDescription > formats)

Asynchronously set list of supported virtual formats. See comments for GetAvailableVirtualFormats(). Requests HAL to asynchronously invoke SetAvailableVirtualFormatsImpl().

◆ SetAvailableVirtualFormatsImpl()

virtual OSStatus aspl::Stream::SetAvailableVirtualFormatsImpl ( std::vector< AudioStreamRangedDescription > formats)
protectedvirtual

Set list of supported virtual formats. Invoked by SetAvailableVirtualFormatsAsync(). Default implementation just changes the list returned by GetAvailableVirtualFormats().

◆ SetIsActive()

OSStatus aspl::Stream::SetIsActive ( bool isActive)

Activate or deactivate stream. Invokes SetIsActiveImpl() and NotifyPropertyChanged().

Note
Backs kAudioStreamPropertyIsActive property.

◆ SetIsActiveImpl()

virtual OSStatus aspl::Stream::SetIsActiveImpl ( bool isActive)
protectedvirtual

Activate or deactivate stream. Should return zero if the state was successfully changed. By default just changes the value returned by GetIsActive(). Invoked by SetIsActive().

Note
Backs kAudioStreamPropertyIsActive property.

◆ SetLatencyAsync()

OSStatus aspl::Stream::SetLatencyAsync ( UInt32 latency)

Asynchronously set stream presentation latency, Requests HAL to asynchronously invoke SetLatencyImpl().

◆ SetLatencyImpl()

virtual OSStatus aspl::Stream::SetLatencyImpl ( UInt32 latency)
protectedvirtual

Set stream presentation latency. Invoked by SetLatencyAsync() to actually change the latency. Default implementation just changes the value returned by GetLatency().

◆ SetPhysicalFormatAsync()

OSStatus aspl::Stream::SetPhysicalFormatAsync ( AudioStreamBasicDescription format)

Set current format of the stream. Requests HAL to asynchronously invoke SetPhysicalFormatImpl(). Fails if format is not present in GetAvailablePhysicalFormats(), which by default returns only one format, provided during initialization. If you want to make your stream supporting multiple formats, you typically need to override both of these methods.

Note
Backs kAudioStreamPropertyPhysicalFormat property.

◆ SetPhysicalFormatImpl()

virtual OSStatus aspl::Stream::SetPhysicalFormatImpl ( const AudioStreamBasicDescription & format)
protectedvirtual

Set current format of the stream. Invoked by SetPhysicalFormatAsync() to actually change the format. Default behavior is to change the format returned by GetPhysicalFormat() and to invoke Device::SetSampleRateAsync() to ensure that device and all its streams have the same rate.

Note
Backs kAudioStreamPropertyPhysicalFormat property.

◆ SetPropertyData()

OSStatus aspl::Stream::SetPropertyData ( AudioObjectID objectID,
pid_t clientPID,
const AudioObjectPropertyAddress * address,
UInt32 qualifierDataSize,
const void * qualifierData,
UInt32 inDataSize,
const void * inData )
overridevirtual

Change property value.

Reimplemented from aspl::Object.

◆ SetVirtualFormatAsync()

OSStatus aspl::Stream::SetVirtualFormatAsync ( AudioStreamBasicDescription format)

Set current virtual format of the stream. Requests HAL to asynchronously invoke SetVirtualFormatImpl(). Fails if format is not present in GetAvailableVirtualFormats(), which by default returns only one format, provided during initialization. If you want to make your stream supporting multiple formats, you typically need to override both of these methods.

Note
Backs kAudioStreamPropertyVirtualFormat property.

◆ SetVirtualFormatImpl()

virtual OSStatus aspl::Stream::SetVirtualFormatImpl ( const AudioStreamBasicDescription & format)
protectedvirtual

Set current virtual format of the stream. Invoked by SetVirtualFormatAsync() to actually change the format. Default behavior is to change the format returned by GetVirtualFormat() and to invoke Device::SetSampleRateAsync() to ensure that device and all its streams have the same rate.

Note
Backs kAudioStreamPropertyVirtualFormat property.

The documentation for this class was generated from the following file: