Intuition Screens — Screen Fundamentals

This article synthesises Section 3.2 ("Screen Fundamentals") of Amiga C for Advanced Programmers by Bleek, Jennrich, Schulz (Abacus / Data Becker, ~1991). It covers the Intuition screen model: what a screen is, how to open one, the NewScreen structure, and how to bring screens to front, send to back, and manage the public-screen list.

A screen is the conceptual layer above a RastPort and a ViewPort: it's the unit that owns a display mode, a colour palette, a default font, and (usually) a window stack. Windows must be opened on a screen.

Editorial note: page numbers in this article refer to the PDF page index in the raw OCR source. The section is in two parts: 3.2 (theory) and 3.2.1 onwards (NewScreen structure, example code).

What a screen is (page 133)

A screen in Intuition is a logical display surface that:

  • Owns the display mode (resolution, interlace, double-buffering, monitor)
  • Owns the colour palette (32 colours for OCS/ECS, 256 for AGA)
  • Owns a default font (used for the title bar and menus)
  • Hosts windows that are opened on it
  • Is identified by a public name (e.g. "Workbench") so other programs can find and share it

The book calls out a useful mental model:

"Word processing's main use for screen output is text display. ... Games need full-screen colour animation. Both can be accomodated by Intuition, but a screen for each has different parameters."

The NewScreen structure (page 134)

NewScreen is the declarative descriptor you fill in before calling OpenScreen(). The book's version of the structure (slightly antique):

struct NewScreen {
    SHORT LeftEdge;
    SHORT TopEdge;
    SHORT Width;
    SHORT Height;
    SHORT Depth;             /* number of bitplanes (1-8) */
    UBYTE DetailPen;         /* text colour (0-7) */
    UBYTE BlockPen;          /* block colour (0-7) */
    USHORT ViewModes;        /* resolution flags */
    USHORT Type;             /* CUSTOMSCREEN / WBENCHSCREEN / PUBLICSCREEN */
    struct TextAttr *Font;
    UBYTE *DefaultTitle;
    struct Gadget *Gadgets;  /* optional custom gadgets in title */
    struct BitMap *CustomBitMap;
};

Most fields are direct analogues of NewWindow.NewWindow. The new ones specific to screens:

  • Type — picks the screen class. WBENCHSCREEN makes it a Workbench replacement; PUBLICSCREEN registers it in the public-screen list; CUSTOMSCREEN is a private screen (default).
  • ViewModes — bit flags for the resolution:
  • HIRES (640×200)
  • LORES (320×200, default)
  • INTERLACE (doubles vertical resolution)
  • SUPERHIRES (A2024 monitor, 1008×800)
  • DBLHPAL, DBLNPAL etc. for PAL/NTSC scan-doubling
  • CustomBitMap — supply your own BitMap instead of letting Intuition allocate one. Used for screen-mode promotion (see graphics/v39-aa-graphics-features.md).

Modern equivalent: the modern NDK uses OpenScreenTagList() with a TagItem array instead of a fixed NewScreen structure. The flags above are the same; just the calling convention has changed. See intuition/intuition-library-reference.md for OpenScreenTags.

Opening and using a screen

After OpenScreen(), you get a struct Screen *. With it you can:

  • Open windows on it via NewWindow → OpenWindow (with NewWindow.Screen = screen)
  • Set its title, default font, colours
  • Bring it to the front: ScreenToFront(screen)
  • Send it behind: ScreenToBack(screen)
  • Close it: CloseScreen(screen)

The book gives a worked example starting at page 144 (which uses both NewScreen and OpenScreen to set up a custom display).

Public screens

A screen can be registered as public via:

struct Screen *s = OpenScreen(&ns);
PubScreenStatus(s, 0);   /* status 0 = available */

Other programs can then ask for the screen by name:

struct Screen *workbench = LockPubScreen("Workbench");
if (workbench) {
    /* open a window on it */
    UnlockPubScreen(NULL, workbench);
}

The book only briefly introduces the public-screen model. The full coverage is in the intuition/intuition-library-reference.md autodoc pages for LockPubScreen, UnlockPubScreen, PubScreenStatus, SetPubScreenModes.

ViewModes flags (page 135)

The ViewModes field is the most important screen parameter. The book covers:

Flag Effect
LORES 320 × 200 (default, OS 1.0+)
HIRES 640 × 200
SUPERHIRES 1008 × 800 (A2024 monitor only)
INTERLACE Doubles vertical resolution (often combined with HIRES for 640×400 non-interlaced display)
DBLHPAL / DBLNPAL Scan-doubled PAL / NTSC for low-resolution on progressive monitors
SCREENQUIET (V39) Don't allow any windows to open on this screen (private display)

For OS 3.x and later, AA (Advanced Architecture) screens add AGA-specific flags: - MODE_HIPF (Hi-Plane Flip) - EXTRAHALFBRITE (EHB modes)

For a complete flag list, see the OS 3.2 autodoc for OpenScreen in library-reference/intuition-library.md.

The NewScreen example (page 134)

The book walks through each field of NewScreen with commentary:

  • LeftEdge / TopEdge — the screen's position on the workbench area. Often 0, 0 unless stacking.
  • Width / Height — in pixels; depends on resolution. Standard sizes: 320×256 (LORES), 640×256 (HIRES), 640×512 (HIRES + INTERLACE).
  • Depth — number of bitplanes (1-8 for AGA). 1 = monochrome, 3 = 8 colours, 4 = 16 colours, 5 = 32 colours.
  • DetailPen / BlockPen — pen numbers for text and block backgrounds. The book explicitly warns: "seven is the highest value for DetailPen or BlockPen" — beyond 7, you're into the "highlight" pens (0-7) vs "shadow" pens (8-15) and the relationship changes.
  • ViewModes — resolution flags (see above).
  • Type — WBENCHSCREEN, PUBLICSCREEN, or 0 (CUSTOMSCREEN).
  • Font — pointer to a TextAttr structure (name, height, style). The book's examples use "topaz.font" (8-point) or "courier.font" (programmer's font).
  • DefaultTitle — pointer to a string, used as the screen title bar.
  • Gadgets — rare; allows custom gadgets in the title bar.
  • CustomBitMap — provide your own bitmap for advanced use (mode promotion, dual-playfield tricks).

Screens vs. windows (book's framing)

The book frames screens as the environment and windows as the application's interface:

"Each window parameter depends on the screen to some extent. Window colour, resolution and position can be affected by the screen."

This is why NewWindow requires you to specify which screen it opens on — and why screen failures (e.g. monitor can't display the requested mode) cascade into window failures.

For practical screen-handling patterns, the book provides a code listing (page 144 onwards in the printed book) that:

  1. Defines a NewScreen
  2. Calls OpenScreen
  3. Defines a NewWindow referencing that screen
  4. Calls OpenWindow
  5. Runs the event loop
  6. Closes the window
  7. Closes the screen

This pattern is identical to the modern OpenScreenTagList + OpenWindowTagList flow; the modern API adds tag-based configuration but the sequence is unchanged.

What's NOT in this section

Sources

The chapter's framing of "screens as environment" is consistent with the modern intuition.library design; the modern API renames and tagifies fields but the model is unchanged.