summaryrefslogtreecommitdiffstats
path: root/xbmc/addons/kodi-addon-dev-kit/include/kodi/addon-instance/Screensaver.h
diff options
context:
space:
mode:
Diffstat (limited to 'xbmc/addons/kodi-addon-dev-kit/include/kodi/addon-instance/Screensaver.h')
-rw-r--r--xbmc/addons/kodi-addon-dev-kit/include/kodi/addon-instance/Screensaver.h460
1 files changed, 0 insertions, 460 deletions
diff --git a/xbmc/addons/kodi-addon-dev-kit/include/kodi/addon-instance/Screensaver.h b/xbmc/addons/kodi-addon-dev-kit/include/kodi/addon-instance/Screensaver.h
deleted file mode 100644
index f8a7380..0000000
--- a/xbmc/addons/kodi-addon-dev-kit/include/kodi/addon-instance/Screensaver.h
+++ /dev/null
@@ -1,460 +0,0 @@
1/*
2 * Copyright (C) 2005-2018 Team Kodi
3 * This file is part of Kodi - https://kodi.tv
4 *
5 * SPDX-License-Identifier: GPL-2.0-or-later
6 * See LICENSES/README.md for more information.
7 */
8
9#pragma once
10
11#include "../AddonBase.h"
12#include "../gui/renderHelper.h"
13
14namespace kodi { namespace addon { class CInstanceScreensaver; }}
15
16extern "C"
17{
18
19struct AddonInstance_Screensaver;
20
21/*!
22 * @brief Screensaver properties
23 *
24 * Not to be used outside this header.
25 */
26typedef struct AddonProps_Screensaver
27{
28 void *device;
29 int x;
30 int y;
31 int width;
32 int height;
33 float pixelRatio;
34 const char *name;
35 const char *presets;
36 const char *profile;
37} AddonProps_Screensaver;
38
39/*!
40 * @brief Screensaver callbacks
41 *
42 * Not to be used outside this header.
43 */
44typedef struct AddonToKodiFuncTable_Screensaver
45{
46 KODI_HANDLE kodiInstance;
47} AddonToKodiFuncTable_Screensaver;
48
49/*!
50 * @brief Screensaver function hooks
51 *
52 * Not to be used outside this header.
53 */
54typedef struct KodiToAddonFuncTable_Screensaver
55{
56 kodi::addon::CInstanceScreensaver* addonInstance;
57 bool (__cdecl* Start) (AddonInstance_Screensaver* instance);
58 void (__cdecl* Stop) (AddonInstance_Screensaver* instance);
59 void (__cdecl* Render) (AddonInstance_Screensaver* instance);
60} KodiToAddonFuncTable_Screensaver;
61
62/*!
63 * @brief Screensaver instance
64 *
65 * Not to be used outside this header.
66 */
67typedef struct AddonInstance_Screensaver
68{
69 AddonProps_Screensaver props;
70 AddonToKodiFuncTable_Screensaver toKodi;
71 KodiToAddonFuncTable_Screensaver toAddon;
72} AddonInstance_Screensaver;
73
74} /* extern "C" */
75
76namespace kodi
77{
78namespace addon
79{
80
81 //============================================================================
82 ///
83 /// \addtogroup cpp_kodi_addon_screensaver
84 /// @brief \cpp_class{ kodi::addon::CInstanceScreensaver }
85 /// **Screensaver add-on instance**
86 ///
87 /// A screensaver is a Kodi addon that fills the screen with moving images or
88 /// patterns when the computer is not in use. Initially designed to prevent
89 /// phosphor burn-in on CRT and plasma computer monitors (hence the name),
90 /// screensavers are now used primarily for entertainment, security or to
91 /// display system status information.
92 ///
93 /// Include the header \ref ScreenSaver.h "#include <kodi/addon-instance/ScreenSaver.h>"
94 /// to use this class.
95 ///
96 /// This interface allows the creating of screensavers for Kodi, based upon
97 /// **DirectX** or/and **OpenGL** rendering with `C++` code.
98 ///
99 /// The interface is small and easy usable. It has three functions:
100 ///
101 /// * <b><c>Start()</c></b> - Called on creation
102 /// * <b><c>Render()</c></b> - Called at render time
103 /// * <b><c>Stop()</c></b> - Called when the screensaver has no work
104 ///
105 /// Additionally, there are several \ref cpp_kodi_addon_screensaver_CB "other functions"
106 /// available in which the child class can ask about the current hardware,
107 /// including the device, display and several other parts.
108 ///
109 ///
110 /// --------------------------------------------------------------------------
111 ///
112 ///
113 /// **Here is an example of the minimum required code to start a screensaver:**
114 /// ~~~~~~~~~~~~~{.cpp}
115 /// #include <kodi/addon-instance/Screensaver.h>
116 ///
117 /// class CMyScreenSaver : public kodi::addon::CAddonBase,
118 /// public kodi::addon::CInstanceScreensaver
119 /// {
120 /// public:
121 /// CMyScreenSaver();
122 ///
123 /// bool Start() override;
124 /// void Render() override;
125 /// };
126 ///
127 /// CMyScreenSaver::CMyScreenSaver()
128 /// {
129 /// ...
130 /// }
131 ///
132 /// bool CMyScreenSaver::Start()
133 /// {
134 /// ...
135 /// return true;
136 /// }
137 ///
138 /// void CMyScreenSaver::Render()
139 /// {
140 /// ...
141 /// }
142 ///
143 /// ADDONCREATOR(CMyScreenSaver)
144 /// ~~~~~~~~~~~~~
145 ///
146 ///
147 /// --------------------------------------------------------------------------
148 ///
149 ///
150 /// **Here is another example where the screensaver is used together with
151 /// other instance types:**
152 ///
153 /// ~~~~~~~~~~~~~{.cpp}
154 /// #include <kodi/addon-instance/Screensaver.h>
155 ///
156 /// class CMyScreenSaver : public ::kodi::addon::CInstanceScreensaver
157 /// {
158 /// public:
159 /// CMyScreenSaver(KODI_HANDLE instance);
160 ///
161 /// bool Start() override;
162 /// void Render() override;
163 /// };
164 ///
165 /// CMyScreenSaver::CMyScreenSaver(KODI_HANDLE instance)
166 /// : CInstanceScreensaver(instance)
167 /// {
168 /// ...
169 /// }
170 ///
171 /// bool CMyScreenSaver::Start()
172 /// {
173 /// ...
174 /// return true;
175 /// }
176 ///
177 /// void CMyScreenSaver::Render()
178 /// {
179 /// ...
180 /// }
181 ///
182 ///
183 /// /*----------------------------------------------------------------------*/
184 ///
185 /// class CMyAddon : public ::kodi::addon::CAddonBase
186 /// {
187 /// public:
188 /// CMyAddon() { }
189 /// ADDON_STATUS CreateInstance(int instanceType,
190 /// std::string instanceID,
191 /// KODI_HANDLE instance,
192 /// KODI_HANDLE& addonInstance) override;
193 /// };
194 ///
195 /// /* If you use only one instance in your add-on, can be instanceType and
196 /// * instanceID ignored */
197 /// ADDON_STATUS CMyAddon::CreateInstance(int instanceType,
198 /// std::string instanceID,
199 /// KODI_HANDLE instance,
200 /// KODI_HANDLE& addonInstance)
201 /// {
202 /// if (instanceType == ADDON_INSTANCE_SCREENSAVER)
203 /// {
204 /// kodi::Log(ADDON_LOG_NOTICE, "Creating my Screensaver");
205 /// addonInstance = new CMyScreenSaver(instance);
206 /// return ADDON_STATUS_OK;
207 /// }
208 /// else if (...)
209 /// {
210 /// ...
211 /// }
212 /// return ADDON_STATUS_UNKNOWN;
213 /// }
214 ///
215 /// ADDONCREATOR(CMyAddon)
216 /// ~~~~~~~~~~~~~
217 ///
218 /// The destruction of the example class `CMyScreenSaver` is called from
219 /// Kodi's header. Manually deleting the add-on instance is not required.
220 ///
221 //----------------------------------------------------------------------------
222 class ATTRIBUTE_HIDDEN CInstanceScreensaver : public IAddonInstance
223 {
224 public:
225 //==========================================================================
226 ///
227 /// @ingroup cpp_kodi_addon_screensaver
228 /// @brief Screensaver class constructor
229 ///
230 /// Used by an add-on that only supports screensavers.
231 ///
232 CInstanceScreensaver()
233 : IAddonInstance(ADDON_INSTANCE_SCREENSAVER, GetKodiTypeVersion(ADDON_INSTANCE_SCREENSAVER))
234 {
235 if (CAddonBase::m_interface->globalSingleInstance != nullptr)
236 throw std::logic_error("kodi::addon::CInstanceScreensaver: Creation of more as one in single instance way is not allowed!");
237
238 SetAddonStruct(CAddonBase::m_interface->firstKodiInstance);
239 CAddonBase::m_interface->globalSingleInstance = this;
240 }
241 //--------------------------------------------------------------------------
242
243 //==========================================================================
244 ///
245 /// @ingroup cpp_kodi_addon_screensaver
246 /// @brief Screensaver class constructor used to support multiple instance
247 /// types
248 ///
249 /// @param[in] instance The instance value given to
250 /// <b>`kodi::addon::CAddonBase::CreateInstance(...)`</b>.
251 /// @param[in] kodiVersion [opt] Version used in Kodi for this instance, to
252 /// allow compatibility to older Kodi versions.
253 /// @note Recommended to set.
254 ///
255 /// @warning Only use `instance` from the CreateInstance call
256 ///
257 explicit CInstanceScreensaver(KODI_HANDLE instance, const std::string& kodiVersion = "")
258 : IAddonInstance(ADDON_INSTANCE_SCREENSAVER,
259 !kodiVersion.empty() ? kodiVersion
260 : GetKodiTypeVersion(ADDON_INSTANCE_SCREENSAVER))
261 {
262 if (CAddonBase::m_interface->globalSingleInstance != nullptr)
263 throw std::logic_error("kodi::addon::CInstanceScreensaver: Creation of multiple together with single instance way is not allowed!");
264
265 SetAddonStruct(instance);
266 }
267 //--------------------------------------------------------------------------
268
269 //==========================================================================
270 ///
271 /// @ingroup cpp_kodi_addon_screensaver
272 /// @brief Destructor
273 ///
274 ~CInstanceScreensaver() override = default;
275 //--------------------------------------------------------------------------
276
277 //==========================================================================
278 ///
279 /// @ingroup cpp_kodi_addon_screensaver
280 /// @brief Used to notify the screensaver that it has been started
281 ///
282 /// @return true if the screensaver was started
283 /// successfully, false otherwise
284 ///
285 virtual bool Start() { return true; }
286 //--------------------------------------------------------------------------
287
288 //==========================================================================
289 ///
290 /// @ingroup cpp_kodi_addon_screensaver
291 /// @brief Used to inform the screensaver that the rendering control was
292 /// stopped
293 ///
294 virtual void Stop() {}
295 //--------------------------------------------------------------------------
296
297 //==========================================================================
298 ///
299 /// @ingroup cpp_kodi_addon_screensaver
300 /// @brief Used to indicate when the add-on should render
301 ///
302 virtual void Render() {}
303 //--------------------------------------------------------------------------
304
305 //==========================================================================
306 ///
307 /// \defgroup cpp_kodi_addon_screensaver_CB Information functions
308 /// \ingroup cpp_kodi_addon_screensaver
309 /// @brief **To get info about the device, display and several other parts**
310 ///
311 //@{
312
313 //==========================================================================
314 ///
315 /// @ingroup cpp_kodi_addon_screensaver_CB
316 /// @brief Device that represents the display adapter
317 ///
318 /// @return A pointer to the device
319 ///
320 /// @note This is only available on **DirectX**, It us unused (`nullptr`) on
321 /// **OpenGL**
322 ///
323 inline void* Device() { return m_instanceData->props.device; }
324 //--------------------------------------------------------------------------
325
326 //==========================================================================
327 ///
328 /// @ingroup cpp_kodi_addon_screensaver_CB
329 /// @brief Returns the X position of the rendering window
330 ///
331 /// @return The X position, in pixels
332 ///
333 inline int X() { return m_instanceData->props.x; }
334 //--------------------------------------------------------------------------
335
336 //==========================================================================
337 ///
338 /// @ingroup cpp_kodi_addon_screensaver_CB
339 /// @brief Returns the Y position of the rendering window
340 ///
341 /// @return The Y position, in pixels
342 ///
343 inline int Y() { return m_instanceData->props.y; }
344 //--------------------------------------------------------------------------
345
346 //==========================================================================
347 ///
348 /// @ingroup cpp_kodi_addon_screensaver_CB
349 /// @brief Returns the width of the rendering window
350 ///
351 /// @return The width, in pixels
352 ///
353 inline int Width() { return m_instanceData->props.width; }
354 //--------------------------------------------------------------------------
355
356 //==========================================================================
357 ///
358 /// @ingroup cpp_kodi_addon_screensaver_CB
359 /// @brief Returns the height of the rendering window
360 ///
361 /// @return The height, in pixels
362 ///
363 inline int Height() { return m_instanceData->props.height; }
364 //--------------------------------------------------------------------------
365
366 //==========================================================================
367 ///
368 /// @ingroup cpp_kodi_addon_screensaver_CB
369 /// @brief Pixel aspect ratio (often abbreviated PAR) is a ratio that
370 /// describes how the width of a pixel compares to the height of that pixel.
371 ///
372 /// @return The pixel aspect ratio used by the display
373 ///
374 inline float PixelRatio() { return m_instanceData->props.pixelRatio; }
375 //--------------------------------------------------------------------------
376
377 //==========================================================================
378 ///
379 /// @ingroup cpp_kodi_addon_screensaver_CB
380 /// @brief Used to get the name of the add-on defined in `addon.xml`
381 ///
382 /// @return The add-on name
383 ///
384 inline std::string Name() { return m_instanceData->props.name; }
385 //--------------------------------------------------------------------------
386
387 //==========================================================================
388 ///
389 /// @ingroup cpp_kodi_addon_screensaver_CB
390 /// @brief Used to get the full path where the add-on is installed
391 ///
392 /// @return The add-on installation path
393 ///
394 inline std::string Presets() { return m_instanceData->props.presets; }
395 //--------------------------------------------------------------------------
396
397 //==========================================================================
398 ///
399 /// @ingroup cpp_kodi_addon_screensaver_CB
400 /// @brief Used to get the full path to the add-on's user profile
401 ///
402 /// @note The trailing folder (consisting of the add-on's ID) is not created
403 /// by default. If it is needed, you must call kodi::vfs::CreateDirectory()
404 /// to create the folder.
405 ///
406 /// @return Path to the user profile
407 ///
408 inline std::string Profile() { return m_instanceData->props.profile; }
409 //--------------------------------------------------------------------------
410 //@}
411
412 private:
413 void SetAddonStruct(KODI_HANDLE instance)
414 {
415 if (instance == nullptr)
416 throw std::logic_error("kodi::addon::CInstanceScreensaver: Creation with empty addon structure not allowed, table must be given from Kodi!");
417
418 m_instanceData = static_cast<AddonInstance_Screensaver*>(instance);
419 m_instanceData->toAddon.addonInstance = this;
420 m_instanceData->toAddon.Start = ADDON_Start;
421 m_instanceData->toAddon.Stop = ADDON_Stop;
422 m_instanceData->toAddon.Render = ADDON_Render;
423 }
424
425 inline static bool ADDON_Start(AddonInstance_Screensaver* instance)
426 {
427 instance->toAddon.addonInstance->m_renderHelper = kodi::gui::GetRenderHelper();
428 return instance->toAddon.addonInstance->Start();
429 }
430
431 inline static void ADDON_Stop(AddonInstance_Screensaver* instance)
432 {
433 instance->toAddon.addonInstance->Stop();
434 instance->toAddon.addonInstance->m_renderHelper = nullptr;
435 }
436
437 inline static void ADDON_Render(AddonInstance_Screensaver* instance)
438 {
439 if (!instance->toAddon.addonInstance->m_renderHelper)
440 return;
441 instance->toAddon.addonInstance->m_renderHelper->Begin();
442 instance->toAddon.addonInstance->Render();
443 instance->toAddon.addonInstance->m_renderHelper->End();
444 }
445
446 /*
447 * Background render helper holds here and in addon base.
448 * In addon base also to have for the others, and stored here for the worst
449 * case where this class is independent from base and base becomes closed
450 * before.
451 *
452 * This is on Kodi with GL unused and the calls to there are empty (no work)
453 * On Kodi with Direct X where angle is present becomes this used.
454 */
455 std::shared_ptr<kodi::gui::IRenderHelper> m_renderHelper;
456 AddonInstance_Screensaver* m_instanceData;
457 };
458
459} /* namespace addon */
460} /* namespace kodi */
generated by cgit v1.2.3 (git 2.25.1) at 2026-01-12 05:28:36 +0000