Screensaver

Detailed Description

Class: kodi::addon::CInstanceScreensaver

Screensaver add-on instance

A screensaver is a Kodi addon that fills the screen with moving images or patterns when the computer is not in use. Initially designed to prevent phosphor burn-in on CRT and plasma computer monitors (hence the name), screensavers are now used primarily for entertainment, security or to display system status information.

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

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

The interface is small and easy usable. It has three functions:

• Start() - Called on creation
• Render() - Called at render time
• Stop() - Called when the screensaver has no work

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 what the addon.xml.in would look like for an screensaver addon:

<?xml version="1.0" encoding="UTF-8"?>
<addon
  id="screensaver.myspecialnamefor"
  version="1.0.0"
  name="My special screensaver addon"
  provider-name="Your Name">
  <requires>@ADDON_DEPENDS@</requires>
  <extension
    point="xbmc.ui.screensaver"
    library_@PLATFORM@="@LIBRARY_FILENAME@"/>
  <extension point="xbmc.addon.metadata">
    <summary lang="en_GB">My screensaver addon</summary>
    <description lang="en_GB">My screensaver addon description</description>
    <platform>@PLATFORM@</platform>
  </extension>
</addon>

Description to screensaver related addon.xml values:

Name	Description
point	Addon type specification At all addon types and for this kind always "xbmc.ui.screensaver".
library_@PLATFORM@	Sets the used library name, which is automatically set by cmake at addon build.

Remarks

For more detailed description of the addon.xml, see also https://kodi.wiki/view/Addon.xml.

---

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

#include <kodi/addon-instance/Screensaver.h>
 
class CMyScreenSaver : public kodi::addon::CAddonBase,
                       public kodi::addon::CInstanceScreensaver
{
public:
  CMyScreenSaver();
 
  bool Start() override;
  void Render() override;
};
 
CMyScreenSaver::CMyScreenSaver()
{
  ...
}
 
bool CMyScreenSaver::Start()
{
  ...
  return true;
}
 
void CMyScreenSaver::Render()
{
  ...
}
 
ADDONCREATOR(CMyScreenSaver)

---

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

#include <kodi/addon-instance/Screensaver.h>
 
class CMyScreenSaver : public kodi::addon::CInstanceScreensaver
{
public:
  CMyScreenSaver(KODI_HANDLE instance, const std::string& version);
 
  bool Start() override;
  void Render() override;
};
 
CMyScreenSaver::CMyScreenSaver(KODI_HANDLE instance, const std::string& version)
  : CInstanceScreensaver(instance, version)
{
  ...
}
 
bool CMyScreenSaver::Start()
{
  ...
  return true;
}
 
void CMyScreenSaver::Render()
{
  ...
}
 
 
//----------------------------------------------------------------------
 
class CMyAddon : public kodi::addon::CAddonBase
{
public:
  CMyAddon() = default;
  ADDON_STATUS CreateInstance(int instanceType,
                              const std::string& instanceID,
                              KODI_HANDLE instance,
                              const std::string& version,
                              KODI_HANDLE& addonInstance) override;
};
 
// If you use only one instance in your add-on, can be instanceType and
// instanceID ignored
ADDON_STATUS CMyAddon::CreateInstance(int instanceType,
                                      const std::string& instanceID,
                                      KODI_HANDLE instance,
                                      const std::string& version,
                                      KODI_HANDLE& addonInstance)
{
  if (instanceType == ADDON_INSTANCE_SCREENSAVER)
  {
    kodi::Log(ADDON_LOG_INFO, "Creating my Screensaver");
    addonInstance = new CMyScreenSaver(instance, version);
    return ADDON_STATUS_OK;
  }
  else if (...)
  {
    ...
  }
  return ADDON_STATUS_UNKNOWN;
}
 
ADDONCREATOR(CMyAddon)

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

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

Function Documentation

CInstanceScreensaver() [1/2]

CInstanceScreensaver ( )

inline

Screensaver class constructor.

Used by an add-on that only supports screensavers.

CInstanceScreensaver() [2/2]

CInstanceScreensaver ( KODI_HANDLE  instance, const std::string &  kodiVersion = ""  )

inlineexplicit

Screensaver class constructor used to support multiple instance types.

Parameters

[in]	instance	The instance value given to kodi::addon::CAddonBase::CreateInstance(...).
[in]	kodiVersion	[opt] Version used in Kodi for this instance, to allow compatibility to older Kodi versions.

Note

Recommended to set kodiVersion.

---

Here's example about the use of this:

class CMyScreenSaver : public kodi::addon::CInstanceScreensaver
{
public:
  CMyScreenSaver(KODI_HANDLE instance, const std::string& kodiVersion)
    : kodi::addon::CInstanceScreensaver(instance, kodiVersion)
  {
     ...
  }
 
  ...
};
 
ADDON_STATUS CMyAddon::CreateInstance(int instanceType,
                                      const std::string& instanceID,
                                      KODI_HANDLE instance,
                                      const std::string& version,
                                      KODI_HANDLE& addonInstance)
{
  kodi::Log(ADDON_LOG_INFO, "Creating my screensaver");
  addonInstance = new CMyScreenSaver(instance, version);
  return ADDON_STATUS_OK;
}

~CInstanceScreensaver()

~CInstanceScreensaver ( )

overridedefault

Destructor.

Start()

virtual bool Start ( )

inlinevirtual

Used to notify the screensaver that it has been started.

Returns

true if the screensaver was started successfully, false otherwise

Stop()

virtual void Stop ( )

inlinevirtual

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

Render()

virtual void Render ( )

inlinevirtual

Used to indicate when the add-on should render.