cpct_drawTileAligned4x8

Copies a 4x8-byte sprite to video memory (or screen buffer), assuming that location to be copied is Pixel Line 0 of a character line.

C Definition

void cpct_drawTileAligned4x8 (void* sprite, void* memory) __z88dk_callee;

Input Parameters (4 bytes)

Assembly call (Input parameters on registers)

call cpct_drawTileAligned4x8_asm

Parameter Restrictions

• sprite must be a pointer to an array array containing sprite’s pixels data in screen pixel format.  Sprite must be rectangular and all bytes in the array must be consecutive pixels, starting from top-left corner and going left-to-right, top-to-bottom down to the bottom-right corner.  Total amount of bytes in pixel array should be 32.  You may check screen pixel format for mode 0 (cpct_px2byteM0) and mode 1 (cpct_px2byteM1) as for mode 2 is linear (1 bit = 1 pixel).
• memory must be a pointer to the first byte in video memory (or screen buffer) where the sprite will be drawn.  This location must be aligned, meaning that it must be a Pixel Line 0 of a screen character line.  To Know more about pixel lines and character lines on screen, take a look at cpct_drawSprite.  If memory points to a not aligned byte (one pertaining to a Non-0 Pixel Line of a character line), this function will overwrite random parts of the memory, with unexpected results (typically, bad drawing results, erratic program behaviour, hangs and crashes).

Known limitations

• This function does not do any kind of boundary check or clipping.  If you try to draw sprites on the frontier of your video memory or screen buffer if might potentially overwrite memory locations beyond boundaries.  This could cause your program to behave erratically, hang or crash.  Always take the necessary steps to guarantee that you are drawing inside screen or buffer boundaries.
• As this function receives a byte-pointer to memory, it can only draw byte-sized and byte-aligned sprites.  This means that the sprite cannot start on non-byte aligned pixels (like odd-pixels, for instance) and their sizes must be a multiple of a byte (2 in mode 0, 4 in mode 1 and 8 in mode 2).

Details

Copies a 4x8-byte sprite from an array with 32 screen pixel format bytes to video memory or a screen buffer.  This function is tagged aligned, meaning that the destination byte must be character aligned.  Being character aligned means that the 8 lines of the sprite will coincide with the 8 lines of a character line in video memory (or in the screen buffer).  For more details about video memory character and pixel lines check table 1 at cpct_drawSprite.

As the 8 lines of the sprite must go to a character line on video memory (or screen buffer), memory destination pointer must point to a the first line (Pixel Line 0) of a character line.  If hardware scrolling has not been used, all pixel lines 0 are contained inside one of these 4 ranges:

All of them have 3 bits in common: bits 5, 4 and 3 are always 0 (xx000xxx).  Any address not having all these 3 bits set to 0 does not refer to a Pixel Line 0 and is not considered to be aligned.

This function will just copy bytes, not taking care of colours or transparencies.  If you wanted to copy a sprite without erasing the background just check for masked sprites and <cpct_drawMaskedSprite>.

Destroyed Register values

AF, BC, DE, HL

Required memory

Time Measures

   Case    | microSecs (us) | CPU Cycles
-----------------------------------------
   Any     |      271       |    1084
-----------------------------------------
Asm saving |      -13       |     -52
-----------------------------------------