1/***************************************************************************
2 * Copyright 2010 Stefan Majewsky <majewsky@gmx.net> *
3 * *
4 * This program is free software; you can redistribute it and/or modify *
5 * it under the terms of the GNU Library General Public License *
6 * version 2 as published by the Free Software Foundation *
7 * *
8 * This program is distributed in the hope that it will be useful, *
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
11 * GNU Library General Public License for more details. *
12 * *
13 * You should have received a copy of the GNU Library General Public *
14 * License along with this program; if not, write to the *
15 * Free Software Foundation, Inc., *
16 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. *
17 ***************************************************************************/
18
19#ifndef KGAMERENDERERCLIENT_H
20#define KGAMERENDERERCLIENT_H
21
22#include <QtGui/QPixmap>
23
24#include <libkdegames_export.h>
25
26class KGameRendererClientPrivate;
27class KGameRenderer;
28class KGameRendererPrivate;
29
30#ifndef KDEGAMES_QCOLOR_QHASH
31# define KDEGAMES_QCOLOR_QHASH
32 inline uint qHash(const QColor& color)
33 {
34 return color.rgba();
35 }
36#endif // KDEGAMES_QCOLOR_QHASH
37
38/**
39 * @class KGameRendererClient kgamerendererclient.h <KGameRendererClient>
40 * @since 4.6
41 * @short An object that receives pixmaps from a KGameRenderer.
42 *
43 * This class abstracts a sprite rendered by KGameRenderer. Given a sprite key,
44 * render size and possibly a frame index, it returns the QPixmap for this
45 * sprite (frame) once it becomes available. See the KGameRenderer class
46 * documentation for details.
47 *
48 * Subclasses have to reimplement the receivePixmap() method.
49 */
50class KDEGAMES_EXPORT KGameRendererClient
51{
52 public:
53 ///Creates a new client which receives pixmaps for the sprite with the
54 ///given @a spriteKey as provided by the given @a renderer.
55 KGameRendererClient(KGameRenderer* renderer, const QString& spriteKey);
56 virtual ~KGameRendererClient();
57
58 ///@return the renderer used by this client
59 KGameRenderer* renderer() const;
60 ///@return the frame count, or 0 for non-animated sprites, or -1 if the
61 ///sprite does not exist at all
62 ///@see KGameRenderer::frameCount()
63 int frameCount() const;
64
65 ///@return the key of the sprite currently rendered by this client
66 QString spriteKey() const;
67 ///Defines the key of the sprite which is rendered by this client.
68 void setSpriteKey(const QString& spriteKey);
69 ///@return the current frame number, or -1 for non-animated sprites
70 int frame() const;
71 ///For animated sprites, render another frame. The given frame number is
72 ///normalized by taking the modulo of the frame count, so the following
73 ///code works fine:
74 ///@code
75 /// class MyClient : public KGameRendererClient { ... }
76 /// MyClient client;
77 /// client.setFrame(client.frame() + 1); //cycle to next frame
78 /// client.setFrame(KRandom::random()); //choose a random frame
79 ///@endcode
80 void setFrame(int frame);
81 ///@return the size of the pixmap requested from KGameRenderer
82 QSize renderSize() const;
83 ///Defines the size of the pixmap that will be requested from
84 ///KGameRenderer. For pixmaps rendered on the screen, you usually want
85 ///to set this size such that the pixmap does not have to be scaled when
86 ///it is rendered onto your primary view (for speed reasons).
87 ///
88 ///The default render size is very small (width = height = 3 pixels), so
89 ///that you notice when you forget to set this. ;-)
90 void setRenderSize(const QSize& renderSize);
91 ///@return the custom color replacements for this client
92 QHash<QColor, QColor> customColors() const;
93 ///Defines the custom color replacements for this client. That is, for
94 ///each entry in this has, the key color will be replaced by its value
95 ///if it is encountered in the sprite.
96 ///
97 ///@note Custom colors increase the rendering time considerably, so use
98 /// this feature only if you really need its flexibility.
99 void setCustomColors(const QHash<QColor, QColor>& customColors);
100 protected:
101 ///This method is called when the KGameRenderer has provided a new
102 ///pixmap for this client (esp. after theme changes and after calls to
103 ///setFrame(), setRenderSize() and setSpriteKey()).
104 virtual void receivePixmap(const QPixmap& pixmap) = 0;
105 private:
106 friend class KGameRendererClientPrivate;
107 friend class KGameRenderer;
108 friend class KGameRendererPrivate;
109 KGameRendererClientPrivate* const d;
110};
111
112#endif // KGAMERENDERERCLIENT_H
113