cpct_etm_drawTileBox2x4

Draws (or redraws) a determined rectangle of tiles inside a tilemap.  It is mainly used to restore parts of a tilemap.

C Definition

void cpct_etm_drawTileBox2x4 (u8 x, u8 y, u8 w, u8 h, u8 map_width, void* pvideomem, const void* ptilemap ) __z88dk_callee;

Input Parameters (9 bytes)

• Always received on the stack

Assembly call (Input parameters on registers)

call cpct_etm_drawTileBox2x4_asm

It is important to notice that part of the parameters are received on registers and part of them on the stack.  This would be an example code for calling this function,

;; Set Parameters on the stack
ld   hl, #ptilemap   ;; HL = pointer to the tilemap
push hl              ;; Push ptilemap to the stack
ld   hl, #pvideomem  ;; HL = Pointer to video memory location where tilemap is drawn
push hl              ;; Push pvideomem to the stack
;; Set Paramters on registers
ld    a, #map_width  ;; A = map_width
ld    b, #y          ;; B = x tile-coordinate
ld    c, #x          ;; C = y tile-coordinate
ld    d, #h          ;; H = height in tiles of the tile-box
ld    e, #w          ;; L =  width in tiles of the tile-box
call  cpct_etm_drawTileBox2x4_asm ;; Call the function

Parameter Restrictions

• (x, y) represent the coordinates, in tiles, of the upper-left corner of the tilebox to be drawn.  These coordinates are relative to the upper-left corner of the tilemap (its first tile).  They are not checked to be inside the tilemap, and providing bad coordinates leads to undefined behaviour.  Supported ranges for this coordinates are: x in [1,127] and y in [1,63] (However, y >= 50 will be outside normal screen, because 50*4 = 200 pixels, which is the height of a normal screen).
• (w, h) represent the width and height, in tiles, of the tilebox being drawn.  Same as (x, y), these values are not checked and values drawing outside the tilemap or beyond the screen could be provided, and would lead to undefined behaviour.
• map_width is expected to be the width of the tilemap in tiles.  Do not confuse this value with w, that represents the width of the tilebox (please note the difference).  Maximum width of the tilemap is 255 tiles, as it is a u8 value.  However, take into account that maps wider than 127 tiles can represent a problem, as the initial x parameter of this function cannot be greater than 127.
• pvideomem should be a pointer to the video memory or backbuffer address where the upper-left corner of the tilemap is drawn.  Please note that it should point to the start of the tilemap, and NOT the start of the tilebox, in video memory or backbuffer.
• ptilemap should be a 2-bytes pointer to the start of a tilemap definition in Easytilemaps format: a 2D matrix of 1-byte tile-indexes.  If it points to a different kind of data, the result is undefined (most likely a crash or rubbish on the screen).

Known limitations

• This function does not do any kind of checking over the tilemap, its contents or size.  If you give a wrong pointer, your tilemap has different dimensions than required or has less / more tiles than will be used later, rubbish can appear on the screen.
• The pvideomem pointer must point to a pixel line 0 or pixel line 4 from any character line on the screen or back buffer.  To know where pixel lines 0/4 are located you may have a look at cpct_drawSprite documentation.
• This function only draws 8-bytes tiles of size 2x4 (in bytes).
• This function will not work from ROM, as it uses self-modifying code.
• Under hardware scroll conditions, tile drawing will fail if asked to draw near 0x?7FF or 0x?FFF addresses (at the end of each one of the 8 pixel lines), as next screen byte at that locations is -0x7FF and not +1 bytes away.

Details

This function draws tile-box, a portion of a concrete tilemap, to the screen or to a backbuffer.  A tile-box is a group of tiles forming a rectangular box, and being part of a tilemap.  Data is expected to be in Easytilemaps format, with the tilemap being a 2D matrix of 1-byte tile-indexes, and tileset being an array of pointers (2-bytes each) to tiles.  Each tile is expected to be an array of 2x4-bytes in screen pixel format.

The main intended use of this function is to erase entities that move over a tilemap, redrawing the portion of the tilemap (a tilebox) over the moving entity.

So, first 4 parameters (x, y, w, h) of these function define the tilebox as a portion of the given tilemap (last parameter).  First 2 parameters locate the upper-left corner of the tilebox (x, y) and the next two define its width (w) and height (h) in tiles.  x and y coordinates are considered relative to the upper-left corner of the tilemap (which is the origin of coordinates, (0,0)), with x’s growing right and y’s growing down.

This function uses the internal pointer to the tileset (ptileset) for Easytilemaps.  This internal pointer MUST HAVE BEEN SET PREVIOUSLY to calling this function.  cpct_etm_setTileset2x4 may be used for setting this internal pointer.  Once set it remains unless manually reset.

This function calls cpct_etm_drawTileRow2x4, which also calls cpct_drawTileAligned2x4_f.  So, these two functions will also be included in your code when using cpct_etm_drawTileBox2x4 (using their assembly bindings).

Destroyed Register values

AF, BC, DE, HL AF’, BC’, DE’, HL’

Required memory

Time Measures

   Case     |      microSecs (us)                |              CPU Cycles                 |
--------------------------------------------------------------------------------------------
   Any      | 98 + PX + MY + 7PPY + (37 + 103W)H | 392 + 4PX + 4MY + 28PPY + (148 + 412W)H |
--------------------------------------------------------------------------------------------
 ASM-Saving |            - 10                    |               - 40                      |
--------------------------------------------------------------------------------------------
 W=2, H=3   |         [ 845 - 937 ]              |           [ 3380 - 3748 ]               |
--------------------------------------------------------------------------------------------
 W=4, H=6   |        [ 2824 - 2916 ]             |          [ 11296 - 11664 ]               |
--------------------------------------------------------------------------------------------

MY = 12*int(log2(y)) + 2*onbits(y) - 1,
// onbits(y) = the number of bits that y has set to 1

MY is in range [11-83]

PPY = int(H/2)
PPY = int(H/2) - 1