Volume control object. More...

#include <aspl/VolumeControl.hpp>

Inheritance diagram for aspl::VolumeControl:

Public Member Functions
	VolumeControl (std::shared_ptr< const Context > context, const VolumeControlParameters &params={})
	Construct stream.

Getters and setters
virtual AudioObjectPropertyScope	GetScope () const
	Get the scope that the control is attached to. Can return kAudioObjectPropertyScopeInput or kAudioObjectPropertyScopeOutput. By default returns VolumeControlParameters::Scope.

virtual AudioObjectPropertyElement	GetElement () const
	Get the element that the control is attached to. Typically should return kAudioObjectPropertyElementMain. By default returns kAudioObjectPropertyElementMain.

virtual SInt32	GetRawValue () const
	Get current volume, in raw units. Values are in range GetRawRange().

OSStatus	SetRawValue (SInt32 value)
	Set current volume, in raw units. Values are in range GetRawRange(). Invokes by SetRawValueImpl() and NotifyPropertiesChanged().

virtual Float32	GetDecibelValue () const
	Get current volume, in decibel units. Values are in range GetDecibelRange().

virtual OSStatus	SetDecibelValue (Float32 value)
	Get current volume, in decibel units. Values are in range GetDecibelRange(). Invokes by SetRawValue().

virtual Float32	GetScalarValue () const
	Get current volume, in scalar units. Values are in range [0; 1].

virtual OSStatus	SetScalarValue (Float32 value)
	Set current volume, in scalar units. Values are in range [0; 1]. Invokes by SetRawValue().

virtual AudioValueRange	GetRawRange () const
	Get minimum and maximum volume values, in raw units. Default implementation returns range based on VolumeControlParameters.

virtual AudioValueRange	GetDecibelRange () const
	Get minimum and maximum volume values, in decibel units. Default implementation returns range based on VolumeControlParameters.

virtual Float32	ConvertScalarToDecibels (Float32 value) const
	Convert volume from scalar scale to decibel scale. Default implementation performs conversion based on VolumeControlParameters.

virtual Float32	ConvertDecibelsToScalar (Float32 value) const
	Convert volume from decibel scale to scalar scale. Default implementation performs conversion based on VolumeControlParameters.

Processing
virtual void	ApplyProcessing (Float32 *frames, UInt32 frameCount, UInt32 channelCount) const
	Apply processing to given buffer. The provided buffer contains exactly `frameCount` * `channelCount` samples. The provides samples are scalled according to the current GetScalarValue().

Property dispath
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

Object &	operator= (const Object &)=delete

std::shared_ptr< const Context >	GetContext () 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	SetRawValueImpl (SInt32 value)
	Set current volume, in raw units. Values are in range GetRawRange(). Invoked by SetRawValue().

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

Volume control object.

Volumes can be represented using three scales:

raw - integer amplitude amplifier, custom range
decibels - floating point logarithmic scale, custom range
scalar - floating point logarithmic scale, range [0; 1]

Decibels and raw scales are linearly related.

The raw scale is intended for computations. The scalar scale is used by macOS for volume sliders.

Default implementation of VolumeControl stores volumes in the raw scale and convert it on fly to/from other scales when requested.

Volume control does not affect I/O by its own. It just stores the volume and provides ApplyProcessing() method which modifies given samples according to the volume.

You can attach VolumeControl to Stream using Stream::AttachVolumeControl() method, and then stream will use it to process samples passed to stream. Alternatively, you can invoke VolumeControls manually the way you need.

Definition at line 64 of file VolumeControl.hpp.

Constructor & Destructor Documentation

◆ VolumeControl()

aspl::VolumeControl::VolumeControl	(	std::shared_ptr< const Context >	context,
		const VolumeControlParameters &	params = {} )

explicit

Construct stream.

Member Function Documentation

◆ ApplyProcessing()

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

virtual

Apply processing to given buffer. The provided buffer contains exactly frameCount * channelCount samples. The provides samples are scalled according to the current GetScalarValue().

Note: Invoked by Stream::ApplyProcessing() on realtime thread.

◆ ConvertDecibelsToScalar()

virtual Float32 aspl::VolumeControl::ConvertDecibelsToScalar ( Float32 value ) const

virtual

Convert volume from decibel scale to scalar scale. Default implementation performs conversion based on VolumeControlParameters.

Note: Backs kAudioLevelControlPropertyConvertDecibelsToScalar property.

◆ ConvertScalarToDecibels()

virtual Float32 aspl::VolumeControl::ConvertScalarToDecibels ( Float32 value ) const

virtual

Convert volume from scalar scale to decibel scale. Default implementation performs conversion based on VolumeControlParameters.

Note: Backs kAudioLevelControlPropertyConvertScalarToDecibels property.

◆ GetBaseClass()

AudioClassID aspl::VolumeControl::GetBaseClass ( ) const

overridevirtual

Get base class ID.

Reimplemented from aspl::Object.

◆ GetClass()

AudioClassID aspl::VolumeControl::GetClass ( ) const

overridevirtual

Get class ID.

Reimplemented from aspl::Object.

◆ GetDecibelRange()

virtual AudioValueRange aspl::VolumeControl::GetDecibelRange ( ) const

virtual

Get minimum and maximum volume values, in decibel units. Default implementation returns range based on VolumeControlParameters.

Note: Backs kAudioLevelControlPropertyDecibelRange property.

◆ GetDecibelValue()

virtual Float32 aspl::VolumeControl::GetDecibelValue ( ) const

virtual

Get current volume, in decibel units. Values are in range GetDecibelRange().

Note: Backs kAudioLevelControlPropertyDecibelValue property.

◆ GetElement()

virtual AudioObjectPropertyElement aspl::VolumeControl::GetElement ( ) const

virtual

Get the element that the control is attached to. Typically should return kAudioObjectPropertyElementMain. By default returns kAudioObjectPropertyElementMain.

Note: Backs kAudioControlPropertyElement property.

◆ GetPropertyData()

OSStatus aspl::VolumeControl::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::VolumeControl::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.

◆ GetRawRange()

virtual AudioValueRange aspl::VolumeControl::GetRawRange ( ) const

virtual

Get minimum and maximum volume values, in raw units. Default implementation returns range based on VolumeControlParameters.

◆ GetRawValue()

virtual SInt32 aspl::VolumeControl::GetRawValue ( ) const

virtual

Get current volume, in raw units. Values are in range GetRawRange().

◆ GetScalarValue()

virtual Float32 aspl::VolumeControl::GetScalarValue ( ) const

virtual

Get current volume, in scalar units. Values are in range [0; 1].

Note: Backs kAudioLevelControlPropertyScalarValue property.

◆ GetScope()

virtual AudioObjectPropertyScope aspl::VolumeControl::GetScope ( ) const

virtual

Get the scope that the control is attached to. Can return kAudioObjectPropertyScopeInput or kAudioObjectPropertyScopeOutput. By default returns VolumeControlParameters::Scope.

Note: Backs kAudioControlPropertyScope property.

◆ HasProperty()

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

overridevirtual

Check whether given property is present.

Reimplemented from aspl::Object.

◆ IsInstance()

bool aspl::VolumeControl::IsInstance ( AudioClassID classID ) const

overridevirtual

Check if this object is instance of given base class.

Reimplemented from aspl::Object.

◆ IsPropertySettable()

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

overridevirtual

Check whether given property can be changed.

Reimplemented from aspl::Object.

◆ SetDecibelValue()

virtual OSStatus aspl::VolumeControl::SetDecibelValue ( Float32 value )

virtual

Get current volume, in decibel units. Values are in range GetDecibelRange(). Invokes by SetRawValue().

Note: Backs kAudioLevelControlPropertyDecibelValue property.

◆ SetPropertyData()

OSStatus aspl::VolumeControl::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.

◆ SetRawValue()

OSStatus aspl::VolumeControl::SetRawValue ( SInt32 value )

Set current volume, in raw units. Values are in range GetRawRange(). Invokes by SetRawValueImpl() and NotifyPropertiesChanged().

◆ SetRawValueImpl()

virtual OSStatus aspl::VolumeControl::SetRawValueImpl ( SInt32 value )

protectedvirtual

Set current volume, in raw units. Values are in range GetRawRange(). Invoked by SetRawValue().

◆ SetScalarValue()

virtual OSStatus aspl::VolumeControl::SetScalarValue ( Float32 value )

virtual

Set current volume, in scalar units. Values are in range [0; 1]. Invokes by SetRawValue().

Note: Backs kAudioLevelControlPropertyScalarValue property.

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

aspl/VolumeControl.hpp

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ VolumeControl()

Member Function Documentation

◆ ApplyProcessing()

◆ ConvertDecibelsToScalar()

◆ ConvertScalarToDecibels()

◆ GetBaseClass()

◆ GetClass()

◆ GetDecibelRange()

◆ GetDecibelValue()

◆ GetElement()

◆ GetPropertyData()

◆ GetPropertyDataSize()

◆ GetRawRange()

◆ GetRawValue()

◆ GetScalarValue()

◆ GetScope()

◆ HasProperty()

◆ IsInstance()

◆ IsPropertySettable()

◆ SetDecibelValue()

◆ SetPropertyData()

◆ SetRawValue()

◆ SetRawValueImpl()

◆ SetScalarValue()