feat: add 4BPP/16colors sprites handling

Author: youenchene

docs/programming/sprites.md

@@ -129,10 +129,76 @@ When optimizing its calls, you need to call it at least twice (once for each dou
 - enabling sprite,
 - changes in sprite chaining.
 
+
+
 ### Chaining sprites in a single channel
 
 This is currently not supported.
 
+
+## Handling 16colors/4BPP sprites
+
+16 colors sprites can be now handle in ACE :
+
+Remember you need to have 1 line before your actual sprite in your bitmap and 1 line after your actual sprite in your bitmap.
+
+```c
+  s_pSprite0Data = bitmapCreate(16, 34, 4, BMF_CLEAR|BMF_INTERLEAVED); // 16x32 2BPP
+  // Showing all colors as an example. Put your sprite bitmap instead
+  blitRect(s_pSprite0Data,0, 0, 8, 4, 0);
+  blitRect(s_pSprite0Data,0, 4, 8, 4, 1);
+  blitRect(s_pSprite0Data,0, 8, 8, 4, 2);
+  blitRect(s_pSprite0Data,0, 12, 8, 4, 3);
+  blitRect(s_pSprite0Data,0, 16, 8, 4, 4);
+  blitRect(s_pSprite0Data,0, 20, 8, 4, 5);
+  blitRect(s_pSprite0Data,0, 24, 8, 4, 6);
+  blitRect(s_pSprite0Data,0, 28, 8, 4, 7);
+  blitRect(s_pSprite0Data,8, 0, 8, 4, 8);
+  blitRect(s_pSprite0Data,8, 4, 8, 4, 9);
+  blitRect(s_pSprite0Data,8, 8, 8, 4, 10);
+  blitRect(s_pSprite0Data,8, 12, 8, 4, 11);
+  blitRect(s_pSprite0Data,8, 16,8, 4, 12);
+  blitRect(s_pSprite0Data,8, 20, 8, 4, 13);
+  blitRect(s_pSprite0Data,8, 24, 8, 4, 14);
+  blitRect(s_pSprite0Data,8, 28, 8, 4, 15);
+  
+s_pSprite0 = spriteAdd(0, s_pSprite0Data);
+```
+Because, a 16 colors sprites use 2 channels, it must be used on an even channel (0,2,4,6). The odd channel just after will be taken by the 16 colors sprite so don't use it. (so 1,3,5,7).
+
+You need to use the SetPos functions to set the sprite position :
+```c
+  spriteSetPos(s_pSprite0,100,100);
+
+  spriteSetPosY(s_pSprite0,s_pSprite0->wY-2);
+
+  spriteSetPosX(s_pSprite0,s_pSprite0->wX-2);
+```
+
+`spriteRequestMetadataUpdate` is not needed when you use theses functions.
+
+
+
+**Don't change the position by doing : `s_pSprite0->wX=newvalue`**
+
+
+For 16 colors sprites, `spriteSetBitmap` is not optimized, don't use it (yet) for animation.
+
+## Q&A
+
+### My sprite is showing behind the playfield
+
+After a view load blcon2 is set to 0, you need to set the blcon2 to what you want.
+
+````
+#include <ace/utils/custom.h>
+[...]
+viewLoad(s_pView); 
+// To insert after the viewload
+// Update blcon2 to put sprite in front of http://amigadev.elowar.com/read/ADCD_2.1/Hardware_Manual_guide/node0159.html
+g_pCustom->bplcon2=0b00100000;
+```
+
 ## Managing sprites in a different way
 
 It is very much possible that you will find ACE's sprite manager's abilities insufficient (e.g. you want to manage your sprite pointers or data using copperlist).

include/ace/managers/sprite.h

@@ -34,6 +34,7 @@ typedef struct tSprite {
 	UBYTE isEnabled;
 	UBYTE isHeaderToBeUpdated;
 	UBYTE isAttached; // Odd Sprites Only.
+	UBYTE is4PP; // 16-color sprites only.
 } tSprite;
 
 /**
@@ -104,6 +105,8 @@ void spriteRemove(tSprite *pSprite);
  * @param pBitmap Bitmap to be used for display/control data. The bitmap must be
  * in 2BPP interleaved format as well as start and end with an empty line,
  * which will not be displayed but used for storing control data.
+ * 4BPP interleaved format is also supported for 16-color sprites it will take 2 channels, you must use an even channel as main channel.
+ * In 4BPP mode, it's not optimized for animation.
  */
 void spriteSetBitmap(tSprite *pSprite, tBitMap *pBitmap);
 
@@ -149,6 +152,31 @@ void spriteSetAttached(tSprite *pSprite, UBYTE isAttached);
  */
 void spriteRequestMetadataUpdate(tSprite *pSprite);
 
+/**
+ * @brief Set Position of the sprite. Mandatory for 4BPP sprites
+ *
+ * @param pSprite Sprite to be enabled.
+ * @param wX X position, measured from the left of the view.
+ * @param wY Y position, measured from the top of the view.
+ */
+void spriteSetPos(tSprite *pSprite,WORD wX, WORD wY);
+
+/**
+ * @brief Set Position of the sprite. Mandatory for 4BPP sprites
+ *
+ * @param pSprite Sprite to be enabled.
+ * @param wX X position, measured from the left of the view.
+ */
+void spriteSetPosX(tSprite *pSprite,WORD wX);
+
+/**
+ * @brief Set Position of the sprite. Mandatory for 4BPP sprites
+ *
+ * @param pSprite Sprite to be enabled.
+ * @param wY Y position, measured from the top of the view.
+ */
+void spriteSetPosY(tSprite *pSprite, WORD wY);
+
 /**
  * @brief Updates the sprite's metadata if set as requiring update.
  * Be sure to call it at least whenever sprite's metadata needs updating.

src/ace/managers/sprite.c

@@ -30,6 +30,15 @@ static void spriteChannelRequestCopperUpdate(tSpriteChannel *pChannel) {
 	pChannel->ubCopperRegenCount = 2; // for front/back buffers in raw mode
 }
 
+tSprite* get4BPPAttachedSprite(tSprite *pSprite) {
+	tSpriteChannel *pChannel = &s_pChannelsData[pSprite->ubChannelIndex+1];
+	/*
+	if(!pChannel->ubCopperRegenCount) {
+		return ;
+	}*/
+	return pChannel->pFirstSprite;
+}
+
 void spriteManagerCreate(const tView *pView, UWORD uwRawCopPos) {
 	// TODO: add support for non-chained mode (setting sprxdat with copper)?
 	s_pView = pView;
@@ -132,6 +141,10 @@ void spriteSetEnabled(tSprite *pSprite, UBYTE isEnabled) {
 	pSprite->isEnabled = isEnabled;
 	// TODO: only after modifying first sprite in chain, change next sprite ptr in the prior one
 	s_pChannelsData[pSprite->ubChannelIndex].ubCopperRegenCount = 2; // for front/back buffers
+
+	if (pSprite->is4PP) {
+		s_pChannelsData[pSprite->ubChannelIndex+1].ubCopperRegenCount = 2;
+	}
 }
 
 void spriteSetAttached(tSprite *pSprite, UBYTE isAttached) {
@@ -153,9 +166,9 @@ void spriteRequestMetadataUpdate(tSprite *pSprite) {
 }
 
 void spriteSetBitmap(tSprite *pSprite, tBitMap *pBitmap) {
-	if(!(pBitmap->Flags & BMF_INTERLEAVED) || pBitmap->Depth != 2) {
+	if(!(pBitmap->Flags & BMF_INTERLEAVED) || (pBitmap->Depth != 2  && (pBitmap->Depth != 4 || (pSprite->ubChannelIndex & 1) == 1))) {
 		logWrite(
-			"ERR: Sprite channel %hhu bitmap %p isn't interleaved 2BPP\n",
+			"ERR: Sprite channel %hhu bitmap %p isn't interleaved 2BPP(for any channel) or 4BPP(for an even channel)\n",
 			pSprite->ubChannelIndex, pBitmap
 		);
 		return;
@@ -170,11 +183,50 @@ void spriteSetBitmap(tSprite *pSprite, tBitMap *pBitmap) {
 		return;
 	}
 
-	pSprite->pBitmap = pBitmap;
-	spriteSetHeight(pSprite, pBitmap->Rows - 2);
+	if (pBitmap->Depth == 2) {
+		pSprite->pBitmap = pBitmap;
+		spriteSetHeight(pSprite, pBitmap->Rows - 2);
 
-	tSpriteChannel *pChannel = &s_pChannelsData[pSprite->ubChannelIndex];
-	spriteChannelRequestCopperUpdate(pChannel);
+		tSpriteChannel *pChannel = &s_pChannelsData[pSprite->ubChannelIndex];
+		spriteChannelRequestCopperUpdate(pChannel);
+	}
+	if (pBitmap->Depth == 4) {
+
+		pSprite->is4PP=1;
+
+		tBitMap *pointers_low;
+		tBitMap *pointers_high;
+
+        pointers_high = bitmapCreate(
+            ubByteWidth*8, pBitmap->Rows,
+            2, BMF_CLEAR | BMF_INTERLEAVED);
+
+        pointers_low = bitmapCreate(
+            ubByteWidth*8, pBitmap->Rows,
+            2, BMF_CLEAR | BMF_INTERLEAVED);
+
+		// Convert the 4bpp bitmap to 2bpp.
+        for (UWORD r = 0; r < pBitmap->Rows; r++)
+        {
+            UWORD offetSrc = r * pBitmap->BytesPerRow;
+            UWORD offetDst = r * pointers_low->BytesPerRow;
+            memcpy(pointers_low->Planes[0] + offetDst, pBitmap->Planes[0] + offetSrc, ubByteWidth);
+            memcpy(pointers_low->Planes[1] + offetDst, pBitmap->Planes[1] + offetSrc, ubByteWidth);
+            memcpy(pointers_high->Planes[0] + offetDst, pBitmap->Planes[2] + offetSrc, ubByteWidth);
+            memcpy(pointers_high->Planes[1] + offetDst, pBitmap->Planes[3] + offetSrc, ubByteWidth);
+        }
+
+		pSprite->pBitmap = pointers_low;
+		spriteSetHeight(pSprite, pointers_low->Rows - 2);
+
+		tSpriteChannel *pChannel = &s_pChannelsData[pSprite->ubChannelIndex];
+		spriteChannelRequestCopperUpdate(pChannel);
+
+
+		tSprite *attached_sprite = spriteAdd(pSprite->ubChannelIndex+1, pointers_high);
+
+		spriteSetAttached(attached_sprite, 1);
+	}
 }
 
 void spriteProcessChannel(UBYTE ubChannelIndex) {
@@ -214,6 +266,40 @@ void spriteProcessChannel(UBYTE ubChannelIndex) {
 		copSetMoveVal(&pList[0].sMove, ulSprAddr >> 16);
 		copSetMoveVal(&pList[1].sMove, ulSprAddr & 0xFFFF);
 	}
+
+	if (pSprite->is4PP) {
+		spriteProcessChannel(ubChannelIndex+1);
+	}
+}
+
+
+void spriteSetPos(tSprite *pSprite,WORD wX, WORD wY) {
+	pSprite->wX = wX;
+	pSprite->wY = wY;
+	pSprite->isHeaderToBeUpdated = 1;
+	if (pSprite->is4PP) {
+		tSprite *pAttachedSprite = get4BPPAttachedSprite(pSprite);
+		pAttachedSprite->wX = wX;
+		pAttachedSprite->wY = wY;
+	}
+}
+
+void spriteSetPosX(tSprite *pSprite,WORD wX) {
+	pSprite->wX = wX;
+	pSprite->isHeaderToBeUpdated = 1;
+	if (pSprite->is4PP) {
+		tSprite *pAttachedSprite = get4BPPAttachedSprite(pSprite);
+		pAttachedSprite->wX = wX;
+	}
+}
+
+void spriteSetPosY(tSprite *pSprite, WORD wY) {
+	pSprite->wY = wY;
+	pSprite->isHeaderToBeUpdated = 1;
+	if (pSprite->is4PP) {
+		tSprite *pAttachedSprite = get4BPPAttachedSprite(pSprite);
+		pAttachedSprite->wY = wY;
+	}
 }
 
 void spriteProcess(tSprite *pSprite) {
@@ -246,6 +332,10 @@ void spriteProcess(tSprite *pSprite) {
 		BTST(uwHStart, 0)
 	);
 
+	if (pSprite->is4PP) {
+		tSprite *pAttachedSprite = get4BPPAttachedSprite(pSprite);
+		spriteProcess(pAttachedSprite);
+	}
 }
 
 void spriteSetHeight(tSprite *pSprite, UWORD uwHeight) {