cpct_drawTileAligned2x4_f

Copies a 2x4-byte sprite to video memory (or screen buffer), assuming that location to be copied is in Pixel Lines 0-3 of a character line.

C Definition

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

Input Parameters (4 bytes)

Assembly call (Input parameters on registers)

call cpct_drawTileAligned2x4_f_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 8.  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 between Pixel Line 0 and Pixel Line 3 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-3] 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 2x4-byte sprite from an array with 8 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 4 lines of the sprite need to be withing the 8 lines of a character line in video memory (or in any screen buffer).  For more details about video memory character and pixel lines check table 1 at cpct_drawSprite.

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

All of them have 1 bit in common: bit 5 is always 0 (xx0xxxxx).  Any address not having this bit set to 0 will refer to Pixel Lines 4-7 in any given Character Line, and are 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     |       72       |   288
-----------------------------------------
Asm saving |      -13       |   -52
-----------------------------------------