cpct_drawStringM1

Prints a null-terminated string with ROM characters on a given byte-aligned position on the screen in Mode 1 (320x200 px, 4 colours).

C Definition

void cpct_drawStringM1 (void* string, void* video_memory, u8 fg_pen, u8 bg_pen)

Input Parameters (5 Bytes)

(2B HL) stringPointer to the null terminated string being drawn
(2B DE) video_memoryVideo memory location where the string will be drawn
(1B C ) fg_penForeground colour (PEN, 0-3)
(1B B ) bg_penBackground colour (PEN, 0-3)

Assembly call (Input parameters on registers)

call cpct_drawStringM1_asm

Parameter Restrictions

  • string must be a null terminated string.  It could contain any 8-bit value as characters except 0, which will signal the end of the string.  Be careful to provide strings with a 0 (null) at the end of the string.  Otherwise, unexpected results may happen (Typically, rubbish characters printed on screen and, occasionally, memory overwrite and even hangs or crashes).
  • video_memory could theoretically be any 16-bit memory location.  It will work outside current screen memory boundaries, which is useful if you use any kind of double buffer.  However, be careful where you use it, as it does no kind of check or clipping, and it could overwrite data if you select a wrong place to draw.
  • fg_pen must be in the range [0-3].  It is used to access a colour mask table and, so, a value greater than 15 will return a random colour mask giving unpredictable results (typically bad character rendering, with odd colour bars).
  • bg_pen must be in the range [0-3], with identical reasons to fg_pen.

Requirements and limitations

  • Do not put this function’s code below 0x4000 in memory.  In order to read characters from ROM, this function enables Lower ROM (which is located 0x0000-0x3FFF), so CPU would read code from ROM instead of RAM in first bank, effectively shadowing this piece of code.  This would lead to undefined results (typically program would hang or crash).
  • This routine does not check for boundaries.  If you draw too long strings or out of the screen, unpredictable results will happen.
  • Screen must be configured in Mode 1 (320x200 px, 4 colours)
  • This function requires the CPC firmware to be DISABLED.  Otherwise, random crashes might happen due to side effects.
  • This function disables interrupts during main loop (character printing), and re-enables them at the end.
  • This function will not work from ROM, as it uses self-modifying code.

Details

This function receives a null-terminated string and draws it to the screen in Mode 1 (320x200, 4 colours).  This function calls cpct_drawCharM1 to draw every character.  video_memory parameter points to the byte where the string will be drawn.  The first pixel of that byte will be the upper-left corner of the string.  As this function uses a byte-pointer to refer to the upper-left corner of the string, it can only draw string on module-4-pixel columns (0, 4, 8, 12...), as every byte contains 4 pixels in Mode 1.

Destroyed Register values

AF, BC, DE, HL

Required memory

169 bytes (34 bytes this function, 135 bytes cpct_drawCharM1)

Time Measures

  Case     |    Cycles    |   microSecs (us)
-------------------------------------------
  Best     | 173 + 4406*L | 43.25 + 1101.50*L
  Worst    | 173 + 5086*L | 43.25 + 1271.50*L
----------------------------------------------
Asm saving |        -84   |          -21.00
----------------------------------------------

L = Length of the string (excluding null-terminator character)

These time measures take into account the time it takes to draw each individual character (call to cpct_drawCharM1, assembly entry point).

Prints a null-terminated string with ROM characters on a given byte-aligned position on the screen in Mode 1 (320x200 px, 4 colours).
unsigned char (u8 = unsigned 8-bits, 1 byte )
Prints a ROM character on a given byte-aligned position on the screen in Mode 1 (320x200 px, 4 colours).
Close