| 1 |
<xml> |
| 2 |
<head> |
| 3 |
<title>Using sprites</title> |
| 4 |
</head> |
| 5 |
<body> |
| 6 |
|
| 7 |
<p>As probably most people know, a sprite is a collection of 2D images (called frames), |
| 8 |
shown in sequence with a delay between each frame. Sprites are used for a lot of game objects, |
| 9 |
i.e. moving people, spaceships, chairs, powerups, missiles, animated mouse cursors, etc.</p> |
| 10 |
|
| 11 |
<p><codelink>CL_Sprite</codelink> does all this for you in a very easy, yet flexible way. |
| 12 |
The simplest sprites are just a collection of frames, all shown after eachother, drawed on |
| 13 |
the screen somewhere.</p> |
| 14 |
|
| 15 |
<p>If you need more advanced features, sprites can be rotated and made semi-translucent, |
| 16 |
you can tweak the animation speed for individual frames, set frame offsets, set drawing and |
| 17 |
rotation alignment, you can play them in a backward looping pattern, a ping-pong loop, |
| 18 |
forward just-once, etc. Short said, CL_Sprite can do most things you'll ever need for basic |
| 19 |
2d sprites.</p> |
| 20 |
|
| 21 |
<h3>Constructing sprites</h3> |
| 22 |
|
| 23 |
<p>CL_Sprite can be constructed in two ways - either using ClanLib resources, |
| 24 |
or manually through a CL_SpriteDescription.</p> |
| 25 |
|
| 26 |
<h4>Creating sprites using resources</h4> |
| 27 |
|
| 28 |
<p>Please read the <a href="sprites_resources.html">Sprites Resources Overview</a> for |
| 29 |
a description on the resource options for sprites.</p> |
| 30 |
|
| 31 |
<p>After you have created your sprite resource, you can easily create a <codelink>CL_Sprite</codelink> |
| 32 |
object from it.</p> |
| 33 |
|
| 34 |
<pre> |
| 35 |
CL_ResourceManager *resources = new CL_ResourceManager("resources.xml"); |
| 36 |
|
| 37 |
CL_Sprite *sprite1 = new CL_Sprite("my_simple_sprite", resources); |
| 38 |
CL_Sprite *sprite2 = new CL_Sprite("my_advanced_sprite", resources); |
| 39 |
</pre> |
| 40 |
|
| 41 |
<h4>Creating sprites manually</h4> |
| 42 |
|
| 43 |
<p>If you for some reason don't want to use resource files, you can manually create |
| 44 |
the same sprite setup using the <codelink>CL_SpriteDescription</codelink> class, which |
| 45 |
describes a set of image-frames.</p> |
| 46 |
|
| 47 |
<p>You add, just like in the resource file, a series of cutters which will extract |
| 48 |
the frames to be used in the sprite.</p> |
| 49 |
|
| 50 |
<pre> |
| 51 |
CL_SpriteDescription desc_simple; |
| 52 |
desc_simple.add_frame(new CL_TargaProvider("image_single1.tga"), true); |
| 53 |
desc_simple.add_frame(new CL_TargaProvider("image_single2.tga"), true); |
| 54 |
desc_simple.add_frame(new CL_TargaProvider("image_single2.tga"), true); |
| 55 |
|
| 56 |
CL_SpriteDescription desc_advanced; |
| 57 |
desc_advanced.add_frame(new CL_TargaProvider("image1.tga"), true); |
| 58 |
desc_advanced.add_gridclipped_frames(new CL_TargaProvider("gridframes.tga"), 0, 0, 32, 32, 10, 2, 0, 0, true); |
| 59 |
desc_advanced.add_alphaclipped_frames(new CL_TargaProvider("alphaframes.tga"), 0, 0, 0.05f, true); |
| 60 |
desc_advanced.add_frame(new CL_TargaProvider("image2.tga"), true); |
| 61 |
desc_advanced.add_gridclipped_frames(new CL_TargaProvider("image3.tga"), 0, 0, 32, 32, 1, 1, 0, 0, true); |
| 62 |
|
| 63 |
CL_Sprite *sprite1 = new CL_Sprite(desc_simple); |
| 64 |
CL_Sprite *sprite2 = new CL_Sprite(desc_advanced); |
| 65 |
|
| 66 |
sprite2->set_alpha(0.5f); |
| 67 |
sprite2->set_base_angle(90.0f); |
| 68 |
sprite2->set_frame_delay(20, 100); |
| 69 |
sprite2->set_frame_offset(20, CL_Point(1, 1)); |
| 70 |
</pre> |
| 71 |
|
| 72 |
<p>If you read the <a href="sprites_resources.html">Sprites Resources Overview</a>, you will see this code |
| 73 |
creates the exact same setup, only now using code instead of a resourcefile.</p> |
| 74 |
|
| 75 |
<h3>Using sprites</h3> |
| 76 |
|
| 77 |
<p>Example usage code:</p> |
| 78 |
<pre> |
| 79 |
// Make sure sprites are animated |
| 80 |
sprite1->update(); |
| 81 |
sprite2->update(); |
| 82 |
|
| 83 |
// Rotate sprite |
| 84 |
sprite1->rotate(0.5f); |
| 85 |
|
| 86 |
// Draw sprites |
| 87 |
sprite1->draw(10, 10); |
| 88 |
sprite2->draw(100, 100); |
| 89 |
</pre> |
| 90 |
|
| 91 |
<h4>Changing look of a sprite</h4> |
| 92 |
|
| 93 |
<p>If you want to change the look of your sprite, use CL_Sprite::set_image_data(). |
| 94 |
This will keep the current attributes (rotation, alpha, etc), except the animation |
| 95 |
status (current frame etc).</p> |
| 96 |
|
| 97 |
<pre> |
| 98 |
class Man |
| 99 |
{ |
| 100 |
... |
| 101 |
|
| 102 |
CL_Sprite *sprite_man_walk; |
| 103 |
CL_Sprite *sprite_man_still; |
| 104 |
|
| 105 |
CL_Sprite *sprite_man; |
| 106 |
} |
| 107 |
|
| 108 |
void Man::init() |
| 109 |
{ |
| 110 |
sprite_man_walk = new CL_Sprite("man_walk", resources); |
| 111 |
sprite_man_still = new CL_Sprite("man_still", resources); |
| 112 |
|
| 113 |
set_walking(true); |
| 114 |
} |
| 115 |
|
| 116 |
void Man::set_walking(bool walking) |
| 117 |
{ |
| 118 |
if(walking) |
| 119 |
sprite_man->set_image_data(*sprite_man_walk); |
| 120 |
else |
| 121 |
sprite_man->set_image_data(*sprite_man_still); |
| 122 |
} |
| 123 |
|
| 124 |
void Man::draw() |
| 125 |
{ |
| 126 |
sprite_man->update(); |
| 127 |
sprite_man->rotate(1.0f); |
| 128 |
|
| 129 |
sprite_man->draw(x, y); |
| 130 |
} |
| 131 |
</pre> |
| 132 |
|
| 133 |
<h3>Playback control</h3> |
| 134 |
<p>TODO</p> |
| 135 |
|
| 136 |
<h3>Alignment and hotspot</h3> |
| 137 |
<p>TODO</p> |
| 138 |
|
| 139 |
<h3>Advanced: Frame-independent update</h3> |
| 140 |
|
| 141 |
<p>There are different ways of having a frame-independent game. |
| 142 |
One way is to calculate the time elapsed since last frame. |
| 143 |
This is how the update() function in CL_Sprite works. Between |
| 144 |
every call to update(), it calculates the amount of time lapsed, |
| 145 |
and uses this to decide which frame in the animation it should |
| 146 |
display. In most cases, this is good enough, and you won't have |
| 147 |
to bother with the second option described below.</p> |
| 148 |
|
| 149 |
<p>Some games works in a fixed-tick-mode, where updates are called |
| 150 |
X numbers of times during one second, instead of calculating a |
| 151 |
variable time between each update. It is possible to use this approach |
| 152 |
with CL_Sprite as well; you just call CL_Sprite::update(float time) with |
| 153 |
the time between each tick. So, if you have a constant tick of 30 per second, |
| 154 |
you would call sprite->update(1000.0f/30);</p> |
| 155 |
|
| 156 |
</body> |
| 157 |
</xml> |