Display

Overview

The Display is the standard NCS/e character display peripheral.

It provides a 32 × 12 character display with configurable colours, text styles, cursor behavior, scrolling, palette control, and global rendering adjustments.

Programs interact with the Display using D.* verbs.

The Display is stateful. It maintains its contents, cursor, active text attributes, palette, layout settings, and rendering settings between calls.

Programs using these verbs require a compatible Display peripheral to be connected.

Display geometry

The standard Display contains 32 × 12 character positions, arranged as 16 × 12 display tiles.

Each tile contains two horizontally adjacent characters.

Coordinates begin at the upper-left corner. The default cursor position is (0,0).

Character-oriented operations such as text output and cropping operate on individual character positions.

Tile-oriented operations such as painting and horizontal scrolling operate on pairs of characters.

Display state

The Display maintains state between calls, including:

  • Display contents.
  • Cursor position and mode.
  • Active colour, inversion, and text style.
  • The 16-entry colour palette.
  • Tab width and logical line width.
  • Global rendering settings.

Changing a setting affects subsequent operations until it is changed again.

Default state

The standard Display initializes with the following state:

Setting Default
Cursor position (0,0)
Active colour 15 (#D.COL.WHITE)
Inverted 0 (#D.TXT.NORMAL)
Text style 0 (Normal)
Tab width 4
Logical line width 32
Glow 3
Emissive 1
Brightness 100
Gamma 100
Contrast 100
Sharpness 92

Refresh behavior

Most Display operations modify the internal display state without immediately refreshing the physical display.

D.CHR is the exception. It immediately refreshes the tiles affected by the text it writes.

The complete display may be explicitly refreshed using:

  • D.BLT to refresh synchronously.
  • D.BLTN to refresh asynchronously.

This allows several changes to be prepared before presenting them together:

D.CUR 0 0
D.COL #D.COL.WHITE
D.TXT "HELLO"
D.CUR 0 1
D.TXT "WORLD"
D.BLT

Optional operands

Some Display verbs accept optional trailing operands.

Optional operands may only be omitted from the end of the argument list. To set a later optional operand, all preceding operands must also be supplied.

For example:

D.TAB 4

changes only the tab width, while:

D.TAB 4 24

changes both the tab width and logical line width.

Omitted trailing operands retain their current values.

Text output

D.TXT — Write Text

D.TXT <text>

Writes text beginning at the current cursor position using the active colour and text attributes.

Operands

Position Name Type Description
1 text String value Text to write.

Modified registers

This operation does not modify any registers.

Examples

D.TXT "Hello, world!"

Notes

  • The cursor advances one character position for each printable character.
  • C0 and C1 control characters are interpreted.
  • Inline Display attribute codes are interpreted.
  • Modified tiles are not immediately refreshed.

D.CHR — Write and Refresh

D.CHR <text>

Writes text beginning at the current cursor position and immediately refreshes the affected display tiles.

Operands

Position Name Type Description
1 text String value Text to write.

Modified registers

This operation does not modify any registers.

Examples

D.CHR "A"

Notes

  • Text is processed identically to D.TXT.
  • The cursor advances one character position for each printable character.
  • C0 and C1 control characters are interpreted.
  • Inline Display attribute codes are interpreted.
  • Affected tiles are immediately refreshed.

D.FIL — Fill Display

D.FIL <text>

Fills the entire display with a repeating pattern of text using the active colour and text attributes.

Operands

Position Name Type Description
1 text String value Pattern to repeat across the display.

Modified registers

This operation does not modify any registers.

Examples

-- Fill the display with periods.
D.FIL "."

-- Fill with a repeating pattern.
D.FIL "01"

Notes

  • The supplied pattern repeats until the complete display has been filled.
  • D.FIL does not modify the cursor.
  • C0 and C1 control characters are not interpreted.
  • Inline Display attribute codes are not interpreted.

D.PNT — Paint Tiles

D.PNT <num>

Paints display tiles using the active colour and text style without changing their character data.

Each tile contains two characters. num specifies the number of tiles to paint.

Operands

Position Name Type Description
1 num Integer value Number of tiles to paint.

Modified registers

This operation does not modify any registers.

Examples

-- Paint 3 tiles, affecting 6 characters.
D.PNT 3

Notes

  • Existing characters are not changed.
  • The colour and style of the affected characters are changed.
  • Each painted tile contains two characters.
  • D.PNT advances the cursor.

Colour and text style

D.COL — Active Colour

D.COL <colour> [invert] [style]

Sets the active palette colour and optional text attributes used by subsequent Display operations.

Operands

Position Name Type Range Description
1 colour Integer value 0–15 Active palette index.
2 invert Integer value 0–1 Whether text is inverted.
3 style Integer value 0–7 Text style.

Modified registers

This operation does not modify any registers.

Text styles

Value Style
0 Normal
1 Underlined
2 Overlined
3 Strike
4 Double underline
5 Double overline
6 Double strike
7 Underline + overline

Examples

-- Select white.
D.COL #D.COL.WHITE

-- Select inverted red.
D.COL #COL_RED 1

-- Select underlined white.
D.COL #D.COL.WHITE 0 1

Standard colour constants

The standard palette entries may be referenced using the following constants:

Integer Hex Style Code Constant Default colour
0 0 \s00 #D.COL.BLACK
1 1 \s01 #D.COL.RED, #D.COL.DEEPRED
2 2 \s02 #D.COL.BLUE
3 3 \s03 #D.COL.PURPLE
4 4 \s04 #D.COL.GREEN, #D.COL.DARKGREEN
5 5 \s05 #D.COL.GRAY, #D.COL.GREY, #D.COL.DARKGRAY, #D.COL.DARKGREY
6 6 \s06 #D.COL.MEDBLUE
7 7 \s07 #D.COL.LIGHTBLUE
8 8 \s08 #D.COL.BROWN
9 9 \s09 #D.COL.ORANGE
10 A \s0A #D.COL.LIGHTGRAY, #D.COL.LIGHTGREY
11 B \s0B #D.COL.PINK
12 C \s0C #D.COL.LIGHTGREEN
13 D \s0D #D.COL.YELLOW
14 E \s0E #D.COL.AQUA
15 F \s0F #D.COL.WHITE

These constants identify palette entries rather than fixed RGB values.

Changing a palette entry with D.PAL changes the colour represented by the corresponding constant.

Inline text styles

D.TXT and D.CHR recognize the private-use range U+F100 through U+F1FF as inline Display attribute codes.

The low byte encodes inversion, text style, and palette colour:

Bit:   7 6 5   4   3 2 1 0
       S S S   I   C C C C
Bits Field Values
7–5 Style 0–7
4 Invert 0 normal, 1 inverted
3–0 Colour Palette index 0–15

NCL provides the \sXX string escape as a convenient way to insert these codes:

D.TXT "\s12Inverted Red\s0FNormal White"

Here, \s12 selects inverted, normal text using palette colour 2, while \s0F selects normal text using palette colour 15.

Inline attribute codes are interpreted by D.TXT and D.CHR. They are not interpreted by D.FIL.

See Syntax for NCL string escape syntax.

Control characters

D.TXT and D.CHR recognize several control characters embedded in text.

Common controls and their convenient NCL escape sequences are listed below.

Codepoint Name Escape Effect
0x07 BEL \a Sounds a beep.
0x08 BS \b Moves the cursor back one character.
0x09 HT \t Moves the cursor to the next tab stop.
0x0A LF \n Moves the cursor down one row.
0x0B VT \v Moves the cursor down to the next tab stop.
0x0C FF \f Moves the cursor to (0,0).
0x0D CR \r Moves the cursor to the start of the current line.
0x7F DEL \d Clears the glyph at the cursor position.
0x8B PLD \cd Moves the cursor down one row if not at column 0.
0x8C PLU \cu Moves the cursor up one row if not at column 0.
0x8D RI \i Moves the cursor up one row.

For example:

D.TXT "Hello!\a\nNext line"

Control characters are interpreted by D.TXT and D.CHR. They are not interpreted by D.FIL.

See Syntax for NCL string escape syntax.

Cursor

The cursor identifies the current character position used by text and painting operations.

The default cursor position is (0,0).

The cursor may exist outside the visible 32 × 12 display area. If a printable character is written while the cursor is vertically outside the visible area, the Display scrolls vertically until the cursor is brought into view.

D.CUR — Cursor

D.CUR [x] [y] [mode]

Changes the cursor position and optionally its display mode.

Operands

Position Name Type Description
1 x Integer value Horizontal cursor position.
2 y Integer value Vertical cursor position.
3 mode Integer value Cursor display mode.

Modified registers

This operation does not modify any registers.

Cursor modes

Constant Value Description
#CUR_OFF 0 Cursor is invisible.
#CUR_ON 1 Cursor is solid.
#CUR_BLINK 2 Cursor blinks.

Examples

-- Move the cursor.
D.CUR 10 4

-- Move the cursor and make it blink.
D.CUR 10 4 #CUR_BLINK

D.CURM — Cursor Mode

D.CURM <mode>

Changes the cursor display mode without changing its position.

Operands

Position Name Type Range Description
1 mode Integer value 0–2 Cursor mode.

Modified registers

This operation does not modify any registers.

Examples

D.CURM #CUR_OFF

D.CURM #CUR_BLINK

D.CURGET — Get Cursor Position

D.CURGET <x> <y>

Reads the current cursor position into two integer registers.

Operands

Position Name Type Description
1 x Integer register Destination for the X coordinate.
2 y Integer register Destination for the Y coordinate.

Modified registers

Register Description
x Current cursor X coordinate.
y Current cursor Y coordinate.

Examples

D.CURGET r0 r1
-- > r0 contains cursor X
-- > r1 contains cursor Y

Text layout

D.TAB — Tab and Logical Width

D.TAB [tabWidth] [lineWidth]

Configures the tab interval and logical line width used by cursor and layout operations.

Operands

Position Name Type Description
1 tabWidth Integer value Tab-stop interval.
2 lineWidth Integer value Logical line width.

Modified registers

This operation does not modify any registers.

Defaults

Setting Default
Tab width 4
Logical line width 32

Examples

-- Use tab stops every 4 characters.
D.TAB 4

-- Use 4-character tabs and a logical width of 24.
D.TAB 4 24

Notes

  • lineWidth changes how the Display calculates logical rows and line positions.
  • It does not change the physical width of the display.
  • Sequential text does not automatically return at the logical line width.
  • Sequential text wraps when it reaches the physical edge of the display.

A logical width smaller than 32 allows multiple logical lines to occupy a physical display row.

A logical width larger than 32 allows one logical line to span multiple physical rows.

Scrolling and cropping

Scrolling operates on display tiles, while cropping operates on character columns and rows.

Newly exposed or blanked cells contain blank characters using the current colour and text style.

D.SCR — Scroll Display

D.SCR [x] [y]

Scrolls the contents of the display horizontally and vertically.

Positive values scroll left or up. Negative values scroll right or down.

Operands

Position Name Type Description
1 x Integer value Horizontal scroll amount in tiles.
2 y Integer value Vertical scroll amount in rows.

Modified registers

This operation does not modify any registers.

Examples

-- Scroll one tile left.
D.SCR 1

-- Scroll two tiles right and one row up.
D.SCR -2 1

Notes

  • Horizontal scrolling is measured in tiles.
  • One horizontal tile contains two characters.
  • Vertical scrolling is measured in rows.
  • Character, colour, and style data scroll together.
  • Newly exposed cells are blank using the current colour and style.

D.CRP — Crop Display

D.CRP [n] [e] [s] [w]

Blanks characters or rows along the edges of the display.

The operands specify the amount to blank from the north, east, south, and west edges respectively.

Operands

Position Name Type Description
1 n Integer value Rows to blank from the top.
2 e Integer value Character columns to blank from the right.
3 s Integer value Rows to blank from the bottom.
4 w Integer value Character columns to blank from the left.

Modified registers

This operation does not modify any registers.

Examples

-- Blank the first row.
D.CRP 1

-- Blank one row or character column along every edge.
D.CRP 1 1 1 1

Notes

  • North and south are measured in rows.
  • East and west are measured in characters.
  • Blanked cells use the current colour and style.

Blitting

D.BLT — Blit Display

D.BLT

Immediately refreshes the complete display from its current state.

Execution waits for the refresh to complete before continuing.

Operands

This operation takes no operands.

Modified registers

This operation does not modify any registers.

Examples

D.TXT "Loading..."
D.BLT

Notes

  • D.BLT is synchronous.
  • The next instruction does not execute until the refresh has completed.

D.BLTN — Blit Display Asynchronously

D.BLTN

Immediately begins refreshing the complete display without waiting for the operation to complete.

Operands

This operation takes no operands.

Modified registers

This operation does not modify any registers.

Examples

D.TXT "Loading..."
D.BLTN

-- Execution continues without waiting.

Notes

  • D.BLTN is asynchronous.
  • Program execution may continue while the display is being refreshed.
  • Display operations issued while an asynchronous refresh is in progress wait for that refresh to complete before taking effect.

Palette

The Display uses a 16-entry colour palette.

Each palette entry contains red, green, and blue components ranging from 0 through 255.

D.PAL — Set Palette Colour

D.PAL <index> [r] [g] [b]

Changes a colour in the Display palette.

Operands

Position Name Type Range Description
1 index Integer value 0–15 Palette index to modify.
2 r Integer value 0–255 Red component.
3 g Integer value 0–255 Green component.
4 b Integer value 0–255 Blue component.

Modified registers

This operation does not modify any registers.

Examples

-- Set palette entry 1 to bright red.
D.PAL 1 255 0 0

Notes

  • RGB values outside 0–255 are clamped.
  • Omitted trailing components retain their current values.
  • Changing a palette entry changes the colour represented by that palette index.

D.PALGET — Get Palette Colour

D.PALGET <index> <r> <g> <b>

Reads a palette colour into three integer registers.

Operands

Position Name Type Description
1 index Integer value Palette index to read.
2 r Integer register Destination for red component.
3 g Integer register Destination for green component.
4 b Integer register Destination for blue component.

Modified registers

Register Description
r Red component, 0–255.
g Green component, 0–255.
b Blue component, 0–255.

Examples

D.PALGET 1 r0 r1 r2
-- > r0 contains red
-- > r1 contains green
-- > r2 contains blue

D.PALRST — Reset Palette

D.PALRST

Restores all palette entries to their default colours.

Operands

This operation takes no operands.

Modified registers

This operation does not modify any registers.

Display settings

D.DIS — Display Settings

D.DIS [glow] [emissive] [brightness] [gamma] [contrast] [sharpness]

Changes global Display rendering settings.

Operands

Position Name Type Range Description
1 glow Integer value 0–100 Display glow intensity.
2 emissive Integer value 0–1 Enables or disables emissive rendering.
3 brightness Integer value 0–500 Brightness adjustment. 100 is neutral.
4 gamma Integer value 1–500 Gamma adjustment. 100 is neutral.
5 contrast Integer value 0–500 Contrast adjustment. 100 is neutral.
6 sharpness Integer value 0–255 Display sharpness.

Modified registers

This operation does not modify any registers.

Default settings

Setting Default
Glow 3
Emissive 1
Brightness 100
Gamma 100
Contrast 100
Sharpness 92

Examples

-- Increase glow without changing other settings.
D.DIS 10

-- Disable emissive rendering.
D.DIS 3 0

-- Darken the display.
D.DIS 3 1 75

-- Increase contrast.
D.DIS 3 1 100 100 150

-- Restore the standard settings.
D.DIS 3 1 100 100 100 92

Notes

  • Values outside their documented ranges are clamped.
  • 100 is neutral for brightness, gamma, and contrast.
  • Omitted trailing settings retain their current values.
  • To change a later setting, all preceding settings must also be supplied.
  • Extreme combinations of rendering settings may produce heavily distorted or unusual display output.