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
19class KGameRendererPrivate;
21class KGameRendererClientPrivate;
22class KGameTheme;
24
25#ifndef KDEGAMES_QCOLOR_QHASH
26#define KDEGAMES_QCOLOR_QHASH
27inline 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 */
83class 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
89public:
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
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.
205
206private:
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
214Q_DECLARE_OPERATORS_FOR_FLAGS(KGameRenderer::Strategies)
215
216#endif // KGAMERENDERER_H
An object that receives pixmaps from a KGameRenderer.
Cache-enabled rendering of SVG themes.
void readOnlyProperty()
This signal is never emitted.
Strategy
Describes the various strategies which KGameRenderer can use to speed up rendering.
A theme provider manages KGameTheme instances, and maintains a selection of the currentTheme().
A theme describes the visual appearance of a game.
Definition kgametheme.h:60
KTEXTEDITOR_EXPORT size_t qHash(KTextEditor::Cursor cursor, size_t seed=0) noexcept
QRgb rgba() const const
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 11 2024 12:12:34 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.