KDEGames

kgamerenderer.h
1 /*
2  SPDX-FileCopyrightText: 2010-2012 Stefan Majewsky <majewsky@gmx.net>
3 
4  SPDX-License-Identifier: LGPL-2.0-only
5 */
6 
7 #ifndef KGAMERENDERER_H
8 #define KGAMERENDERER_H
9 
10 // own
11 #include "kdegames_export.h"
12 // Qt
13 #include <QHash>
14 #include <QObject>
15 #include <QPixmap>
16 // Std
17 #include <memory>
18 
19 class KGameRendererPrivate;
21 class KGameRendererClientPrivate;
22 class KGameTheme;
23 class KGameThemeProvider;
24 
25 #ifndef KDEGAMES_QCOLOR_QHASH
26 #define KDEGAMES_QCOLOR_QHASH
27 inline uint qHash(const QColor &color)
28 {
29  return color.rgba();
30 }
31 #endif // KDEGAMES_QCOLOR_QHASH
32 
33 /**
34  * @class KGameRenderer kgamerenderer.h <KGameRenderer>
35  * @short Cache-enabled rendering of SVG themes.
36  *
37  * KGameRenderer is a light-weight rendering framework for the rendering of
38  * SVG themes (as represented by KGameTheme) into pixmap caches.
39  *
40  * @section terminology Terminology
41  *
42  * @li Themes in the context of KGameRenderer are KGameTheme instances. The theme
43  * selection by a KGameRenderer can be managed by a KGameThemeProvider.
44  * @li A sprite is either a single pixmap ("non-animated sprites") or a sequence
45  * of pixmaps which are shown consecutively to produce an animation
46  * ("animated sprites"). Non-animated sprites correspond to a single element
47  * with the same key in the SVG theme file. The element keys for the pixmaps
48  * of an animated sprite are produced by appending the frameSuffix() to the
49  * sprite key.
50  *
51  * @section clients Access to the pixmaps
52  *
53  * Sprite pixmaps can be retrieved from KGameRenderer in the main thread using
54  * the synchronous KGameRenderer::spritePixmap() method. However, it is highly
55  * recommended to use the asynchronous interface provided by the interface class
56  * KGameRendererClient. A client corresponds to one pixmap and registers itself
57  * with the corresponding KGameRenderer instance to get notified when a new
58  * pixmap is available.
59  *
60  * For QGraphicsView-based applications, the KGameRenderedItem class provides a
61  * QGraphicsPixmapItem which is a KGameRendererClient and displays the pixmap
62  * for a given sprite.
63  *
64  * @section strategies Rendering strategy
65  *
66  * For each theme, KGameRenderer keeps two caches around: an in-process cache of
67  * QPixmaps, and a disk cache containing QImages (powered by KImageCache). You
68  * therefore will not need to implement any caching for the pixmaps provided by
69  * KGameRenderer.
70  *
71  * When requests from a KGameRendererClient cannot be served immediately because
72  * the requested sprite is not in the caches, a rendering request is sent to a
73  * worker thread.
74  *
75  * @section legacy Support for legacy themes
76  *
77  * When porting applications to KGameRenderer, you probably have to support
78  * the format of existing themes. KGameRenderer provides the frameBaseIndex()
79  * and frameSuffix() properties for this purpose. It is recommended not to
80  * change these properties in new applications.
81  * @since 4.6
82  */
83 class KDEGAMES_EXPORT KGameRenderer : public QObject
84 {
85  Q_OBJECT
86  Q_PROPERTY(const KGameTheme *theme READ theme NOTIFY themeChanged)
87  Q_PROPERTY(KGameThemeProvider *themeProvider READ themeProvider NOTIFY readOnlyProperty)
88 
89 public:
90  /// Describes the various strategies which KGameRenderer can use to speed
91  /// up rendering.
92  /// \see setStrategyEnabled
93  enum Strategy {
94  /// If set, pixmaps will be cached in a shared disk cache (using
95  /// KSharedDataCache). This is especially useful for complex SVG
96  /// themes because KGameRenderer will not load the SVG if all needed
97  /// pixmaps are available from the disk cache.
98  UseDiskCache = 1 << 0,
99  /// If set, pixmap requests from KGameRendererClients will be
100  /// handled asynchronously if possible. This is especially useful
101  /// when many clients are requesting complex pixmaps at one time.
102  UseRenderingThreads = 1 << 1
103  };
104  /**
105  * Stores a combination of #Strategy values.
106  */
107  Q_DECLARE_FLAGS(Strategies, Strategy)
108 
109  /// Constructs a new KGameRenderer that renders @a prov->currentTheme().
110  /// @param prov the theme provider
111  /// @param cacheSize the cache size in megabytes (if not given, a sane
112  /// default is used)
113  /// @warning This constructor may only be called from the main thread.
114  explicit KGameRenderer(KGameThemeProvider *prov, unsigned cacheSize = 0);
115  /// overload that allows to use KGameRenderer without a theme provider
116  /// (useful when there is only one theme)
117  /// @note Takes ownership of @a theme.
118  explicit KGameRenderer(KGameTheme *theme, unsigned cacheSize = 0);
119  /// Deletes this KGameRenderer instance, as well as all clients using it.
120  ~KGameRenderer() override;
121 
122  /// @return the frame base index. @see setFrameBaseIndex()
123  int frameBaseIndex() const;
124  /// Sets the frame base index, i.e. the lowest frame index. Usually,
125  /// frame numbering starts at zero, so the frame base index is zero.
126  ///
127  /// For example, if you set the frame base index to 42, and use the
128  /// default frame suffix, the 3 frames of an animated sprite "foo" are
129  /// provided by the SVG elements "foo_42", "foo_43" and "foo_44".
130  ///
131  /// It is recommended not to alter the frame base index unless you need
132  /// to support legacy themes.
133  void setFrameBaseIndex(int frameBaseIndex);
134  /// @return the frame suffix. @see setFrameSuffix()
135  QString frameSuffix() const;
136  /// Sets the frame suffix. This suffix will be added to a sprite key
137  /// to create the corresponding SVG element key, after any occurrence of
138  /// "%1" in the suffix has been replaced by the frame number.
139  /// @note Giving a suffix which does not include "%1" will reset to the
140  /// default suffix "_%1".
141  ///
142  /// For example, if the frame suffix is set to "_%1" (the default), the
143  /// SVG element key for the frame no. 23 of the sprite "foo" is "foo_23".
144  /// @note Frame numbering starts at zero unless you setFrameBaseIndex().
145  void setFrameSuffix(const QString &suffix);
146  /// @return the optimization strategies used by this renderer
147  /// @see setStrategyEnabled()
148  Strategies strategies() const;
149  /// Enables/disables an optimization strategy for this renderer. By
150  /// default, both the UseDiskCache and the UseRenderingThreads strategies
151  /// are enabled. This is a sane default for 99% of all games. You might
152  /// only want to disable optimizations if the graphics are so simple that
153  /// the optimizations create an overhead in your special case.
154  ///
155  /// If you disable UseDiskCache, you should do so before setTheme(),
156  /// because changes to UseDiskCache cause a full theme reload.
157  void setStrategyEnabled(Strategy strategy, bool enabled = true);
158 
159  /// @return the KGameTheme instance used by this renderer
160  const KGameTheme *theme() const;
161  /// @return the KGameThemeProvider instance used by this renderer, or 0 if
162  /// the renderer was created with a single static theme
163  KGameThemeProvider *themeProvider() const;
164 
165  /// @return the bounding rectangle of the sprite with this @a key
166  /// This is equal to QSvgRenderer::boundsOnElement() of the corresponding
167  /// SVG element.
168  QRectF boundsOnSprite(const QString &key, int frame = -1) const;
169  /// @return the count of frames available for the sprite with this @a key
170  /// If this sprite is not animated (i.e. there are no SVG elements for
171  /// any frames), this method returns 0. If the sprite does not exist at
172  /// all, -1 is returned.
173  ///
174  /// If the sprite is animated, the method counts frames starting at zero
175  /// (unless you change the frameBaseIndex()), and returns the number of
176  /// frames for which corresponding elements exist in the SVG file.
177  ///
178  /// For example, if the SVG contains the elements "foo_0", "foo_1" and
179  /// "foo_3", frameCount("foo") returns 2 for the default frame suffix.
180  /// (The element "foo_3" is ignored because "foo_2" is missing.)
181  int frameCount(const QString &key) const;
182  /// @return if the sprite with the given @a key exists
183  /// This is the same as \code renderer.frameCount(key) >= 0 \endcode
184  bool spriteExists(const QString &key) const;
185  /// @return a rendered pixmap
186  /// @param key the key of the sprite
187  /// @param size the size of the resulting pixmap
188  /// @param frame the number of the frame which you want
189  /// @param customColors the custom color replacements for this client.
190  /// That is, for each entry in this has, the key color will be
191  /// replaced by its value if it is encountered in the sprite.
192  /// @note For non-animated frames, set @a frame to -1 or omit it.
193  /// @note Custom colors increase the rendering time considerably, so use
194  /// this feature only if you really need its flexibility.
195 
196  // The parentheses around QHash<QColor, QColor>() avoid compile
197  // errors on platforms with older gcc versions, e.g. OS X 10.6.
198  QPixmap spritePixmap(const QString &key, QSize size, int frame = -1, const QHash<QColor, QColor> &customColors = (QHash<QColor, QColor>())) const;
199 
200 Q_SIGNALS:
201  void themeChanged(const KGameTheme *theme);
202  /// This signal is never emitted. It is provided because QML likes to
203  /// complain about properties without NOTIFY signals, even readonly ones.
204  void readOnlyProperty();
205 
206 private:
207  friend class KGameRendererPrivate;
208  friend class KGameRendererClient;
209  friend class KGameRendererClientPrivate;
210  std::unique_ptr<KGameRendererPrivate> const d_ptr;
211  Q_DECLARE_PRIVATE(KGameRenderer)
212 };
213 
214 Q_DECLARE_OPERATORS_FOR_FLAGS(KGameRenderer::Strategies)
215 
216 #endif // KGAMERENDERER_H
Strategy
Describes the various strategies which KGameRenderer can use to speed up rendering.
Definition: kgamerenderer.h:93
Q_PROPERTY(...)
An object that receives pixmaps from a KGameRenderer.
Q_SIGNALSQ_SIGNALS
KCALENDARCORE_EXPORT size_t qHash(const KCalendarCore::Period &key, size_t seed=0)
Cache-enabled rendering of SVG themes.
Definition: kgamerenderer.h:83
QRgb rgba() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Thu Feb 15 2024 04:06:06 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.