romdev-mcp 0.1.1

package/src/platforms/genesis/lib/sgdk/include/map.h

@@ -0,0 +1,409 @@
+/**
+ *  \file map.h
+ *  \brief MAP (large background map) management unit
+ *  \author Stephane Dallongeville
+ *  \date 11/2020
+ *
+ * This unit provides methods to manipulate / scroll large background MAP:<br>
+ * - Create / release MAP object<br>
+ * - MAP decoding functions<br>
+ * - Large MAP scrolling engine<br>
+ * <br>
+ * Using MAP resource you can encode large image as a #MapDefinition structure which will be
+ * used to handle large background scrolling. The #MapDefinition structure is optimized to encode
+ * large map efficiently (space wise), here's the encoding format:<br>
+ * - background map is encoded as a grid of 128x128 pixels blocks<br>
+ * - duplicated 128x128 blocks are optimized (keep only 1 reference)<br>
+ * - each 128x128 blocks is encoded internally as a 8x8 grid of metatile<br>
+ * - a metatile is a 16x16 pixels block (2x2 tiles block)<br>
+ * - each duplicated / flipped metatile are optimized.<br>
+ * <br>
+ * Knowing that you can draw your level background to optimize its space usage by trying to optimize<br>
+ * the number of unique 128x128 pixels block.
+ *
+ */
+
+#ifndef _MAP_H_
+#define _MAP_H_
+
+
+#include "vdp.h"
+#include "vdp_tile.h"
+#include "pal.h"
+
+// forward
+typedef struct Map Map;
+
+/**
+ *  \brief
+ *      Map data update type
+ */
+typedef enum
+{
+    ROW_UPDATE,        /** tilemap row update **/
+    COLUMN_UPDATE      /** tilemap column update **/
+} MapUpdateType;
+
+/**
+ *  \brief
+ *      Map data patch callback.<br>
+ *      It's used to modify/patch map data (for destructible blocks for instance) before sending it to VRAM.
+ *
+ *  \param map
+ *      source Map structure containing map information.
+ *  \param buf
+ *      buffer containing the tilemap data to patch
+ *  \param x
+ *      tile X start update position
+ *  \param y
+ *      tile Y start update position
+ *  \param updateType
+ *      map data update type:<br>
+ *      - ROW_UPDATE (tilemap row update)<br>
+ *      - COLUMN_UPDATE (tilemap column update)<br>
+ *  \param size
+ *      size of the buffer (tilemap width or height depending we are on a row or column update type)
+ */
+typedef void MapDataPatchCallback(Map *map, u16 *buf, u16 x, u16 y, MapUpdateType updateType, u16 size);
+
+
+/**
+ *  \brief
+ *      MapDefinition structure which contains data for large level background.<br>
+ *      It's optimized to encode large map using 128x128 block chunk (block chunk are organized in metatile).
+ *
+ *  \param w
+ *      map width in block (128x128 pixels block).
+ *  \param h
+ *      map height in block (128x128 pixels block).
+ *  \param hp
+ *      map height in block (128x128 pixels block) removing duplicated rows
+ *  \param compression
+ *      b0-b3=compression type for metaTiles<br>
+ *      b4-b7=compression for blocks data<br>
+ *      b8-b11=compression for blockIndexes data<br>
+ *      Accepted values:<br>
+ *        <b>COMPRESSION_NONE</b><br>
+ *        <b>COMPRESSION_APLIB</b><br>
+ *        <b>COMPRESSION_LZ4W</b><br>
+ *  \param numMetaTile
+ *      number of MetaTile
+ *  \param numBlock
+ *      number of Block (128x128 pixels chunk)
+ *  \param metaTiles
+ *      metatiles definition, each metatile is encoded as 2x2 tiles block:<br>
+ *      - b15: priority<br>
+ *      - b14-b13: palette<br>
+ *      - b12: vflip<br>
+ *      - b11: hflip<br>
+ *      - b10-b0: tile index (from tileset)
+ *  \param blocks
+ *      blocks definition, each block is encoded as 8x8 metatiles:<br>
+ *      if numMetaTile <= 256 --> 8 bit index for metaTile<br>
+ *      else --> 16 bit index for metaTile
+ *  \param blockIndexes
+ *      block index array (referencing blocks) for the w * hp sized map<br>
+ *      if numBlock <= 256 --> 8 bit index for block
+ *      else --> 16 bit index for block
+ *  \param blockRowOffsets
+ *      block row offsets used internally for fast retrieval of block data (index = blockIndexes[blockRowOffsets[y] + x])
+ */
+typedef struct
+{
+    u16 w;
+    u16 h;
+    u16 hp;
+    u16 compression;
+    u16 numMetaTile;
+    u16 numBlock;
+    u16 *metaTiles;
+    void* blocks;
+    void* blockIndexes;
+    u16* blockRowOffsets;
+} MapDefinition;
+
+/**
+ *  \brief
+ *      Map structure containing information for large background/plane update based on #MapDefinition
+ *
+ *  \param w
+ *      map width in block (128x128 pixels block)
+ *  \param h
+ *      map height in block (128x128 pixels block)
+ *  \param metaTiles
+ *      internal - unpacked data of MapDefinition.metaTiles
+ *  \param blocks
+ *      internal - unpacked data of MapDefinition.blocks
+ *  \param blockIndexes
+ *      internal - unpacked data of MapDefinition.blockIndexes
+ *  \param blockRowOffsets
+ *      internal - direct access of MapDefinition.blockRowOffsets
+ *  \param plane
+ *      VDP plane where MAP is draw
+ *  \param baseTile
+ *      Base tile attributes used to provide base tile index offset and base palette index (see TILE_ATTR_FULL() macro)
+ *  \param posX
+ *      current view position X set using #MAP_scrollTo(..) method
+ *  \param posY
+ *      current view position Y set using #MAP_scrollTo(..) method
+ *  \param wMask
+ *      internal
+ *  \param hMask
+ *      internal
+ *  \param planeWidthMask
+ *      internal
+ *  \param planeHeightMask
+ *      internal
+ *  \param lastXT
+ *      internal
+ *  \param lastYT
+ *      internal
+ *  \param hScrollTable
+ *      internal
+ *  \param vScrollTable
+ *      internal
+ *  \param prepareMapDataColumnCB
+ *      internal
+ *  \param prepareMapDataRowCB
+ *      internal
+ *  \param patchMapDataColumnCB
+ *      internal
+ *  \param patchMapDataRowCB
+ *      internal
+ *  \param getMetaTileCB
+ *      internal
+ *  \param getMetaTilemapRectCB
+ *      internal
+ */
+typedef struct Map
+{
+    u16 w;
+    u16 h;
+    u16* metaTiles;
+    void* blocks;
+    void* blockIndexes;
+    u16* blockRowOffsets;
+    VDPPlane plane;
+    u16 baseTile;
+    u32 posX;
+    u32 posY;
+    u16 wMask;
+    u16 hMask;
+    u16 planeWidth;
+    u16 planeHeight;
+    u16 planeWidthMaskAdj;
+    u16 planeHeightMaskAdj;
+    u16 planeWidthSftAdj;
+    u16 firstUpdate;
+    u16 lastXT;
+    u16 lastYT;
+    u16 hScrollTable[240];
+    u16 vScrollTable[20];
+    void (*prepareMapDataColumnCB)(Map *map, u16 *bufCol1, u16 *bufCol2, u16 xm, u16 ym, u16 height);
+    void (*prepareMapDataRowCB)(Map *map, u16 *bufRow1, u16 *bufRow2, u16 xm, u16 ym, u16 width);
+    MapDataPatchCallback* mapDataPatchCB;
+    u16  (*getMetaTileCB)(Map *map, u16 x, u16 y);
+    void (*getMetaTilemapRectCB)(Map *map, u16 x, u16 y, u16 w, u16 h, u16* dest);
+} Map;
+
+
+/**
+ *  \brief
+ *      Create and return a Map structure required to use all MAP_xxx functions
+ *      from a given MapDefinition.<br>
+ *      When you're done with the map you shall use MAP_release(map) to release it.
+ *
+ *  \param mapDef
+ *      MapDefinition structure containing background/plane data.
+ *  \param plane
+ *      Plane where we want to draw the Map (for #MAP_scrollTo(..) method).<br>
+ *      Accepted values are:<br>
+ *      - BG_A<br>
+ *      - BG_B<br>
+ *      If you want to use the map for collision or special behavior (using the MAP_getTile(..) method) then you can just let this parameter to 0.
+ *  \param baseTile
+ *      Used to provide base tile index and base palette index (see TILE_ATTR_FULL() macro).<br>
+ *      Note that you can also use it to force HIGH priority but in that case your map should only contains LOW priority tiles
+ *      otherwise the HIGH priority tiles will be set in LOW priority instead (mutually exclusive).
+ *  \return initialized Map structure or <i>NULL</i> if there is not enough memory to allocate data for given MapDefinition.
+ */
+Map* MAP_create(const MapDefinition* mapDef, VDPPlane plane, u16 baseTile);
+
+/**
+ *  \brief
+ *      Release the map and its resources (same as MEM_free(map))
+ *
+ *  \param map
+ *      the Map structure to release
+ */
+void MAP_release(Map* map);
+
+/**
+ *  \brief
+ *      Scroll map to specified position.<br>
+ *      The fonction takes care of updating the VDP tilemap which will be transfered by DMA queue then
+ *      VDP background scrolling is automatically set on VBlank (into the SYS_doVBlankProcess() tasks).<br>
+ *      WARNING: first MAP_scrollTo(..) call will do a full plane update, for a 64x32 sized plane this represents 4KB of data.<br>
+ *      That means you can't initialize 2 MAPs in the same frame (limited to 7.2 KB of data per frame) so take care of calling
+ *      SYS_doVBlankProcess() in between.
+ *
+ *  \param map
+ *      source Map structure containing map information.
+ *  \param x
+ *      view position X we want to scroll on
+ *  \param y
+ *      view position Y we want to scroll on
+ *
+ *  \see #MAP_create(..)
+ */
+void MAP_scrollTo(Map* map, u32 x, u32 y);
+/**
+ *  \brief
+ *      Exactly as #MAP_scrollTo(..) except we can force complete map drawing
+ *
+ *  \param map
+ *      source Map structure containing map information.
+ *  \param x
+ *      view position X we want to scroll on
+ *  \param y
+ *      view position Y we want to scroll on
+ *  \param forceRedraw
+ *      Set to <i>TRUE</i> to force a complete map redraw (take more time)
+ *
+ *  \see #MAP_scrollTo(..)
+ */
+void MAP_scrollToEx(Map* map, u32 x, u32 y, bool forceRedraw);
+
+/**
+ *  \brief
+ *      Returns metatile index / number at given position (a metatile is a block of 2x2 tiles = 16x16 pixels)
+ *
+ *  \param map
+ *      source Map structure containing map information.
+ *  \param x
+ *      metatile X position (16x16 pixels block)
+ *  \param y
+ *      metatile Y position (16x16 pixels block)
+ *
+ *  \return
+ *      metatile index
+ *
+ *  \see #MAP_create(..)
+ *  \see #MAP_getTile(..)
+ *  \see #MAP_getMetaTilemapRect(..)
+ */
+u16 MAP_getMetaTile(Map* map, u16 x, u16 y);
+/**
+ *  \brief
+ *      Returns given tile attribute (note than map->baseTile isn't added to the result)
+ *
+ *  \param map
+ *      source Map structure containing map information.
+ *  \param x
+ *      tile X position
+ *  \param y
+ *      tile Y position
+ *
+ *  \return
+ *      tile attribute:<br>
+ *      - b15: priority<br>
+ *      - b14-b13: palette<br>
+ *      - b12: vflip<br>
+ *      - b11: hflip<br>
+ *      - b10-b0: tile index
+ *
+ *  \see #MAP_create(..)
+ *  \see #MAP_getMetaTile(..)
+ *  \see #MAP_getTilemapRect(..)
+ */
+u16 MAP_getTile(Map* map, u16 x, u16 y);
+/**
+ *  \brief
+ *      Returns metatiles index for the specified region (a metatile is a block of 2x2 tiles = 16x16 pixels)
+ *
+ *  \param map
+ *      source Map structure containing map information.
+ *  \param x
+ *      Region X start position (in metatile - 16x16 pixels block).
+ *  \param y
+ *      Region Y start position (in metatile - 16x16 pixels block).
+ *  \param w
+ *      Region Width (in metatile).
+ *  \param h
+ *      Region Heigh (in metatile).
+ *  \param dest
+ *      destination pointer receiving metatiles attribute data
+ *
+ *  \return
+ *      metatiles index
+ *
+ *  \see #MAP_create(..)
+ *  \see #MAP_getTilemapRect(..)
+ */
+void MAP_getMetaTilemapRect(Map* map, u16 x, u16 y, u16 w, u16 h, u16* dest);
+/**
+ *  \brief
+ *      Returns tiles attribute data for the specified region (map->baseTile is used as base tiles attribute, see #MAP_create(..))
+ *
+ *  \param map
+ *      source Map structure containing map information.
+ *  \param x
+ *      Region X start position <b>(in metatile)</b>
+ *  \param y
+ *      Region Y start position <b>(in metatile)</b>
+ *  \param w
+ *      Region Width <b>(in metatile)</b>
+ *  \param h
+ *      Region Heigh <b>(in metatile)</b>
+ *  \param column
+ *      if set to TRUE then tilemap data is stored by column order [Y,X] instead of row order [X,Y].
+ *  \param dest
+ *      destination pointer receiving tiles attribute data
+ *
+ *  \return
+ *      tiles attribute:<br>
+ *      - b15: priority<br>
+ *      - b14-b13: palette<br>
+ *      - b12: vflip<br>
+ *      - b11: hflip<br>
+ *      - b10-b0: tile index
+ *
+ *  \see #MAP_create(..)
+ *  \see #MAP_getTile(..)
+ *  \see #MAP_getMetaTilemapRect(..)
+ */
+void MAP_getTilemapRect(Map* map, u16 x, u16 y, u16 w, u16 h, bool column, u16* dest);
+
+/**
+ *  \brief
+ *      Set the callback function to patch tilemap data.<br>
+ *      Note that you need to set
+ *<br>
+ *      The method will be called when a new tilemap row / column is ready to be send to the VDP.<br>
+ *      You can use this callback to modify the tilemap data before sending it to VRAM.<br>
+ *      It can be useful, for instance, to implement destructibles blocks.
+ *
+ *  \param map
+ *      source Map structure we want to set the patch data callback for.
+ *  \param CB
+ *      Callback to use to patch the new tilemap data (set to NULL by default = no callback).<br>
+ *      See declaration of #MapDataPatchCallback to get information about the callback parameters.
+ */
+void MAP_setDataPatchCallback(Map* map, MapDataPatchCallback *CB);
+
+/**
+ *  \brief
+ *      Override the system (VDP) plane size for this map (should be called after MAP_create(..))<br>
+ *      Useful if you have VDP plane size set to 64x64 but you want to use 64x32 for a plane so you can use spare VRAM for something else.
+ *
+ *  \param map
+ *      source Map structure we want to override VDP tilemap size for.
+ *  \param w
+ *      tilemap width (32, 64 or 128)
+ *  \param h
+ *      tilemap height (32, 64 or 128)
+ */
+void MAP_overridePlaneSize(Map* map, u16 w, u16 h);
+
+
+#endif // _MAP_H_

package/src/platforms/genesis/lib/sgdk/include/mapper.h

@@ -0,0 +1,186 @@
+/**
+ *  \file mapper.h
+ *  \brief Mapper / bank switch methods.
+ *  \author Stephane Dallongeville
+ *  \date 01/2020
+ *
+ * This unit provides tools to deal with ROM larger than 4MB.<br>
+ * It allows to do classic bank switching using the official SEGA mapper but also provide methods to get easy access to "far" data.<br>
+ * Note that you can use the ENABLE_BANK_SWITCH flag in config.h file to enable automatic bank switch on binary data access.<br>
+ *<br>
+ * SEGA official mapper description (taken from Segaretro.org):<br>
+ * The bankswitching mechanism is very simple. It views the addressable 4 mega-bytes of ROM as 8 512KB regions.<br>
+ * The first area, 0x000000-0x07FFFF is fixed and cannot be remapped because that is where the vector table resides.<br>
+ * The banking registers on the cartridge work by allocating the 512KB chunk to a given part of the addressable 4MB ROM space.<br>
+ * Below are the registers and what range they correspond to. The value written to a register will cause the specified 512KB page to be mapped to that region.<br>
+ * A page is specified with 6 bits (bits 7 and 6 are always 0) thus allowing a possible 64 pages = 32 MB (SSFII only has 10, though.)<br>
+ *<br>
+ *       0xA130F3:       0x080000 - 0x0FFFFF<br>
+ *       0xA130F5:       0x100000 - 0x17FFFF<br>
+ *       0xA130F7:       0x180000 - 0x1FFFFF<br>
+ *       0xA130F9:       0x200000 - 0x27FFFF<br>
+ *       0xA130FB:       0x280000 - 0x2FFFFF<br>
+ *       0xA130FD:       0x300000 - 0x37FFFF<br>
+ *       0xA130FF:       0x380000 - 0x3FFFFF<br>
+ *<br>
+ * The registers are accessed through byte writes.<br>
+ * Examples:<br>
+ *       If 0x01 is written to register 0xA130FF, 0x080000-0x0FFFFF is visible at 0x380000-0x3FFFFF.<br>
+ *       If 0x08 is written to register 0xA130F9, the first 512KB of the normally invisible upper 1MB of ROM is now visible at 0x200000-0x27FFFF.<br>
+ *<br>
+ * The registers simply represent address ranges in the 4MB ROM area and you can page in data to these ranges by specifying the bank #
+ */
+
+#ifndef _MAPPER_H_
+#define _MAPPER_H_
+
+
+#include "config.h"
+#include "types.h"
+
+
+#define MAPPER_BASE     0xA130F1
+
+#define BANK_SIZE       0x80000
+#define BANK_IN_MASK    (BANK_SIZE - 1)
+#define BANK_OUT_MASK   (0xFFFFFFFF ^ BANK_IN_MASK)
+
+/**
+ *  \brief
+ *      Give access to specified 'far' data through SEGA official bank switch mechanism if needed.
+ *
+ *  \see #ENABLE_BANK_SWITCH flag in config.h file
+ *  \see #SYS_getFarData(..)
+ *  \see #SYS_getFarDataSafe(..)
+ */
+#if (ENABLE_BANK_SWITCH != 0)
+    #define FAR(data) SYS_getFarData((void*) (data))
+    #define FAR_SAFE(data, size) SYS_getFarDataSafe((void*) (data), size)
+#else
+    #define FAR(data) data
+    #define FAR_SAFE(data, size) data
+#endif
+
+
+/**
+ *  \brief
+ *      Reset all banks to their initial / default value (automatically called at reset)
+ */
+void SYS_resetBanks();
+
+/**
+ *  \brief
+ *      Returns the current bank of specified region index.
+ *
+ *  \param regionIndex the 512KB region index we want to get. Accepted values: 1-7 as region 0 (0x000000-0x07FFFF) is fixed.
+ *  \return the effective 512KB data bank index mapped on this region (0 to 63)
+ */
+u16 SYS_getBank(u16 regionIndex);
+/**
+ *  \brief
+ *      Set the current bank of specified region index.
+ *
+ *  \param regionIndex the 512KB region index we want to set. Accepted values: 1-7 as region 0 (0x000000-0x07FFFF) is fixed.
+ *  \param bankIndex the effective 512KB data bank index mapped on this region. Accepted values: 0-63
+ */
+void SYS_setBank(u16 regionIndex, u16 bankIndex);
+
+/**
+ *  \brief
+ *      Make the given binary data ressource accessible and return a pointer to it.
+ *
+ *  \param data data we want to access.
+ *
+ * This method will use bank switching to make the specified data accessible and return a valid pointer to it.<br>
+ * <b>WARNING:</b> this method use the 0x00300000-0x003FFFFF range (2 regions) to make the requested data accessible using bank switching mechanism.<br>
+ * If data bank is already accessible it re-uses the region otherwise it will change bank of one of the region so be careful of that if you want to access data
+ * from different data bank at same time
+ *
+ *  \see SYS_getFarDataEx
+ *  \see SYS_getFarDataSafe
+ */
+void* SYS_getFarData(void* data);
+/**
+ *  \brief
+ *      Make the given binary data ressource accessible and return a pointer to it.
+ *
+ *  \param data far data we want to access.
+ *  \param high if set to TRUE then we use the high remappable bank for the FAR acces otherwise we use the low one
+ *
+ * This method will use bank switching to make the specified data accessible and return a valid pointer to it.<br>
+ * It will use the 0x00300000-0x0037FFFF or 0x00380000-0x003FFFFF region depending the value of <i>high</i> parameter.<br>
+ *
+ *  \see SYS_getFarData
+ *  \see SYS_getFarDataSafe
+ */
+void* SYS_getFarDataEx(void* data, bool high);
+/**
+ *  \brief
+ *      Returns TRUE if given binary data is crossing 2 512 KB banks
+ *
+ *  \param data far data pointer
+ *  \param size size (in byte) of the far data block
+ *
+ * This method return TRUE is the given binary data block is crossing 2 512 KB banks
+ *
+ *  \see SYS_getFarDataSafe
+ */
+bool SYS_isCrossingBank(void* data, u32 size);
+/**
+ *  \brief
+ *      Make the given binary data ressource accessible and return a pointer to it (safe version with possible bank crossing)
+ *
+ *  \param data far data we want to access.
+ *  \param size size (in byte) of the far data block we want to access.<br>
+ *     Note that size should be > 0, if you don't the size then use SYS_getFarData(..) method instead.
+ *
+ * This method will use bank switching to make the specified data accessible and return a valid pointer to it.<br>
+ * <b>WARNING:</b> this method use the 0x00300000-0x003FFFFF range (2 regions) to make the requested data accessible using bank switching mechanism.<br>
+ * If data bank is already accessible it re-uses the region otherwise it will change bank of one of the region so be careful of that if you want to access data
+ * from different data bank at same time :p<br>
+ * The method checks if the data is crossing banks in which case it will set the 2 switchable/remappable regions to make the data fully accessible.
+ *
+ *  \see SYS_getFarDataSafeEx
+ *  \see SYS_getFarData
+ */
+void* SYS_getFarDataSafe(void* data, u32 size);
+/**
+ *  \brief
+ *      Make the given binary data ressource accessible and return a pointer to it (safe version with possible bank crossing)
+ *
+ *  \param data address of far data we want to access.
+ *  \param size size (in byte) of the far data block we want to access.<br>
+ *     Note that size should be > 0, if you don't the size then use SYS_getFarData(..) method instead.
+ *  \param high if set to TRUE then we use the high remappable bank for the FAR acces otherwise we use the low one
+ *
+ * This method will use bank switching to make the specified data accessible and return a valid pointer to it.<br>
+ * It will use the 0x00300000-0x0037FFFF or 0x00380000-0x003FFFFF region depending the value of <i>high</i> parameter.<br>
+ * The method checks if the data is crossing banks in which case it will set the 2 switchable/remappable regions to make the data fully accessible.
+ *
+ *  \see SYS_getFarDataSafe
+ */
+void* SYS_getFarDataSafeEx(void* data, u32 size, bool high);
+
+/**
+ *  \brief
+ *      Retrieve the value of the next used region for FAR access with bank switch if data is not already accessible.
+ *
+ * This method should really be used in very specific case to know which region (6 or 7) will be used for next FAR access through bank switch but more
+ * importantly eventually to save its state and restore it with #SYS_setNextFarAccessRegion(..) later if you need to temporary change banks.
+ *
+ *  \see SYS_setNextFarAccessRegion
+ */
+bool SYS_getNextFarAccessRegion();
+/**
+ *  \brief
+ *      Set the value of the next used region for FAR access with bank switch if data is not already accessible.
+ *
+ * This method should really be used in very specific case to set which region (6 or 7) will be used for next FAR access through bank switch.<br>
+ * It can also be used to restore internal state saved it through #SYS_getNextFarAccessRegion()
+ *
+ *  \see SYS_getNextFarAccessRegion
+ *  \see SYS_getFarDataEx
+ */
+void SYS_setNextFarAccessRegion(bool high);
+
+#endif // _MAPPER_H_