git.y1.nz

commit 02b6ac03dd373d7a237cb342dab4f16981416f2c
parent 486dc36efb41765bc67b865a3a91c021b3c7c6a3
Author: bbbbbr <bbbbbr@users.noreply.github.com>
Date:   Tue, 21 Jun 2022 21:00:44 -0700

Merge pull request #384 from bbbbbr/docs_4_1_0

Docs: submap: try to further clarify coordiante systems
Diffstat:
M
gbdk-lib/include/gb/gb.h
44
++++++++++++++++++++++++++++++++------------

1 file changed, 32 insertions(+), 12 deletions(-)
diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h
@@ -1011,12 +1011,22 @@ inline void set_bkg_based_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, cons
     __x__, __y__ writing across for __w__ tiles and down for __h__ tiles,
     using __map_w__ as the rowstride for the source tile map.
 
-    The __x__ and __y__ parameters are linked in lockstep between
-    the Source Tile Map and the hardware Background Map.
-    The hardware Background Map tile coordinates will be masked
-    to the lowest 5 bits (`value & 0x1F`). In order to use them
-    out of lockstep an offset from the Source Tile Map pointer
-    can be passed in `map + x + (y * map_width)`.
+    The __x__ and __y__ parameters are in Source Tile Map tile
+    coordinates. The location tiles will be written to on the
+    hardware Background Map is derived from those, but only uses
+    the lower 5 bits of each axis, for range of 0-31 (they are
+    bit-masked: `x & 0x1F` and `y & 0x1F`). As a result the two
+    coordinate systems are aligned together.
+
+    In order to transfer tile map data in a way where the
+    coordinate systems are not aligned, an offset from the
+    Source Tile Map pointer can be passed in:
+    `(map_ptr + x + (y * map_width))`.
+
+    For example, if you want the tile id at `1,2` from the source map to
+    show up at `0,0` on the hardware Background Map (instead of at `1,2`)
+    then modify the pointer address that is passed in:
+    `map_ptr + 1 + (2 * map_width)`
 
     Use this instead of @ref set_bkg_tiles when the source map is wider than
     32 tiles or when writing a width that does not match the source map width.
@@ -1264,12 +1274,22 @@ inline void set_win_based_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, cons
     __x__, __y__ writing across for __w__ tiles and down for __h__ tiles,
     using __map_w__ as the rowstride for the source tile map.
 
-    The __x__ and __y__ parameters are linked in lockstep between
-    the Source Tile Map and the hardware Window Map.
-    The hardware Window Map tile coordinates will be masked
-    to the lowest 5 bits (`value & 0x1F`). In order to use them
-    out of lockstep an offset from the Source Tile Map pointer
-    can be passed in `map + x + (y * map_width)`.
+    The __x__ and __y__ parameters are in Source Tile Map tile
+    coordinates. The location tiles will be written to on the
+    hardware Background Map is derived from those, but only uses
+    the lower 5 bits of each axis, for range of 0-31 (they are
+    bit-masked: `x & 0x1F` and `y & 0x1F`). As a result the two
+    coordinate systems are aligned together.
+
+    In order to transfer tile map data in a way where the
+    coordinate systems are not aligned, an offset from the
+    Source Tile Map pointer can be passed in:
+    `(map_ptr + x + (y * map_width))`.
+
+    For example, if you want the tile id at `1,2` from the source map to
+    show up at `0,0` on the hardware Background Map (instead of at `1,2`)
+    then modify the pointer address that is passed in:
+    `map_ptr + 1 + (2 * map_width)`
 
     Use this instead of @ref set_win_tiles when the source map is wider than
     32 tiles or when writing a width that does not match the source map width.

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