cpct_drawSolidBox

Fills up a rectangle in video memory (or screen buffer) with a given colour data byte.  Could be used for drawing coloured rectangles as well as erasing screen rectangles easily.

C Definition

void cpct_drawSolidBox (void* memory, u8 colour_pattern, u8 width, u8 height);

Input Parameters (5 bytes)

Assembly call (Input parameters on registers)

call cpct_drawSolidBox_asm

Parameter Restrictions

• 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.
• colour_pattern could be any 8-bit value, and should be in screen pixel format.  Functions cpct_px2byteM0 and cpct_px2byteM1 could be used to calculate screen pixel formatted bytes out of firmware colours for each pixel in the byte.  If you wanted to know more about screen pixel formats, check cpct_px2byteM0 or cpct_px2byteM1.  Screen pixel format for Mode 2 is just a linear 1-pixel = 1-bit.
• width must be the width of the box in bytes, and must be in the range [1-64].  A box width outside the range [1-64] will probably make the program hang or crash, due to the optimization technique used.  Always remember that the width must be expressed in bytes and not in pixels.  The correspondence is:

• height must be the height of the box in bytes, and must be greater than 0.  There is no practical upper limit to this value.  Height of a box 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 boxes 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 boxes.  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).
• This function will not work from ROM, as it uses self-modifying code.

Details

This function draws a solid colour-patterned box (a rectangle full of a given colour pattern) anywhere at the video memory or screen buffer.  It does so by copying the colour pattern byte to the top-left byte of the box and then cloning that byte to the next bytes of the box.  As it does so using an unrolled LDIR and a dynamic JR, it is limited to 64 LDIs (64 bytes-wide at most).

Destroyed Register values

AF, BC, DE, HL

Required memory

Time Measures

 Case      |      microSecs (us)      |      CPU Cycles
---------------------------------------------------------------------
 Best      |  35 + (29 + 5W)H  + 11HH | 140 + (116 + 20W)H  + 44HH
 Worst     |        Best + 11         |      Best + 44
---------------------------------------------------------------------
 W=2,H=16  |         670 /  681       |     2680 / 2724
 W=4,H=32  |        1636 / 1647       |     6544 / 6588
---------------------------------------------------------------------
Asm saving |         -23              |        -92
---------------------------------------------------------------------

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