git.y1.nz

commit 30b29e9be567a0733e53869f01551574fe6b1fc1
parent 5d8434767276e4b905d98493ade0c06746cc2330
Author: Toxa <56631470+untoxa@users.noreply.github.com>
Date:   Thu, 22 Apr 2021 14:46:50 +0300

Merge pull request #176 from bbbbbr/metasprite_cgb

Improvements for Metasprites and sprite property flags
Diffstat:
M
docs/pages/08_faq.md
7
+++++--
M
docs/pages/20_toolchain_settings.md
1
+
M
gbdk-lib/include/gb/metasprites.h
34
++++++++++++++++++++++++++++++++--
M
gbdk-support/png2mtspr/png2mtspr.cpp
28
+++++++++++++++++-----------

4 files changed, 55 insertions(+), 15 deletions(-)
diff --git a/docs/pages/08_faq.md b/docs/pages/08_faq.md
@@ -49,4 +49,8 @@
 
 - When using gbt_player with music in banks, how can the current bank be restored after calling gbt_update()? (since it changes the currently active bank without restoring it).
   - See @ref banking_current_bank "restoring the current bank"
-    <!-- -->  
-
+    <!-- -->  
+
+- How can CGB palettes and other sprite properties be used with metasprites?
+  - See @ref metasprite_and_sprite_properties "Metasprites and sprite properties"
+    <!-- -->    
diff --git a/docs/pages/20_toolchain_settings.md b/docs/pages/20_toolchain_settings.md
@@ -535,6 +535,7 @@ usage: png2mtspr <file>.png [options]
 -c            ouput file (default: <png file>.c)
 -sw <width>   metasprites width size (default: png width)
 -sh <height>  metasprites height size (default: png height)
+-sp <props>   change default for sprite OAM property bytes (in hex) (default: 0x00)
 -px <x coord> metasprites pivot x coordinate (default: metasprites width / 2)
 -py <y coord> metasprites pivot y coordinate (default: metasprites height / 2)
 -spr8x8       use SPRITES_8x8 (default: SPRITES_8x16)
diff --git a/gbdk-lib/include/gb/metasprites.h b/gbdk-lib/include/gb/metasprites.h
@@ -1,6 +1,6 @@
 /** @file gb/metasprites.h
     
-    Metasprite support
+    # Metasprite support
 
     A metasprite is a larger sprite made up from a 
     collection of smaller individual hardware sprites.
@@ -20,6 +20,24 @@
     or multiple frames of graphics into metasprite
     structured data for use with the ...metasprite...()
     functions.
+
+    @anchor metasprite_and_sprite_properties
+    # Metasprites and sprite properties (including cgb palette)
+
+    When the move_metasprite_*() functions are called they
+    update all properties for the affected sprites in the
+    Shadow OAM. This means any existing property flags set
+    for a sprite (CGB palette, BG/WIN priority, Tile VRAM Bank)
+    will get overwritten.
+
+    How to use sprite property flags with metasprites: 
+    - Metsaprite structures can be copied into RAM so their
+      property flags can be modified at runtime.
+    - The metasprite structures can have the property flags
+      modified before compilation (such as with `-sp <props>`
+      in the @ref utility_png2mtspr "png2mtspr" tool).
+    - Update properties for the affected sprites after calling
+      a move_metasprite_*() function.
 */
 
 #ifndef _METASPRITES_H_INCLUDE
@@ -73,6 +91,9 @@ static void __hide_metasprite(UINT8 id);
     \li __current_metasprite = metasprite; 
     \li __current_base_tile = base_tile;
 
+    Note: Overwrites OAM sprite properties (such as CGB Palette), see
+          @ref metasprite_and_sprite_properties "Metasprites and sprite properties".
+
     @return Number of hardware sprites used to draw this metasprite
  */
 inline UBYTE move_metasprite(const metasprite_t * metasprite, UINT8 base_tile, UINT8 base_sprite, UINT8 x, UINT8 y) {
@@ -95,6 +116,9 @@ inline UBYTE move_metasprite(const metasprite_t * metasprite, UINT8 base_tile, U
     \li __current_metasprite = metasprite; 
     \li __current_base_tile = base_tile;
 
+    Note: Overwrites OAM sprite properties (such as CGB palette), see
+          @ref metasprite_and_sprite_properties "Metasprites and sprite properties".
+
     @return Number of hardware sprites used to draw this metasprite
 
     @see move_metasprite()
@@ -120,6 +144,9 @@ inline UBYTE move_metasprite_vflip(const metasprite_t * metasprite, UINT8 base_t
     \li __current_metasprite = metasprite; 
     \li __current_base_tile = base_tile;
 
+    Note: Overwrites OAM sprite properties (such as CGB palette), see
+          @ref metasprite_and_sprite_properties "Metasprites and sprite properties".
+
     @return Number of hardware sprites used to draw this metasprite
 
     @see move_metasprite()
@@ -144,6 +171,9 @@ inline UBYTE move_metasprite_hflip(const metasprite_t * metasprite, UINT8 base_t
     \li __current_metasprite = metasprite; 
     \li __current_base_tile = base_tile;
 
+    Note: Overwrites OAM sprite properties (such as CGB palette), see
+          @ref metasprite_and_sprite_properties "Metasprites and sprite properties".
+
     @return Number of hardware sprites used to draw this metasprite
 
     @see move_metasprite()
@@ -160,7 +190,7 @@ inline UBYTE move_metasprite_hvflip(const metasprite_t * metasprite, UINT8 base_
     @param base_sprite   Number of hardware sprite to start with
 
     Sets:
-    \li __current_metasprite = metasprite; 
+    \li __current_metasprite = metasprite;
 
  **/
 inline void hide_metasprite(const metasprite_t * metasprite, UINT8 base_sprite) {
diff --git a/gbdk-support/png2mtspr/png2mtspr.cpp b/gbdk-support/png2mtspr/png2mtspr.cpp
@@ -76,6 +76,7 @@ vector< Tile > tiles;
 vector<	MetaSprite > sprites;
 PNGImage image;
 int tile_h;
+int props_default = 0x00;  // Default Sprite props has no attributes enabled
 
 Tile FlipH(const Tile& tile)
 {
@@ -111,7 +112,7 @@ bool FindTile(const Tile& t, unsigned char& idx, unsigned char& props)
 	if(it != tiles.end())
 	{
 		idx = (unsigned char)(it - tiles.begin());
-		props = 0;
+		props = props_default;
 		return true;
 	}
 	
@@ -120,7 +121,7 @@ bool FindTile(const Tile& t, unsigned char& idx, unsigned char& props)
 	if(it != tiles.end())
 	{
 		idx = (unsigned char)(it - tiles.begin());
-		props = 1 << 5;
+		props = props_default | (1 << 5);
 		return true;
 	}
 
@@ -129,7 +130,7 @@ bool FindTile(const Tile& t, unsigned char& idx, unsigned char& props)
 	if(it != tiles.end())
 	{
 		idx = (unsigned char)(it - tiles.begin());
-		props = (1 << 5) | (1 << 6);
+		props = props_default | (1 << 5) | (1 << 6);
 		return true;
 	}
 
@@ -138,7 +139,7 @@ bool FindTile(const Tile& t, unsigned char& idx, unsigned char& props)
 	if(it != tiles.end())
 	{
 		idx = (unsigned char)(it - tiles.begin());
-		props = 1 << 6;
+		props = props_default | (1 << 6);
 		return true;
 	}
 
@@ -165,7 +166,7 @@ void GetMetaSprite(int _x, int _y, int _w, int _h, int pivot_x, int pivot_y)
 				{
 					tiles.push_back(tile);
 					idx = (unsigned char)tiles.size() - 1;
-					props = 0;
+					props = props_default;
 				}
 
 				if(tile_h == 16)
@@ -190,6 +191,7 @@ int main(int argc, char *argv[])
 		printf("-c            ouput file (default: <png file>.c)\n");
 		printf("-sw <width>   metasprites width size (default: png width)\n");
 		printf("-sh <height>  metasprites height size (default: png height)\n");
+		printf("-sp <props>   change default for sprite OAM property bytes (in hex) (default: 0x00)\n");
 		printf("-px <x coord> metasprites pivot x coordinate (default: metasprites width / 2)\n");
 		printf("-py <y coord> metasprites pivot y coordinate (default: metasprites height / 2)\n");
 		printf("-spr8x8       use SPRITES_8x8 (default: SPRITES_8x16)\n");
@@ -219,6 +221,10 @@ int main(int argc, char *argv[])
 		{
 			sprite_h = atoi(argv[++ i]);
 		}
+        else if(!strcmp(argv[i], "-sp"))
+		{
+			props_default = strtol(argv[++ i], NULL, 16);
+		}
 		if(!strcmp(argv[i], "-px"))
 		{
 			pivot_x = atoi(argv[++ i]);
@@ -295,8 +301,8 @@ int main(int argc, char *argv[])
 	fprintf(file, "#define %s_PIVOT_X %d\n", data_name.c_str(), pivot_x);
 	fprintf(file, "#define %s_PIVOT_Y %d\n", data_name.c_str(), pivot_y);
 	fprintf(file, "\n");
-	fprintf(file, "extern const UINT8 %s_data[%d];\n", data_name.c_str(), tiles.size() * tile_h * 2);
-	fprintf(file, "extern const metasprite_t* const %s_metasprites[%d];\n", data_name.c_str(), sprites.size());
+	fprintf(file, "extern const UINT8 %s_data[%ld];\n", data_name.c_str(), tiles.size() * tile_h * 2);
+	fprintf(file, "extern const metasprite_t* const %s_metasprites[%ld];\n", data_name.c_str(), sprites.size());
 
 	fclose(file);
 
@@ -315,7 +321,7 @@ int main(int argc, char *argv[])
 	if(bank)
 		fprintf(file, "#pragma bank %d\n\n", bank);
 
-	fprintf(file, "const UINT8 %s_data[%d] = {\n", data_name.c_str(), tiles.size() * tile_h * 2);
+	fprintf(file, "const UINT8 %s_data[%ld] = {\n", data_name.c_str(), tiles.size() * tile_h * 2);
 	for(vector< Tile >::iterator it = tiles.begin(); it != tiles.end(); ++ it)
 	{
 		for(Tile::iterator it2 = (*it).begin(); it2 != (*it).end(); ++ it2)
@@ -332,7 +338,7 @@ int main(int argc, char *argv[])
 
 	for(vector< MetaSprite >::iterator it = sprites.begin(); it != sprites.end(); ++ it)
 	{
-		fprintf(file, "const metasprite_t %s_metasprite%d[] = {\n", data_name.c_str(), it - sprites.begin());
+		fprintf(file, "const metasprite_t %s_metasprite%ld[] = {\n", data_name.c_str(), it - sprites.begin());
 		fprintf(file, "\t");
 		for(MetaSprite::iterator it2 = (*it).begin(); it2 != (*it).end(); ++ it2)
 		{
@@ -343,10 +349,10 @@ int main(int argc, char *argv[])
 		fprintf(file, "};\n\n");	
 	}
 
-	fprintf(file, "const metasprite_t* const %s_metasprites[%d] = {\n\t", data_name.c_str(), sprites.size());
+	fprintf(file, "const metasprite_t* const %s_metasprites[%ld] = {\n\t", data_name.c_str(), sprites.size());
 	for(vector< MetaSprite >::iterator it = sprites.begin(); it != sprites.end(); ++ it)
 	{
-		fprintf(file, "%s_metasprite%d", data_name.c_str(), it - sprites.begin());
+		fprintf(file, "%s_metasprite%ld", data_name.c_str(), it - sprites.begin());
 		if(it + 1 != sprites.end())
 			fprintf(file, ", ");
 	}

This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.