cpct_drawSpriteMasked

Copies a masked sprite from an array to video memory (or to a screen buffer), using mask as transparency information, to prevent erasing the background.

C Definition

void cpct_drawSpriteMasked (void* sprite, void* memory, u8 width, u8 height) __z88dk_callee;

Input Parameters (6 bytes)

Assembly call (Input parameters on registers)

call cpct_drawSpriteMasked_asm

Parameter Restrictions

• sprite must be an array containing sprite’s pixels data in screen pixel format along with mask data.  Each mask byte will contain enabled bits as those that should be picked from the background (transparent) and disabled bits for those that will be printed from sprite colour data.  Each mask data byte must precede its associated colour data byte.  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 2 x width x height (mask data doubles array size).  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 could be any place in memory, inside or outside current video memory.  It will be equally treated as video memory (taking into account CPC’s video memory disposition).  This lets you copy sprites to software or hardware backbuffers, and not only video memory.
• width must be the width of the sprite in bytes, excluding mask data, and must be 1 or more.  Using 0 as width parameter for this function could potentially make the program hang or crash.  Always remember that the width must be expressed in bytes and not in pixels.  The correspondence is:

• height must be the height of the sprite in bytes, and must be greater than 0.  There is no practical upper limit to this value.  Height of a sprite in bytes and pixels is the same value, as bytes only group consecutive pixels in the horizontal space.

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 box 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

This function copies a generic WxH bytes sprite from memory to a video-memory location (either present video-memory or software / hardware backbuffer).  The original sprite must be stored as an array (i.e. with all of its pixels stored as consecutive bytes in memory).  It works in a similar way to cpct_drawSprite, but taking care about transparency information encoded in mask bytes.  For detailed information about how sprite copying works, and how video memory is formatted, take a look at cpct_drawSprite.

For this routine to work, the sprite must contain mask information: inside the sprite array, for each byte containing screen colour information, there must be a preceding byte with mask information.  So, the format is as depicted in example 1:

Array storage format:  <-byte 1-> <-byte 2-> <-byte 3-> <-byte 4->
                       <- mask -> <-colour-> <- mask -> <-colour->
------------------------------------------------------------------------------
       u8* sprite =  {    0xFF,     0x00,       0x00,     0xC2,   .... };
------------------------------------------------------------------------------
Video memory output:   <- 1st Screen byte -> <- 2nd Screen byte ->
______________________________________________________________________________
        Example 1: Definition of a masked sprite and byte format

In example 1, each “Screen byte” will become 1 byte outputted to video memory resulting of the combination of 3 bytes: 1-byte mask, 1-byte sprite colour data and 1-byte previous screen colour data.  The combination of these 3 bytes results in sprite colour data being “blended” with previous screen colour data, adding sprite pixels with background pixels (the ones over transparent pixels).

The way this function works is by getting sprite bytes two by two, operating with them, and copying them to video memory (or backbuffer).  Each two bytes got (mask + sprite colour information) are mixed with an AND opreation to remove (set to 0) sprite background pixels.  After that, an OR operation between the resulting byte and the background (the present byte at video memory location where we want to write) is performed.  That effectively mixes sprite colours with background colours, after removing background pixels from the sprite.

Destroyed Register values

AF, BC, DE, HL

Required memory

Time Measures

 Case      |    microSecs (us)        |    CPU Cycles
----------------------------------------------------------------
 Best      |  21 + (22 + 18W)H + 10HH | 84 + (88 + 72W)H + 40HH
 Worst     |       Best + 10          |     Best + 40
----------------------------------------------------------------
 W=2,H=16  |        957 /  967        |    3828 /  3868
 W=4,H=32  |       3057 / 3067        |   12228 / 12268
----------------------------------------------------------------
Asm saving |          -16             |       -64
----------------------------------------------------------------

W = width in bytes, H = height in bytes, HH = [(H-1)/8]