Modules/print

print

Code: print.h

Category: Core

Dependencies:

• VDP

Samples:

• s_print
• s_text

✍

The print module used to display text in any screen mode. It offers functions for displaying different types of data in different formats, including advanced effects such as shading or outlining (for bitmap modes).

Usage

To use this module, include "print.h" in your source code, and add "print" to the modules list (LibModules) in your project's configuration file (project_config.js).

✍

Use of this module begins with the initialization of a font. Then you can use all the functions to draw text on screen.

Modes

You have several font render modes.

Text

Draw characters as pattern names (text mode).

Requirement:

• Compatible with tiled-based screen modes: Screen 0 (40/80 columns), 1, 2 and 4.
• You need to activate PRINT_USE_TEXT compile option in your library configuration (msxgl_config.h).

Example using tile-based render mode:

#include "font/font_mgl_sample8.h"

VDP_SetMode(VDP_MODE_SCREEN1);            // Initialize screen mode 1 (tiled-base mode)
Print_SetTextFont(g_Font_MGL_Sample8, 1); // Upload font tile-set from index 1
Print_SetPosition(10, 10);                // Position in tile grid unit
Print_DrawText("Text mode");

Bitmap

Draw characters from RAM (real-time unpack font data and draw it).

Requirement:

• Compatible with bitmap-based screen modes: Screen 5 to 8.
• You need to activate PRINT_USE_BITMAP or PRINT_USE_VRAM compile option in your library configuration (msxgl_config.h).

Example using bitmap render mode for MSX2:

#include "font/font_mgl_sample6.h"

VDP_SetMode(VDP_MODE_SCREEN5);            // Initialize screen mode 5 (bitmap mode)
Print_SetBitmapFont(g_Font_MGL_Sample6);  // Initialize bitmap font
Print_SetOutline(TRUE, COLOR_GRAY);       // Set outline effect
Print_SetPosition(100, 100);              // Position in pixel unit
Print_DrawText("Bitmap mode");

Bitmap with transparency

Draw characters from RAM with transparency (real-time unpack font data and draw it).

Same mode than Bitmap but a little bit slower.

Can be activated using:

#include "font/font_mgl_sample6.h"

VDP_SetMode(VDP_MODE_SCREEN5);            // Initialize screen mode 5 (bitmap mode)
Print_SetBitmapFont(g_Font_MGL_Sample6);  // Initialize bitmap font
Print_SetMode(PRINT_MODE_BITMAP_TRANS);   // Activate transparency
Print_SetPosition(100, 100);              // Position in pixel unit
Print_DrawText("Bitmap mode with transparency");

VRAM

Draw characters from VRAM (font data is upack once in VRAM thne drawing is done by VRAM copy). slower to initialize, far quicker to draw.

Requirement:

• Compatible with bitmap-based screen modes: Screen 5 to 8.
• You need to activate PRINT_USE_VRAM compile option in your library configuration (msxgl_config.h).

Example using bitmap render mode for MSX2:

#include "font/font_mgl_sample6.h"

Print_SetVRAMFont(g_Font_MGL_Sample6, 212, COLOR_WHITE);
Print_SetPosition(100, 150);              // Position in pixel unit
Print_DrawText("VRAM mode");

Sprites

Draw characters from sprites (load font data as sprite pattern in VRAM then display characters using sprite system).

Requirement:

• Compatible with all sprite enabled screen modes:
  • Screen 1 to 3 (4 sprites per line),
  • Screen 4 to 8 (8 sprites per line),
• You need to activate PRINT_USE_SPRITE compile option in your library configuration (msxgl_config.h).

Example using sprite render mode:

#include "font/font_mgl_sample8.h"

VDP_SetMode(VDP_MODE_SCREEN1);            // Initialize screen mode 1 (tiled-base mode)
Print_SetSpriteFont(g_Font_MGL_Sample8, 0, 0);
Print_SetPosition(100, 50);               // Position in pixel unit
Print_DrawText("SPRT");

Font modes compatibility matrix

Font mode	Screen modes
	0	1	2	3	4	5	6	7	8	10	12
Text	✔️	✔️	✔️	❌	✔️	❌	❌	❌	❌	❌	❌
Bitmap	❌	❌	❌	❌	❌	✔️	✔️	✔️	✔️	❔	❔
VRAM	❌	❌	❌	❌	❌	✔️	✔️	✔️	✔️	❔	❔
Sprites	❌	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Samples

See module use cases in the sample programs:

• s_print (bitmap based example)
• s_text (tiled based example)

Settings

✍

Library configuration (msxgl_config.h):

// Print module setting
#define PRINT_USE_TEXT				TRUE	// Allow use of Text font (T1-T2, G1-G3)
#define PRINT_USE_BITMAP			FALSE	// Allow use of Bitmap font (G4-G7)
#define PRINT_USE_VRAM				FALSE	// Allow use of VRAM stored font (G4-G7)
#define PRINT_USE_SPRITE			FALSE	// Allow use of Sprite font (G3-G7)
#define PRINT_USE_FX_SHADOW			FALSE	// [Bitmap] Allow use of text shadow
#define PRINT_USE_FX_OUTLINE		FALSE	// [Bitmap] Allow use of text outline
#define PRINT_USE_2_PASS_FX			FALSE	// [Bitmap] Allow use 2-pass FX render to prevent character overlap
#define PRINT_USE_GRAPH				TRUE	// Allow use of character lines and boxes
#define PRINT_USE_VALIDATOR			TRUE	// Add validator character code
#define PRINT_USE_UNIT				FALSE	// Display integer type (h: hexadecimal, b: binary)
#define PRINT_USE_FORMAT			TRUE	// Add printf type function
#define PRINT_USE_32B				TRUE	// Allow to print 32-bits integers
#define PRINT_SKIP_SPACE			FALSE	// Skill space character
#define PRINT_COLOR_NUM				12		// 1 color per line
// Character width
// - PRINT_WIDTH_1 (text mode)
// - PRINT_WIDTH_6 (fixed to 6 pixels)
// - PRINT_WIDTH_8 (fixed to 8 pixels)
// - PRINT_WIDTH_X (variable)
#define PRINT_WIDTH					PRINT_WIDTH_1
// Character height
// - PRINT_HEIGHT_1 (text mode)
// - PRINT_HEIGHT_8 (fixed to 8 pixels)
// - PRINT_HEIGHT_X (variable)
#define PRINT_HEIGHT				PRINT_HEIGHT_1

Dependencies

Dependency on other modules:

• VDP