\cpp_class{ kodi::addon::CInstanceVisualization } Visualization add-on instance More...

Modules
	class VisTrack
	Visualization track information structure

	Information functions
	To get info about the device, display and several other parts

Functions
	kodi::addon::CInstanceVisualization::CInstanceVisualization ()
	Visualization class constructor. More...

	kodi::addon::CInstanceVisualization::CInstanceVisualization (KODI_HANDLE instance)
	Visualization class constructor used to support multiple instance types. More...

	kodi::addon::CInstanceVisualization::~CInstanceVisualization () override=default
	Destructor. More...

virtual bool	kodi::addon::CInstanceVisualization::Start (int channels, int samplesPerSec, int bitsPerSample, std::string songName)
	Used to notify the visualization that a new song has been started. More...

virtual void	kodi::addon::CInstanceVisualization::Stop ()
	Used to inform the visualization that the rendering control was stopped. More...

virtual void	kodi::addon::CInstanceVisualization::AudioData (const float audioData, int audioDataLength, float freqData, int freqDataLength)
	Pass audio data to the visualization. More...

virtual bool	kodi::addon::CInstanceVisualization::IsDirty ()
	Used to inform Kodi that the rendered region is dirty and need an update. More...

virtual void	kodi::addon::CInstanceVisualization::Render ()
	Used to indicate when the add-on should render. More...

virtual void	kodi::addon::CInstanceVisualization::GetInfo (bool &wantsFreq, int &syncDelay)
	Used to get the number of buffers from the current visualization. More...

virtual bool	kodi::addon::CInstanceVisualization::GetPresets (std::vector< std::string > &presets)
	Used to get a list of visualization presets the user can select from. More...

virtual int	kodi::addon::CInstanceVisualization::GetActivePreset ()
	Get the index of the current preset. More...

virtual bool	kodi::addon::CInstanceVisualization::IsLocked ()
	Check if the add-on is locked to the current preset. More...

virtual bool	kodi::addon::CInstanceVisualization::PrevPreset ()
	Load the previous visualization preset. More...

virtual bool	kodi::addon::CInstanceVisualization::NextPreset ()
	Load the next visualization preset. More...

virtual bool	kodi::addon::CInstanceVisualization::LoadPreset (int select)
	Load a visualization preset. More...

virtual bool	kodi::addon::CInstanceVisualization::RandomPreset ()
	Switch to a new random preset. More...

virtual bool	kodi::addon::CInstanceVisualization::LockPreset (bool lockUnlock)
	Lock the current visualization preset, preventing it from changing. More...

virtual bool	kodi::addon::CInstanceVisualization::RatePreset (bool plusMinus)
	Used to increase/decrease the visualization preset rating. More...

virtual bool	kodi::addon::CInstanceVisualization::UpdateAlbumart (std::string albumart)
	Inform the visualization of the current album art image. More...

virtual bool	kodi::addon::CInstanceVisualization::UpdateTrack (const VisTrack &track)
	Inform the visualization of the current track's tag information. More...

Detailed Description

\cpp_class{ kodi::addon::CInstanceVisualization } Visualization add-on instance

Music visualization, or music visualisation, is a feature in Kodi that generates animated imagery based on a piece of music. The imagery is usually generated and rendered in real time synchronized to the music.

Visualization techniques range from simple ones (e.g., a simulation of an oscilloscope display) to elaborate ones, which often include a plurality of composited effects. The changes in the music's loudness and frequency spectrum are among the properties used as input to the visualization.

Include the header #include <kodi/addon-instance/Visualization.h> to use this class.

This interface allows the creation of visualizations for Kodi, based upon DirectX or/and OpenGL rendering with C++ code.

Additionally, there are several other functions available in which the child class can ask about the current hardware, including the device, display and several other parts.

Here is an example of the minimum required code to start a visualization:

#include <kodi/addon-instance/Visualization.h>
 
class CMyVisualization : public kodi::addon::CAddonBase,
                         public kodi::addon::CInstanceVisualization
{
public:
  CMyVisualization();
 
  bool Start(int channels, int samplesPerSec, int bitsPerSample, std::string songName) override;
  void AudioData(const float* audioData, int audioDataLength, float* freqData, int freqDataLength) override;
  void Render() override;
};
 
CMyVisualization::CMyVisualization()
{
  ...
}
 
bool CMyVisualization::Start(int channels, int samplesPerSec, int bitsPerSample, std::string songName)
{
  ...
  return true;
}
 
void CMyVisualization::AudioData(const float* audioData, int audioDataLength, float* freqData, int freqDataLength)
{
  ...
}
 
void CMyVisualization::Render()
{
  ...
}
 
ADDONCREATOR(CMyVisualization)

Here is another example where the visualization is used together with other instance types:

#include <kodi/addon-instance/Visualization.h>
 
class CMyVisualization : public ::kodi::addon::CInstanceVisualization
{
public:
  CMyVisualization(KODI_HANDLE instance);
 
  bool Start(int channels, int samplesPerSec, int bitsPerSample, std::string songName) override;
  void AudioData(const float* audioData, int audioDataLength, float* freqData, int freqDataLength) override;
  void Render() override;
};
 
CMyVisualization::CMyVisualization(KODI_HANDLE instance)
  : CInstanceVisualization(instance)
{
  ...
}
 
bool CMyVisualization::Start(int channels, int samplesPerSec, int bitsPerSample, std::string songName)
{
  ...
  return true;
}
 
void CMyVisualization::AudioData(const float* audioData, int audioDataLength, float* freqData, int freqDataLength)
{
  ...
}
 
void CMyVisualization::Render()
{
  ...
}
 
 
/*----------------------------------------------------------------------*&zwj;/
 
class CMyAddon : public ::kodi::addon::CAddonBase
{
public:
  CMyAddon() { }
  ADDON_STATUS CreateInstance(int instanceType,
                              std::string instanceID,
                              KODI_HANDLE instance,
                              KODI_HANDLE& addonInstance) override;
};
 
/* If you use only one instance in your add-on, can be instanceType and
 * instanceID ignored *&zwj;/
ADDON_STATUS CMyAddon::CreateInstance(int instanceType,
                                      std::string instanceID,
                                      KODI_HANDLE instance,
                                      KODI_HANDLE& addonInstance)
{
  if (instanceType == ADDON_INSTANCE_VISUALIZATION)
  {
    kodi::Log(ADDON_LOG_NOTICE, "Creating my Visualization");
    addonInstance = new CMyVisualization(instance);
    return ADDON_STATUS_OK;
  }
  else if (...)
  {
    ...
  }
  return ADDON_STATUS_UNKNOWN;
}
 
ADDONCREATOR(CMyAddon)

The destruction of the example class CMyVisualization is called from Kodi's header. Manually deleting the add-on instance is not required.

Function Documentation

◆ AudioData()

virtual void kodi::addon::CInstanceVisualization::AudioData	(	const float *	audioData,
		int	audioDataLength,
		float *	freqData,
		int	freqDataLength
	)

inlinevirtual

Pass audio data to the visualization.

Parameters

[in]	audioData	The raw audio data
[in]	audioDataLength	Length of the audioData array
[in]	freqData	The FFT of the audio data
[in]	freqDataLength	Length of frequency data array

Values freqData and freqDataLength are used if GetInfo() returns true for the wantsFreq parameter. Otherwise, freqData is set to nullptr and freqDataLength is 0.

◆ CInstanceVisualization() [1/2]

kodi::addon::CInstanceVisualization::CInstanceVisualization ( )

inline

Visualization class constructor.

Used by an add-on that only supports visualizations.

◆ CInstanceVisualization() [2/2]

kodi::addon::CInstanceVisualization::CInstanceVisualization ( KODI_HANDLE instance )

inlineexplicit

Visualization class constructor used to support multiple instance types.

Parameters

[in] instance The instance value given to kodi::addon::CAddonBase::CreateInstance(...).

Warning: Only use instance from the CreateInstance call

◆ GetActivePreset()

virtual int kodi::addon::CInstanceVisualization::GetActivePreset ( )

inlinevirtual

Get the index of the current preset.

Returns: Index number of the current preset

◆ GetInfo()

virtual void kodi::addon::CInstanceVisualization::GetInfo	(	bool &	wantsFreq,
		int &	syncDelay
	)

inlinevirtual

Used to get the number of buffers from the current visualization.

Parameters

[out]	wantsFreq	Indicates whether the add-on wants FFT data. If set to true, the freqData and freqDataLength parameters of AudioData() are used
[out]	syncDelay	The number of buffers to delay before calling AudioData()

Note: If this function is not implemented, it will default to wantsFreq = false and syncDelay = 0.

◆ GetPresets()

virtual bool kodi::addon::CInstanceVisualization::GetPresets ( std::vector< std::string > & presets )

inlinevirtual

Used to get a list of visualization presets the user can select from.

Parameters

[out] presets The vector list containing the names of presets that the user can select

Returns: Return true if successful, or false if there are no presets to choose from

◆ IsDirty()

virtual bool kodi::addon::CInstanceVisualization::IsDirty ( )

inlinevirtual

Used to inform Kodi that the rendered region is dirty and need an update.

Returns: True if dirty

◆ IsLocked()

virtual bool kodi::addon::CInstanceVisualization::IsLocked ( )

inlinevirtual

Check if the add-on is locked to the current preset.

Returns: True if locked to the current preset

◆ LoadPreset()

virtual bool kodi::addon::CInstanceVisualization::LoadPreset ( int select )

inlinevirtual

Load a visualization preset.

This function is called after a new preset is selected.

Parameters

[in] select Preset index to use

Returns: Return true if the preset is loaded

◆ LockPreset()

virtual bool kodi::addon::CInstanceVisualization::LockPreset ( bool lockUnlock )

inlinevirtual

Lock the current visualization preset, preventing it from changing.

Parameters

[in] lockUnlock If set to true, the preset should be locked

Returns: Return true if the current preset is locked

◆ NextPreset()

virtual bool kodi::addon::CInstanceVisualization::NextPreset ( )

inlinevirtual

Load the next visualization preset.

Returns: Return true if the next preset was loaded

◆ PrevPreset()

virtual bool kodi::addon::CInstanceVisualization::PrevPreset ( )

inlinevirtual

Load the previous visualization preset.

Returns: Return true if the previous preset was loaded

◆ RandomPreset()

virtual bool kodi::addon::CInstanceVisualization::RandomPreset ( )

inlinevirtual

Switch to a new random preset.

Returns: Return true if a random preset was loaded

◆ RatePreset()

virtual bool kodi::addon::CInstanceVisualization::RatePreset ( bool plusMinus )

inlinevirtual

Used to increase/decrease the visualization preset rating.

Parameters

[in] plusMinus If set to true the rating is increased, otherwise decreased

Returns: Return true if the rating is modified

◆ Render()

virtual void kodi::addon::CInstanceVisualization::Render ( void )

inlinevirtual

Used to indicate when the add-on should render.

◆ Start()

virtual bool kodi::addon::CInstanceVisualization::Start	(	int	channels,
		int	samplesPerSec,
		int	bitsPerSample,
		std::string	songName
	)

inlinevirtual

Used to notify the visualization that a new song has been started.

Parameters

[in]	channels	Number of channels in the stream
[in]	samplesPerSec	Samples per second of stream
[in]	bitsPerSample	Number of bits in one sample
[in]	songName	The name of the currently-playing song

Returns: true if start successful done

◆ Stop()

virtual void kodi::addon::CInstanceVisualization::Stop ( )

inlinevirtual

Used to inform the visualization that the rendering control was stopped.

◆ UpdateAlbumart()

virtual bool kodi::addon::CInstanceVisualization::UpdateAlbumart ( std::string albumart )

inlinevirtual

Inform the visualization of the current album art image.

Parameters

[in] albumart Path to the current album art image

Returns: Return true if the image is used

◆ UpdateTrack()

virtual bool kodi::addon::CInstanceVisualization::UpdateTrack ( const VisTrack & track )

inlinevirtual

Inform the visualization of the current track's tag information.

Parameters

[in] track Visualization track information structure

Returns: Return true if the track information is used

◆ ~CInstanceVisualization()

kodi::addon::CInstanceVisualization::~CInstanceVisualization ( )

overridedefault

Destructor.

Modules

Functions

Detailed Description

Function Documentation

◆ AudioData()

◆ CInstanceVisualization() [1/2]

◆ CInstanceVisualization() [2/2]

◆ GetActivePreset()

◆ GetInfo()

◆ GetPresets()

◆ IsDirty()

◆ IsLocked()

◆ LoadPreset()

◆ LockPreset()

◆ NextPreset()

◆ PrevPreset()

◆ RandomPreset()

◆ RatePreset()

◆ Render()

◆ Start()

◆ Stop()

◆ UpdateAlbumart()

◆ UpdateTrack()

◆ ~CInstanceVisualization()