Sprites / SpritesB Library - Revision history

Filmote: /* Using Frames */

2024-08-12T10:47:05Z

Using Frames

← Older revision		Revision as of 10:47, 12 August 2024
Line 250:		Line 250:
	Sprites::drawExternalMask(10, 20, Ape, Ape_Mask, frame, frame);		Sprites::drawExternalMask(10, 20, Ape, Ape_Mask, frame, frame);
	</pre>		</pre>

	~~<code>Sprites::drawExternalMask(10, 20, ball, ball_Mask, 0, 0);</code>~~

Filmote: /* Using Frames */

2024-08-12T10:46:46Z

Using Frames

← Older revision		Revision as of 10:46, 12 August 2024
Line 206:		Line 206:

	// width, height,		// width, height,

	20, 24,		20, 24,

	// FRAME 00		// FRAME 00

	0x00, 0x00, 0x00, 0xc0, 0x38, 0x04, 0xc2, 0x79, 0x65, 0x51, 0x51, 0x65, 0x79, 0xc2, 0x04, 0x38, 0xc0, 0x00, 0x00, 0x00,		0x00, 0x00, 0x00, 0xc0, 0x38, 0x04, 0xc2, 0x79, 0x65, 0x51, 0x51, 0x65, 0x79, 0xc2, 0x04, 0x38, 0xc0, 0x00, 0x00, 0x00,

	0x38, 0xc4, 0x02, 0x13, 0xe4, 0xe9, 0xa2, 0xd7, 0x35, 0xe5, 0xe5, 0x35, 0xd7, 0xa2, 0xe9, 0xe4, 0x13, 0x02, 0xc4, 0x38,		0x38, 0xc4, 0x02, 0x13, 0xe4, 0xe9, 0xa2, 0xd7, 0x35, 0xe5, 0xe5, 0x35, 0xd7, 0xa2, 0xe9, 0xe4, 0x13, 0x02, 0xc4, 0x38,

	0x00, 0x0c, 0x05, 0x0a, 0x08, 0x09, 0x0d, 0x0a, 0x01, 0x01, 0x01, 0x01, 0x0a, 0x0d, 0x09, 0x08, 0x0a, 0x05, 0x0c, 0x00,		0x00, 0x0c, 0x05, 0x0a, 0x08, 0x09, 0x0d, 0x0a, 0x01, 0x01, 0x01, 0x01, 0x0a, 0x0d, 0x09, 0x08, 0x0a, 0x05, 0x0c, 0x00,

	// FRAME 01		// FRAME 01

	0xc0, 0x30, 0x08, 0x08, 0x7c, 0xf4, 0xc2, 0x1d, 0x2b, 0x41, 0x6b, 0x41, 0x2b, 0x9e, 0xc4, 0x7c, 0x08, 0x08, 0x30, 0xc0,		0xc0, 0x30, 0x08, 0x08, 0x7c, 0xf4, 0xc2, 0x1d, 0x2b, 0x41, 0x6b, 0x41, 0x2b, 0x9e, 0xc4, 0x7c, 0x08, 0x08, 0x30, 0xc0,

	0x07, 0x38, 0xc0, 0x12, 0xc4, 0xe8, 0xe2, 0xf7, 0xf5, 0x65, 0x65, 0xf5, 0xf7, 0xe2, 0xe8, 0xc4, 0x12, 0xc0, 0x38, 0x07,		0x07, 0x38, 0xc0, 0x12, 0xc4, 0xe8, 0xe2, 0xf7, 0xf5, 0x65, 0x65, 0xf5, 0xf7, 0xe2, 0xe8, 0xc4, 0x12, 0xc0, 0x38, 0x07,

	0x00, 0x0c, 0x05, 0x0a, 0x08, 0x09, 0x0d, 0x0b, 0x01, 0x01, 0x01, 0x01, 0x0b, 0x0d, 0x09, 0x08, 0x0a, 0x05, 0x0c, 0x00,		0x00, 0x0c, 0x05, 0x0a, 0x08, 0x09, 0x0d, 0x0b, 0x01, 0x01, 0x01, 0x01, 0x0b, 0x0d, 0x09, 0x08, 0x0a, 0x05, 0x0c, 0x00,

	// FRAME 02		// FRAME 02

	...		...

Filmote at 10:46, 12 August 2024

2024-08-12T10:46:19Z

← Older revision		Revision as of 10:46, 12 August 2024
Line 187:		Line 187:

	A sample application that demonstrates the various draw commands can be found [https://github.com/filmote/Pipes_Article1_SpritesDemo here]		A sample application that demonstrates the various draw commands can be found [https://github.com/filmote/Pipes_Article1_SpritesDemo here]

			== Using Frames ==


			When dealing with animations, it is convenient to put all of the images that makes up an animation into a single file and render the needed image using an index. This allows the code to be simplified when playing a sequence of images to just increment a variable which acts as the index to the image.

			Consider the single image below. It contains 5 images of Kong, with each individual image 20x24 pixels in height. As with single sprites, all images must be multiples of 8 pixels high.

			[[File:Ape Full.png]]


			We can convert the data using another Team ARG tool, the [http://www.bloggingadeadhorse.com/TeamARGSpriteConverter/index.htm Arduboy Sprite Converter]. The tool expects the filename to contain the dimensions in the format ''{name}_{width}x{height}.png''. Saving the sample image as ''Ape_20x24.png'' and converting it using the provided tool, produces the following data:

			<pre>
			const unsigned char PROGMEM Ape[] =

			{

			// width, height,

			20, 24,

			// FRAME 00

			0x00, 0x00, 0x00, 0xc0, 0x38, 0x04, 0xc2, 0x79, 0x65, 0x51, 0x51, 0x65, 0x79, 0xc2, 0x04, 0x38, 0xc0, 0x00, 0x00, 0x00,

			0x38, 0xc4, 0x02, 0x13, 0xe4, 0xe9, 0xa2, 0xd7, 0x35, 0xe5, 0xe5, 0x35, 0xd7, 0xa2, 0xe9, 0xe4, 0x13, 0x02, 0xc4, 0x38,

			0x00, 0x0c, 0x05, 0x0a, 0x08, 0x09, 0x0d, 0x0a, 0x01, 0x01, 0x01, 0x01, 0x0a, 0x0d, 0x09, 0x08, 0x0a, 0x05, 0x0c, 0x00,

			// FRAME 01

			0xc0, 0x30, 0x08, 0x08, 0x7c, 0xf4, 0xc2, 0x1d, 0x2b, 0x41, 0x6b, 0x41, 0x2b, 0x9e, 0xc4, 0x7c, 0x08, 0x08, 0x30, 0xc0,

			0x07, 0x38, 0xc0, 0x12, 0xc4, 0xe8, 0xe2, 0xf7, 0xf5, 0x65, 0x65, 0xf5, 0xf7, 0xe2, 0xe8, 0xc4, 0x12, 0xc0, 0x38, 0x07,

			0x00, 0x0c, 0x05, 0x0a, 0x08, 0x09, 0x0d, 0x0b, 0x01, 0x01, 0x01, 0x01, 0x0b, 0x0d, 0x09, 0x08, 0x0a, 0x05, 0x0c, 0x00,

			// FRAME 02

			...

			};
			</pre>


			Like the conversion of the single sprite, the data contains the dimensions of the sprite followed by the encoded data. However, this tool has encoded all five images into a single array.

			Individual frames can now be referenced using any of the Sprites functions, as shown below:

			<pre>
			uint8_t frame = 3;
			Sprites::drawOverwrite(10, 20, Ape, frame);
			</pre>

			Using frames and masks together is the same as with a single sprite. Depending on your animation, you may be able to share a single mask across all animation images or you may be forced to use a unique mask per image. The function <code>Sprites::drawExternalMask(x, y, img, mask, img_frame, mask_frame);</code> allows you to independently specify images and masks and their respective frame index.

			When using a single mask, you would specify an index for the image required and a constant <code>0</code> for the mask's frame (as there is only one mask).

			<pre>
			uint8_t frame = 3;
			Sprites::drawExternalMask(10, 20, Ape, Ape_Mask, frame, 0);
			</pre>


			When using images with corresponding masks, you would typically specify the same index for the image and the mask's frame. This assumes you images and masks are laid out in the same order.

			<pre>
			uint8_t frame = 3;
			Sprites::drawExternalMask(10, 20, Ape, Ape_Mask, frame, frame);
			</pre>

			<code>Sprites::drawExternalMask(10, 20, ball, ball_Mask, 0, 0);</code>

Filmote at 10:02, 11 August 2024

2024-08-11T10:02:12Z

← Older revision		Revision as of 10:02, 11 August 2024
Line 3:		Line 3:

	The Arduboy library has support for sprites but due to the lack of a powerful graphics processor handles them differently. When rendering a sprite, the image is mapped into a single display buffer that may already have a background image drawn on it. If you move the sprite you need to regenerate the background from its old position.		The Arduboy library has support for sprites but due to the lack of a powerful graphics processor handles them differently. When rendering a sprite, the image is mapped into a single display buffer that may already have a background image drawn on it. If you move the sprite you need to regenerate the background from its old position.

			<br/>

	== Sprites Library ==		== Sprites Library ==

Filmote: /* SpritesB Library */

2024-08-11T10:01:56Z

SpritesB Library

← Older revision		Revision as of 10:01, 11 August 2024
Line 33:		Line 33:

	The important lines to note are lines <code>004 - 008</code> which define our sprite graphic and line <code>016</code> which displays the graphic on the screen. In this example, its a ball that is 16 x 16 pixels in size. The first two numbers of the array indicate the size, the rest of the data is the graphic itself encoded using one of the graphics tools detailed below. Line <code>016</code> uses the Sprites library to render the ball graphic at postion 10,0 on the screen. It is using a predefined function, <code>drawOverwrite()</code>, to render the graphic over the top of any graphics already rendered. As all sprites are rectangular yet our ball is (obviously) round, it will erase the graphics in the 'corners'. The Sprites library provides additional functions to mask the round image thus allowing the ball to be rendered properly without the 'corners' erasing the corners. These functions are describe below.		The important lines to note are lines <code>004 - 008</code> which define our sprite graphic and line <code>016</code> which displays the graphic on the screen. In this example, its a ball that is 16 x 16 pixels in size. The first two numbers of the array indicate the size, the rest of the data is the graphic itself encoded using one of the graphics tools detailed below. Line <code>016</code> uses the Sprites library to render the ball graphic at postion 10,0 on the screen. It is using a predefined function, <code>drawOverwrite()</code>, to render the graphic over the top of any graphics already rendered. As all sprites are rectangular yet our ball is (obviously) round, it will erase the graphics in the 'corners'. The Sprites library provides additional functions to mask the round image thus allowing the ball to be rendered properly without the 'corners' erasing the corners. These functions are describe below.

			<br/>

	== SpritesB Library ==		== SpritesB Library ==

	The <code>SpritesB</code> library provides the same methods ass the Sprites library however these libraries have been optimised for speed. To invoke a <code>SpritesB</code> method, simply substitute the library designation with that of the <code>SpritesB</code> library. For example, <code>Sprites::drawOverwrite(10, 20, ball, 0);</code> would become <code>SpritesB::drawOverwrite(10, 20, ball, 0);</code>		The <code>SpritesB</code> library provides the same methods ass the Sprites library however these libraries have been optimised for program size over speed. To invoke a <code>SpritesB</code> method, simply substitute the library designation with that of the <code>SpritesB</code> library. For example, <code>Sprites::drawOverwrite(10, 20, ball, 0);</code> would become <code>SpritesB::drawOverwrite(10, 20, ball, 0);</code>

			It is important to note that if you mix <code>Sprites</code> methods and <code>SpritesB</code> methods in the one sketch, both functions will be compiled into the code resulting in additional program space being used. Typically, you would pick one approach or the other.

			<br/>

	== Creating Your Own Sprites ==		== Creating Your Own Sprites ==

			<br/>

	=== Creating a Sprite ===		=== Creating a Sprite ===
Line 61:		Line 69:

	The data above has 34 bytes due to the size of the image. The first two indicate the width and height of the graphic - in this case 16 x 16 pixels. The remainder of the data - 32 bytes - describes the actual data to be displayed. Each element in the array describes 8 vertical pixels and as our image is 16 pixels in width the first row of 16 values describes the the upper 16x8 pixels of the image. The second row of values describes the lower 16x8 pixels of our image.		The data above has 34 bytes due to the size of the image. The first two indicate the width and height of the graphic - in this case 16 x 16 pixels. The remainder of the data - 32 bytes - describes the actual data to be displayed. Each element in the array describes 8 vertical pixels and as our image is 16 pixels in width the first row of 16 values describes the the upper 16x8 pixels of the image. The second row of values describes the lower 16x8 pixels of our image.

			<br/>

	=== Creating a Sprite Mask ===		=== Creating a Sprite Mask ===

	As eluded to earlier, the Sprites Library allows you to render sprites using a mask to allow them to be positioned over background graphics while controlling what areas are drawn and what areas are not. Consider the following graphic and mask:		As eluded to earlier, the Sprites Library allows you to render sprites using a mask to allow them to be positioned over background graphics while controlling what areas are drawn and what areas are not. Consider the following graphic and mask:

Line 105:		Line 116:

	When using the <code>drawPlusMask()</code> function, the combined image and mask data are passed as a single parameter to the function: <code>Sprites::drawPlusMask(10, 20, ball_plusMask, 0);</code>		When using the <code>drawPlusMask()</code> function, the combined image and mask data are passed as a single parameter to the function: <code>Sprites::drawPlusMask(10, 20, ball_plusMask, 0);</code>

			<br/>

	== Using Sprites Masks ==		== Using Sprites Masks ==

Filmote at 09:59, 11 August 2024

2024-08-11T09:59:25Z

← Older revision		Revision as of 09:59, 11 August 2024
Line 33:		Line 33:

	The important lines to note are lines <code>004 - 008</code> which define our sprite graphic and line <code>016</code> which displays the graphic on the screen. In this example, its a ball that is 16 x 16 pixels in size. The first two numbers of the array indicate the size, the rest of the data is the graphic itself encoded using one of the graphics tools detailed below. Line <code>016</code> uses the Sprites library to render the ball graphic at postion 10,0 on the screen. It is using a predefined function, <code>drawOverwrite()</code>, to render the graphic over the top of any graphics already rendered. As all sprites are rectangular yet our ball is (obviously) round, it will erase the graphics in the 'corners'. The Sprites library provides additional functions to mask the round image thus allowing the ball to be rendered properly without the 'corners' erasing the corners. These functions are describe below.		The important lines to note are lines <code>004 - 008</code> which define our sprite graphic and line <code>016</code> which displays the graphic on the screen. In this example, its a ball that is 16 x 16 pixels in size. The first two numbers of the array indicate the size, the rest of the data is the graphic itself encoded using one of the graphics tools detailed below. Line <code>016</code> uses the Sprites library to render the ball graphic at postion 10,0 on the screen. It is using a predefined function, <code>drawOverwrite()</code>, to render the graphic over the top of any graphics already rendered. As all sprites are rectangular yet our ball is (obviously) round, it will erase the graphics in the 'corners'. The Sprites library provides additional functions to mask the round image thus allowing the ball to be rendered properly without the 'corners' erasing the corners. These functions are describe below.

			== SpritesB Library ==

			The <code>SpritesB</code> library provides the same methods ass the Sprites library however these libraries have been optimised for speed. To invoke a <code>SpritesB</code> method, simply substitute the library designation with that of the <code>SpritesB</code> library. For example, <code>Sprites::drawOverwrite(10, 20, ball, 0);</code> would become <code>SpritesB::drawOverwrite(10, 20, ball, 0);</code>

	== Creating Your Own Sprites ==		== Creating Your Own Sprites ==

	=== Creating a Sprite ===		=== Creating a Sprite ===

	Sprites can be created in any graphical tool that can produce black and white PNG files - which is pretty much any tool! When developing sprites, it is important to note that they must be a multiple of 8 pixels high.		Sprites can be created in any graphical tool that can produce black and white PNG files - which is pretty much any tool! When developing sprites, it is important to note that they must be a multiple of 8 pixels high.

Filmote: /* Creating a Sprite Mask */

2024-08-11T09:55:08Z

Creating a Sprite Mask

← Older revision		Revision as of 09:55, 11 August 2024
Line 83:		Line 83:

	As you can see the ball and mask are described in two separate arrays. This format is appropriate for the <code>drawExternalMask()</code> detailed below.		As you can see the ball and mask are described in two separate arrays. This format is appropriate for the <code>drawExternalMask()</code> detailed below.

			When using the <code>drawExternalMask()</code> function, both image and mask are passed to the function: <code>Sprites::drawExternalMask(10, 20, ball, ball_Mask, 0, 0);</code>

	The <code>drawPlusMask()</code> function uses is a variation of the <code>drawExternalMask()</code>function which uses a single array of data instead of separate graphic and mask arrays. If you study the data in the array below, you will notice that the first byte is derived from the first byte of the graphics data and is followed by the first byte of the mask data. The next byte is the second byte of the graphics data followed by the second byte of the mask data and so on. Arranging the data this way allows the code to retrieve the data in the most optimal way and improves performance. The down side is that the mask cannot be shared across multiple, similar graphic images.		The <code>drawPlusMask()</code> function uses is a variation of the <code>drawExternalMask()</code>function which uses a single array of data instead of separate graphic and mask arrays. If you study the data in the array below, you will notice that the first byte is derived from the first byte of the graphics data and is followed by the first byte of the mask data. The next byte is the second byte of the graphics data followed by the second byte of the mask data and so on. Arranging the data this way allows the code to retrieve the data in the most optimal way and improves performance. The down side is that the mask cannot be shared across multiple, similar graphic images.
Line 96:		Line 98:
	};		};
	</pre>		</pre>

			When using the <code>drawPlusMask()</code> function, the combined image and mask data are passed as a single parameter to the function: <code>Sprites::drawPlusMask(10, 20, ball_plusMask, 0);</code>

	== Using Sprites Masks ==		== Using Sprites Masks ==

Filmote: /* Creating a Sprite Mask */

2024-08-11T09:52:47Z

Creating a Sprite Mask

← Older revision		Revision as of 09:52, 11 August 2024
Line 83:		Line 83:

	As you can see the ball and mask are described in two separate arrays. This format is appropriate for the <code>drawExternalMask()</code> detailed below.		As you can see the ball and mask are described in two separate arrays. This format is appropriate for the <code>drawExternalMask()</code> detailed below.

			The <code>drawPlusMask()</code> function uses is a variation of the <code>drawExternalMask()</code>function which uses a single array of data instead of separate graphic and mask arrays. If you study the data in the array below, you will notice that the first byte is derived from the first byte of the graphics data and is followed by the first byte of the mask data. The next byte is the second byte of the graphics data followed by the second byte of the mask data and so on. Arranging the data this way allows the code to retrieve the data in the most optimal way and improves performance. The down side is that the mask cannot be shared across multiple, similar graphic images.

	<pre>		<pre>

Filmote: /* Creating a Sprite Mask */

2024-08-11T04:36:28Z

Creating a Sprite Mask

← Older revision		Revision as of 04:36, 11 August 2024
Line 82:		Line 82:
	</pre>		</pre>

	This format is appropriate for the <code>drawExternalMask() ~~detailed below.~~</code>		As you can see the ball and mask are described in two separate arrays. This format is appropriate for the <code>drawExternalMask()</code> detailed below.

	<pre>		<pre>
	const byte PROGMEM ball_plusMask[] = {		const byte PROGMEM ball_plusMask[] = {

Filmote: /* Creating a Sprite Mask */

2024-08-11T04:35:43Z

Creating a Sprite Mask

← Older revision		Revision as of 04:35, 11 August 2024
Line 57:		Line 57:
	The data above has 34 bytes due to the size of the image. The first two indicate the width and height of the graphic - in this case 16 x 16 pixels. The remainder of the data - 32 bytes - describes the actual data to be displayed. Each element in the array describes 8 vertical pixels and as our image is 16 pixels in width the first row of 16 values describes the the upper 16x8 pixels of the image. The second row of values describes the lower 16x8 pixels of our image.		The data above has 34 bytes due to the size of the image. The first two indicate the width and height of the graphic - in this case 16 x 16 pixels. The remainder of the data - 32 bytes - describes the actual data to be displayed. Each element in the array describes 8 vertical pixels and as our image is 16 pixels in width the first row of 16 values describes the the upper 16x8 pixels of the image. The second row of values describes the lower 16x8 pixels of our image.

			=== Creating a Sprite Mask ===
			As eluded to earlier, the Sprites Library allows you to render sprites using a mask to allow them to be positioned over background graphics while controlling what areas are drawn and what areas are not. Consider the following graphic and mask:

			[[File:Sprites 00.png\|frameless]] [[File:Sprites 01.png\|frameless]]


			When using a sprite and mask, each pixel in the graphic is considered with its corresponding pixel in the mask to determine what will be rendered. Pixels set white in the mask indicate that the pixel will be set to the value of the corresponding image pixel. If a pixel in the image is white and the corresponding pixel in the mask is also white, then the resultant pixel to be rendered the screen will be white. Likewise, if the pixel in the image is black and the corresponding pixel in the mask is white, then the resultant pixel to be rendered the screen will be black.

			Pixels set to black in the mask will be left unchanged - whatever colour the pixel is in the graphic will be rendered to the screen.

	~~=== Creating a Sprite Mask ===~~		Masks can be created and converted using the same tools above. However, when copying the data to your program, remove the dimensions of the mask as they are not needed. Converting the grpahic and mask above results in the data below:

	<pre>		<pre>
Line 67:		Line 76:
	};		};

	const byte PROGMEM ~~ball_externalMask~~[] = {		const byte PROGMEM ball_Mask[] = {
	0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,		0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
Line 73:		Line 82:
	</pre>		</pre>

			This format is appropriate for the <code>drawExternalMask() detailed below.</code>
	<pre>		<pre>
	const byte PROGMEM ball_plusMask[] = {		const byte PROGMEM ball_plusMask[] = {
Line 94:		Line 103:
	* <code>drawPlusMask()</code>		* <code>drawPlusMask()</code>
	* <code>drawSefMasked()</code>		* <code>drawSefMasked()</code>
	~~But what do they each do? Consider the following image and mask:~~

	But what do they each do? Consider the following image and mask:		But what do they each do? Consider the following image and mask: