#include <KGameRenderer>

Inheritance diagram for KGameRenderer:

Public Types
enum	Strategy { UseDiskCache = 1 << 0, UseRenderingThreads = 1 << 1 }

Signals
void	readOnlyProperty ()

void	themeChanged (const KgTheme *theme)

Public Member Functions
	KGameRenderer (KgThemeProvider *prov, unsigned cacheSize=0)

	KGameRenderer (KgTheme *theme, unsigned cacheSize=0)

virtual	~KGameRenderer ()

QRectF	boundsOnSprite (const QString &key, int frame=-1) const

QGraphicsView *	defaultPrimaryView () const

int	frameBaseIndex () const

int	frameCount (const QString &key) const

QString	frameSuffix () const

void	setDefaultPrimaryView (QGraphicsView *view)

void	setFrameBaseIndex (int frameBaseIndex)

void	setFrameSuffix (const QString &suffix)

void	setStrategyEnabled (Strategy strategy, bool enabled=true)

bool	spriteExists (const QString &key) const

QPixmap	spritePixmap (const QString &key, const QSize &size, int frame=-1, const QHash< QColor, QColor > &customColors=(QHash< QColor, QColor >())) const

Strategies	strategies () const

const KgTheme *	theme () const

KgThemeProvider *	themeProvider () const

Public Member Functions inherited from QObject
	QObject (QObject *parent)

	QObject (QObject parent, const char name)

virtual	~QObject ()

bool	blockSignals (bool block)

QObject *	child (const char objName, const char inheritsClass, bool recursiveSearch) const

const QObjectList &	children () const

const char *	className () const

bool	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const QObject receiver, const char method)

bool	disconnect (const char signal, const QObject receiver, const char *method)

void	dumpObjectInfo ()

void	dumpObjectTree ()

QList< QByteArray >	dynamicPropertyNames () const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name) const

QList< T >	findChildren (const QRegExp &regExp) const

QList< T >	findChildren (const QString &name) const

bool	inherits (const char *className) const

void	insertChild (QObject *object)

void	installEventFilter (QObject *filterObj)

bool	isA (const char *className) const

bool	isWidgetType () const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

const char *	name () const

const char *	name (const char *defaultName) const

QString	objectName () const

QObject *	parent () const

QVariant	property (const char *name) const

void	removeChild (QObject *object)

void	removeEventFilter (QObject *obj)

void	setName (const char *name)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const

int	startTimer (int interval)

QThread *	thread () const

Properties
const KgTheme	theme

KgThemeProvider	themeProvider

Properties inherited from QObject
	objectName

Additional Inherited Members
Static Public Member Functions inherited from QObject
bool	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

bool	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

Protected Member Functions inherited from QObject
bool	checkConnectArgs (const char signal, const QObject object, const char *method)

virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const char *signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const char *signal)

int	receivers (const char *signal) const

QObject *	sender () const

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *event)

Static Protected Member Functions inherited from QObject
QByteArray	normalizeSignalSlot (const char *signalSlot)

Detailed Description

Cache-enabled rendering of SVG themes.

Since: 4.6 KGameRenderer is a light-weight rendering framework for the rendering of SVG themes (as represented by KgTheme) into pixmap caches.

Terminology

Themes in the context of KGameRenderer are KgTheme instances. The theme selection by a KgRenderer can be managed by a KgThemeProvider.
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.

Definition at line 94 of file kgamerenderer.h.

Member Enumeration Documentation

enum KGameRenderer::Strategy

Describes the various strategies which KGameRenderer can use to speed up rendering.

See also: setStrategyEnabled

Enumerator

UseDiskCache

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.

UseRenderingThreads

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.

Definition at line 103 of file kgamerenderer.h.

Constructor & Destructor Documentation

KGameRenderer::KGameRenderer	(	KgThemeProvider *	prov,
		unsigned	cacheSize = `0`
	)

explicit

Constructs a new KGameRenderer that renders prov->currentTheme().

Parameters

cacheSize the cache size in megabytes (if not given, a sane default is used)

Warning: This constructor may only be called from the main thread.

Definition at line 66 of file kgamerenderer.cpp.

KGameRenderer::KGameRenderer	(	KgTheme *	theme,
		unsigned	cacheSize = `0`
	)

explicit

Definition at line 83 of file kgamerenderer.cpp.

KGameRenderer::~KGameRenderer ( )

virtual

Deletes this KGameRenderer instance, as well as all clients using it.

Definition at line 88 of file kgamerenderer.cpp.

Member Function Documentation

QRectF KGameRenderer::boundsOnSprite	(	const QString &	key,
		int	frame = `-1`
	)		const

Returns: the bounding rectangle of the sprite with this key This is equal to QSvgRenderer::boundsOnElement() of the corresponding SVG element.

Definition at line 357 of file kgamerenderer.cpp.

QGraphicsView * KGameRenderer::defaultPrimaryView ( ) const

Returns: the primary view which is used by newly created KGameRenderedItem instances associated with this renderer

See also: KGameRenderedItem::setPrimaryView

Definition at line 101 of file kgamerenderer.cpp.

int KGameRenderer::frameBaseIndex ( ) const

Returns: the frame base index.

See also: setFrameBaseIndex()

Definition at line 111 of file kgamerenderer.cpp.

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 (i.e. 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.)

Definition at line 301 of file kgamerenderer.cpp.

QString KGameRenderer::frameSuffix ( ) const

Returns: the frame suffix.

See also: setFrameSuffix()

Definition at line 121 of file kgamerenderer.cpp.

void KGameRenderer::readOnlyProperty ( )

signal

This signal is never emitted.

It is provided because QML likes to complain about properties without NOTIFY signals, even readonly ones.

void KGameRenderer::setDefaultPrimaryView ( QGraphicsView * view )

Set the primary view which will be used by newly created KGameRenderedItem instances associated with this renderer.

Calls to this method will have no effect on existing instances.

See also: KGameRenderedItem::setPrimaryView

Definition at line 106 of file kgamerenderer.cpp.

void KGameRenderer::setFrameBaseIndex ( int frameBaseIndex )

Sets the frame base index, i.e.

the lowest frame index. 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.

Definition at line 116 of file kgamerenderer.cpp.

void KGameRenderer::setFrameSuffix ( const QString & suffix )

Sets the frame 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().

Definition at line 126 of file kgamerenderer.cpp.

void KGameRenderer::setStrategyEnabled	(	KGameRenderer::Strategy	strategy,
		bool	enabled = `true`
	)

Enables/disables an optimization strategy for this renderer.

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 optimisations 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.

Definition at line 136 of file kgamerenderer.cpp.

bool KGameRenderer::spriteExists ( const QString & key ) const

Returns: if the sprite with the given key exists This is the same as
renderer.frameCount(key) >= 0

Definition at line 406 of file kgamerenderer.cpp.

QPixmap KGameRenderer::spritePixmap	(	const QString &	key,
		const QSize &	size,
		int	frame = `-1`,
		const QHash< QColor, QColor > &	customColors = `(QHash<QColor, QColor>())`
	)		const

Returns: a rendered pixmap

Parameters

key	the key of the sprite
size	the size of the resulting pixmap
frame	the number of the frame which you want
customColors	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.; Custom colors increase the rendering time considerably, so use this feature only if you really need its flexibility.

Definition at line 411 of file kgamerenderer.cpp.

KGameRenderer::Strategies KGameRenderer::strategies ( ) const

Returns: the optimization strategies used by this renderer

See also: setStrategyEnabled()

Definition at line 131 of file kgamerenderer.cpp.

const KgTheme* KGameRenderer::theme ( ) const

Returns: the KgTheme instance used by this renderer

void KGameRenderer::themeChanged ( const KgTheme * theme )

signal

KgThemeProvider* KGameRenderer::themeProvider ( ) const

Returns: the KgThemeProvider instance used by this renderer, or 0 if the renderer was created with a single static theme

Property Documentation

const KgTheme * KGameRenderer::theme

read

Definition at line 97 of file kgamerenderer.h.

KgThemeProvider * KGameRenderer::themeProvider

read

Definition at line 98 of file kgamerenderer.h.

The documentation for this class was generated from the following files:

libkdegames

Public Types

Signals

Public Member Functions

Properties

Additional Inherited Members