KGameRenderer Class
Cache-enabled rendering of SVG themes. More...
| Header: | #include <KGameRenderer> |
| Inherits: | QObject |
| Inherited By: |
Public Types
| flags | Strategies |
| enum | Strategy { UseDiskCache, UseRenderingThreads } |
Properties
- theme : const KGameTheme*
- themeProvider : KGameThemeProvider*
Public Functions
| KGameRenderer(KGameThemeProvider *prov, unsigned int cacheSize = 0) | |
| KGameRenderer(KGameTheme *theme, unsigned int cacheSize = 0) | |
| virtual | ~KGameRenderer() override |
| QRectF | boundsOnSprite(const QString &key, int frame = -1) const |
| int | frameBaseIndex() const |
| int | frameCount(const QString &key) const |
| QString | frameSuffix() const |
| void | setFrameBaseIndex(int frameBaseIndex) |
| void | setFrameSuffix(const QString &suffix) |
| void | setStrategyEnabled(KGameRenderer::Strategy strategy, bool enabled = true) |
| bool | spriteExists(const QString &key) const |
| QPixmap | spritePixmap(const QString &key, QSize size, int frame = -1, const QHash<QColor, QColor> &customColors = (QHash<QColor, QColor>())) const |
| KGameRenderer::Strategies | strategies() const |
| const KGameTheme * | theme() const |
| KGameThemeProvider * | themeProvider() const |
Signals
| void | readOnlyProperty() |
| void | themeChanged(const KGameTheme *theme) |
Detailed Description
KGameRenderer is a light-weight rendering framework for the rendering of SVG themes (as represented by KGameTheme) into pixmap caches.
Terminology
- Themes in the context of KGameRenderer are KGameTheme instances. The theme selection by a KGameRenderer can be managed by a KGameThemeProvider.
- A sprite is either a single pixmap ("non-animated sprites") or a sequence of pixmaps which are shown consecutively to produce an animation ("animated sprites"). Non-animated sprites correspond to a single element with the same key in the SVG theme file. The element keys for the pixmaps of an animated sprite are produced by appending the frameSuffix() to the sprite key.
Access to the pixmaps
Sprite pixmaps can be retrieved from KGameRenderer in the main thread using the synchronous KGameRenderer::spritePixmap() method. However, it is highly recommended to use the asynchronous interface provided by the interface class KGameRendererClient. A client corresponds to one pixmap and registers itself with the corresponding KGameRenderer instance to get notified when a new pixmap is available.
For QGraphicsView-based applications, the KGameRenderedItem class provides a QGraphicsPixmapItem which is a KGameRendererClient and displays the pixmap for a given sprite.
Rendering strategy
For each theme, KGameRenderer keeps two caches around: an in-process cache of QPixmaps, and a disk cache containing QImages (powered by KImageCache). You therefore will not need to implement any caching for the pixmaps provided by KGameRenderer.
When requests from a KGameRendererClient cannot be served immediately because the requested sprite is not in the caches, a rendering request is sent to a worker thread.
Support for legacy themes
When porting applications to KGameRenderer, you probably have to support the format of existing themes. KGameRenderer provides the frameBaseIndex() and frameSuffix() properties for this purpose. It is recommended not to change these properties in new applications.
Member Type Documentation
enum KGameRenderer::Strategy
flags KGameRenderer::Strategies
Describes the various strategies which KGameRenderer can use to speed up rendering.
| Constant | Value | Description |
|---|---|---|
KGameRenderer::UseDiskCache | 1 << 0 | If set, pixmaps will be cached in a shared disk cache (using KSharedDataCache). This is especially useful for complex SVG themes because KGameRenderer will not load the SVG if all needed pixmaps are available from the disk cache. |
KGameRenderer::UseRenderingThreads | 1 << 1 | If set, pixmap requests from KGameRendererClients will be handled asynchronously if possible. This is especially useful when many clients are requesting complex pixmaps at one time. |
The Strategies type is a typedef for QFlags<Strategy>. It stores an OR combination of Strategy values.
See also setStrategyEnabled.
Property Documentation
[read-only] theme : const KGameTheme*
This property holds the KGameTheme instance used by this renderer.
Access functions:
| const KGameTheme * | theme() const |
Notifier signal:
| void | themeChanged(const KGameTheme *theme) |
[read-only] themeProvider : KGameThemeProvider*
This property holds the KGameThemeProvider instance used by this renderer.
If the renderer was created with a single static theme, this is 0.
Access functions:
| KGameThemeProvider * | themeProvider() const |
Notifier signal:
| void | readOnlyProperty() |
Member Function Documentation
[explicit] KGameRenderer::KGameRenderer(KGameThemeProvider *prov, unsigned int cacheSize = 0)
Constructs a new KGameRenderer that renders prov->currentTheme(), where prov is the theme provider. cacheSize is the cache size in mebibytes. If not given, a sane default of 3MiB is used.
Warning: This constructor may only be called from the main thread.
See also KGameThemeProvider::currentTheme.
[explicit] KGameRenderer::KGameRenderer(KGameTheme *theme, unsigned int cacheSize = 0)
Constructs KGameRenderer without a theme provider (useful when there is only one theme).
Note: Takes ownership of theme.
This is an overloaded function.
[override virtual noexcept] KGameRenderer::~KGameRenderer()
Deletes this KGameRenderer instance, as well as all clients using it.
QRectF KGameRenderer::boundsOnSprite(const QString &key, int frame = -1) const
Returns the bounding rectangle of the sprite with this key for frame. This is equal to QSvgRenderer::boundsOnElement() of the corresponding SVG element.
int KGameRenderer::frameBaseIndex() const
Returns the frame base index.
See also setFrameBaseIndex().
int KGameRenderer::frameCount(const QString &key) const
Returns the count of frames available for the sprite with this key. If this sprite is not animated (that is, there are no SVG elements for any frames), this method returns 0. If the sprite does not exist at all, -1 is returned.
If the sprite is animated, the method counts frames starting at zero (unless you change the frameBaseIndex()), and returns the number of frames for which corresponding elements exist in the SVG file.
For example, if the SVG contains the elements "foo_0", "foo_1" and "foo_3", frameCount("foo") returns 2 for the default frame suffix. (The element "foo_3" is ignored because "foo_2" is missing.)
QString KGameRenderer::frameSuffix() const
Returns the frame suffix.
See also setFrameSuffix().
void KGameRenderer::setFrameBaseIndex(int frameBaseIndex)
Sets the frame base index, that is, the lowest frame index, to frameBaseIndex. Usually, frame numbering starts at zero, so the frame base index is zero.
For example, if you set the frame base index to 42, and use the default frame suffix, the 3 frames of an animated sprite "foo" are provided by the SVG elements "foo_42", "foo_43" and "foo_44".
It is recommended not to alter the frame base index unless you need to support legacy themes.
See also frameBaseIndex().
void KGameRenderer::setFrameSuffix(const QString &suffix)
Sets the frame suffix to suffix. This suffix will be added to a sprite key to create the corresponding SVG element key, after any occurrence of "%1" in the suffix has been replaced by the frame number.
Note: Giving a suffix which does not include "%1" will reset to the default suffix "_%1".
For example, if the frame suffix is set to "_%1" (the default), the SVG element key for the frame no. 23 of the sprite "foo" is "foo_23".
Note: Frame numbering starts at zero unless you setFrameBaseIndex().
See also frameSuffix().
void KGameRenderer::setStrategyEnabled(KGameRenderer::Strategy strategy, bool enabled = true)
Enables/disables an optimization strategy for this renderer according to enabled. By default, both the UseDiskCache and the UseRenderingThreads strategies are enabled. This is a sane default for 99% of all games. You might only want to disable optimizations if the graphics are so simple that the optimizations create an overhead in your special case.
If you disable UseDiskCache, you should do so before setTheme(), because changes to UseDiskCache cause a full theme reload.
bool KGameRenderer::spriteExists(const QString &key) const
Returns whether the sprite with the given key exists. This is the same as renderer.frameCount(key) >= 0
QPixmap KGameRenderer::spritePixmap(const QString &key, QSize size, int frame = -1, const QHash<QColor, QColor> &customColors = (QHash<QColor, QColor>())) const
Returns a rendered pixmap from the key of the sprite at the size size using frame number frame. customColors is the custom color replacements for this client. That is, for each entry in this has, the key color will be replaced by its value if it is encountered in the sprite.
Note: For non-animated frames, set frame to -1 or omit it.
Note: Custom colors increase the rendering time considerably, so use this feature only if you really need its flexibility.
KGameRenderer::Strategies KGameRenderer::strategies() const
Returns the optimization strategies used by this renderer
See also setStrategyEnabled().
[signal] void KGameRenderer::themeChanged(const KGameTheme *theme)
Emitted when the theme changes to theme.
Note: Notifier signal for property theme.