Graphics on TurboVision

Mode 13h in Turbo Pascal: Graphics Programming Without Illusions

Sun, 22 Feb 2026 00:00:00 +0000

Turbo Pascal graphics programming is one of the cleanest ways to learn what a frame actually is. In modern stacks, rendering often passes through layers that hide timing, memory layout, and write costs. In DOS Mode 13h, almost nothing is hidden. You get 320x200, 256 colors, and a linear framebuffer at segment $A000. Every pixel you draw is your responsibility.

Mode 13h became a favorite because it removed complexity that earlier VGA modes imposed. No planar bit operations, no complicated bank switching for this resolution, and no mystery about where bytes go. Pixel (x, y) maps to offset y * 320 + x. That directness made it ideal for demos, games, and educational experiments. It rewarded people who could reason about memory as geometry.

A minimal setup in Turbo Pascal is refreshingly explicit: switch video mode via BIOS interrupt, get access to VGA memory, write bytes, wait for input, restore text mode. There is no rendering engine to configure. You control lifecycle directly. That means you also own failure states. Forget to restore mode and you leave the user in graphics. Corrupt memory and artifacts appear instantly.

Early experiments usually start with single-pixel writes and quickly hit performance limits. Calling a procedure per pixel is expressive but expensive. The first optimization lesson is batching and locality: draw contiguous spans, avoid repeated multiplies, precompute line offsets, and minimize branch-heavy inner loops. Mode 13h teaches a truth that still holds in GPU-heavy times: throughput loves predictable memory access.

Palette control is another powerful concept students often miss today. In 256-color mode, pixel values are indices, not direct RGB triples. By writing DAC registers, you can change global color mappings without touching framebuffer bytes. This enables palette cycling, day-night transitions, and cheap animation effects that look far richer than their computational cost. You are effectively animating interpretation, not data.

The classic water or fire effects in DOS demos relied on exactly this trick. The framebuffer stayed mostly stable while the palette rotated across carefully constructed ramps. What looked dynamic and expensive was often elegant indirection. When people say old graphics programmers were “clever,” this is the kind of system-level cleverness they mean: using hardware semantics to trade bandwidth for perception.

Flicker management introduces the next lesson: page or buffer discipline. If you draw directly to visible memory while the beam is scanning, partial updates can tear. So many projects used software backbuffers in conventional memory, composed full frames there, then copied to $A000 in one pass. With tight loops and occasional retrace synchronization, output became dramatically cleaner. This is conceptually the same as modern double buffering.

Collision and sprite systems further sharpen design. Transparent blits require skipping designated color indices. Masking introduces branch costs. Dirty-rectangle approaches reduce full-screen copies at the price of bookkeeping complexity. Developers learned to choose trade-offs based on scene characteristics instead of blindly applying one pattern. That mindset remains essential in performance engineering: no optimization is universal.

Turbo Pascal itself played a practical role in this loop. You could prototype an effect in high-level Pascal, profile by observation, then move only hotspot routines to inline assembly where needed. That incremental path is important. It discouraged premature optimization while still allowing low-level control when measurable bottlenecks appeared. Good systems work often looks like this staircase: clarity first, precision optimization second.

Debugging graphics bugs in Mode 13h was brutally educational. Off-by-one writes painted diagonal scars. Incorrect stride assumptions created skewed images. Overflow in offset arithmetic wrapped into nonsense that looked artistic until it crashed. You learned to verify bounds, separate coordinate transforms from blitting, and build tiny visual test patterns. A checkerboard routine can reveal more than pages of logging.

One underused exercise for modern learners is implementing the same tiny scene three ways: naive per-pixel draw, scanline-optimized draw, and buffered blit with palette animation. The visual output can be identical while performance differs radically. This makes optimization tangible. You are not guessing from profiler flames alone; you see smoothness and latency with your own eyes.

Mode 13h also teaches humility about hardware assumptions. Not every machine behaves the same under load. Timing differences, cache behavior, and peripheral quirks affect results. The cleanest DOS codebases separated device assumptions from scene logic and made fallbacks possible. That sounds like old wisdom, but it maps directly to current cross-platform rendering work.

There is a reason this environment remains compelling decades later. It compresses core graphics principles into a small, understandable box: memory addressing, color representation, buffering strategy, and frame pacing. You can hold the whole pipeline in your head. Once you can do that, modern APIs feel less magical and more like powerful abstractions built on familiar physics.

Turbo Pascal in Mode 13h is therefore not a relic exercise. It is a precision training ground. It teaches you to respect data movement, to decouple representation from display, to optimize where evidence points, and to treat visual correctness as testable behavior. Those lessons survive every framework trend because they are not about tools. They are about first principles.

Mode X in Turbo Pascal, Part 1: Planar Memory and Pages

Sun, 22 Feb 2026 00:00:00 +0000

Mode 13h is the famous VGA “easy mode”: one byte per pixel, 320x200, 256 colors, linear memory. It is perfect for first experiments and still great for teaching rendering basics. But old DOS games that felt smoother than your own early experiments usually did not stop there. They switched to Mode X style layouts where planar memory, off-screen pages, and explicit register control gave better composition options and cleaner timing.

This first article in the series is about that mental model. Before writing sprite engines, tile systems, or palette tricks, you need to understand what the VGA memory controller is really doing. If the model is wrong, every optimization turns into folklore.

If you have not read Mode 13h Graphics in Turbo Pascal, do that first. It gives the baseline we are now deliberately leaving behind.

Why Mode X felt “faster” in real games

The practical advantage was not raw arithmetic speed. The advantage was control over layout and buffering:

You could keep multiple pages in video memory.
You could build into a hidden page and flip start address.
You could organize writes in ways that matched planar hardware better.
You could avoid tearing without full-frame copies every frame.

What looked like magic in magazines was mostly disciplined memory mapping plus stable frame pacing.

The key shift: from linear bytes to planes

In Mode X style operation, pixel bytes are distributed across four planes. Adjacent pixel columns are not consecutive memory bytes in the way Mode 13h beginners expect. Instead, pixel ownership rotates by plane. That means one memory offset can represent four neighboring pixels depending on which plane is currently enabled for writes.

The control knobs are VGA registers:

Sequencer map mask: choose writable plane(s).
Graphics controller read map select: choose readable plane.
CRTC start address: choose which memory area is currently displayed.

Once you accept that “address + selected plane = pixel target,” most confusing behavior suddenly becomes deterministic.

Entering a workable 320x240-like unchained setup

Many implementations start by setting BIOS mode 13h and then unchaining to get planar behavior while keeping convenient geometry assumptions. Exact register recipes vary by card and emulator, so treat this as a pattern, not sacred scripture.

procedure SetModeX;
begin
  asm
    mov ax, $0013
    int $10
  end;

  { Disable chain-4 and odd/even, enable all planes }
  Port[$3C4] := $04; Port[$3C5] := $06; { Memory Mode }
  Port[$3C4] := $02; Port[$3C5] := $0F; { Map Mask }

  { Graphics controller tweaks for unchained access }
  Port[$3CE] := $05; Port[$3CF] := $40;
  Port[$3CE] := $06; Port[$3CF] := $05;
end;

Do not panic if this looks low-level. Turbo Pascal is excellent at this style of direct hardware work because compile-run cycles are fast and failures are usually immediately observable.

Plotting one pixel with plane selection

A minimal pixel routine makes the model tangible. X chooses plane and byte offset; Y chooses row stride component.

procedure PutPixelX(X, Y: Integer; C: Byte);
var
  Offset: Word;
  PlaneMask: Byte;
begin
  Offset := (Y * 80) + (X shr 2);
  PlaneMask := 1 shl (X and 3);

  Port[$3C4] := $02;
  Port[$3C5] := PlaneMask;
  Mem[$A000:Offset] := C;
end;

The 80 stride comes from 320/4 bytes per row in planar addressing. That single number is where many beginner bugs hide, because linear assumptions die hard.

Pages and start address flipping

A stronger reason to adopt Mode X is page strategy. If your card memory budget allows it, maintain two or more page regions in VRAM. Render into non-visible page, then point CRTC start address at the finished page. That is cheaper and cleaner than copying full frames through CPU-visible loops every tick.

Conceptually:

displayPage is what CRTC shows.
drawPage is where your renderer writes.
End of frame: swap roles and update CRTC start.

The code details differ by implementation, but the discipline is universal: never draw directly into the page currently being scanned out unless you enjoy tear artifacts as design motif.

Practical debugging advice

When output is wrong, do not “optimize harder.” Validate one axis at a time:

Fill one plane with a color and confirm stripe pattern.
Write known values at fixed offsets and read back by plane.
Verify start-address page flip without any sprite code.
Only then add primitives and scene logic.

This sequence saves hours. Most graphics bugs in this phase are addressing bugs, not “algorithm bugs.”

Where we go next

In Part 2, we build practical drawing primitives (lines, rectangles, clipped blits) that respect planar layout instead of fighting it:

Mode X in Turbo Pascal, Part 2: Primitives and Clipping

Related context:

Mode X is not difficult because it is old. It is difficult because it requires a precise mental model. Once that model clicks, the hardware starts to feel less like a trap and more like an instrument.

Mode X in Turbo Pascal, Part 2: Primitives and Clipping

Sun, 22 Feb 2026 00:00:00 +0000

After the planar memory model clicks, the next trap is pretending linear drawing code can be “ported” to Mode X by changing one helper. That works for demos and fails for games. Robust Mode X rendering starts with primitives that are aware of planes, clipping, and page targets from day one.

If you missed the foundation, begin with Part 1: Planar Memory and Pages. This article assumes you already have working pixel output and page flipping.

Primitive design goals

For old DOS rendering pipelines, primitives should optimize for correctness first:

Never write outside page bounds.
Keep clipping deterministic and centralized.
Minimize per-pixel register churn where possible.
Separate addressing math from shape logic.

Performance matters, but undefined writes kill performance faster than any missing micro-optimization.

Clipping is policy, not an afterthought

A common beginner pattern is “draw first, check later.” On VGA memory that quickly becomes silent corruption. Instead, apply clipping at primitive boundaries before entering the hot loops.

For axis-aligned boxes, clipping is straightforward:

function ClipRect(var X1, Y1, X2, Y2: Integer): Boolean;
begin
  if X1 < 0 then X1 := 0;
  if Y1 < 0 then Y1 := 0;
  if X2 > 319 then X2 := 319;
  if Y2 > 199 then Y2 := 199;
  ClipRect := (X1 <= X2) and (Y1 <= Y2);
end;

Once clipped, your inner loop can stay simple and trustworthy. This is less glamorous than fancy blitters and infinitely more important.

Horizontal fills with reduced state changes

Naive pixel-by-pixel fills set map mask every write. Better approach: process spans in groups where plane mask pattern repeats predictably. Even a modest rework reduces I/O pressure.

procedure HLineX(X1, X2, Y: Integer; C: Byte);
var
  X: Integer;
begin
  if (Y < 0) or (Y > 199) then Exit;
  if X1 > X2 then begin X := X1; X1 := X2; X2 := X; end;
  if X1 < 0 then X1 := 0;
  if X2 > 319 then X2 := 319;

  for X := X1 to X2 do
    PutPixelX(X, Y, C);
end;

This still calls PutPixelX, but with clipping discipline built in. Later you can specialize spans and batch by plane.

Rectangle fills and UI panels

Old DOS interfaces often combine world rendering plus overlays. A clipped rectangle fill is the workhorse for panels, bars, and damage flashes.

procedure FillRectX(X1, Y1, X2, Y2: Integer; C: Byte);
var
  Y: Integer;
begin
  if not ClipRect(X1, Y1, X2, Y2) then Exit;
  for Y := Y1 to Y2 do
    HLineX(X1, X2, Y, C);
end;

It looks boring because good infrastructure often does. Boring primitives are stable primitives.

Line drawing without hidden chaos

For general lines, Bresenham remains practical. The Mode X-specific advice is to keep the stepping algorithm independent from memory layout and delegate write target handling to one consistent pixel primitive.

Why this matters: when bugs appear, you can isolate whether the issue is geometric stepping or planar addressing. Mixed concerns create mixed failures and bad debugging sessions.

Instrument your renderer early

Before moving to sprites, add a diagnostic frame:

draw clipped and unclipped test rectangles at edges
draw diagonal lines through all corners
render page index and frame counter
flash a corner pixel each frame

If this test scene is unstable, your game scene will be chaos with better art.

Structured pass order

A practical frame pipeline in Mode X might be:

clear draw page
draw background spans
draw world primitives
draw sprite layer placeholders
draw HUD rectangles/text
flip display page

This ordering gives deterministic overdraw and clear extension points for Part 3.

Cross-reference with existing DOS workflow

These graphics routines live inside the same operational reality as your boot and tooling discipline:

Old graphics programming is rarely “graphics only.” It is always an ecosystem of memory policy, startup profile, and debugging rhythm.

Next step

Part 3 moves from primitives to actual game-feeling output: masked sprites, palette cycling, and timing control:

Mode X in Turbo Pascal, Part 3: Sprites and Palette Cycling

Primitives are where reliability is born. If your clips are correct and your spans are deterministic, everything built above them gets cheaper to reason about.

One extra practice that helps immediately is recording a tiny “primitive conformance” script in your repo: expected screenshots or checksum-like pixel probes for a fixed test scene. Run it after every renderer change. In retro projects, visual regressions often creep in from seemingly unrelated optimizations, and this one habit catches them early.

Mode X in Turbo Pascal, Part 3: Sprites and Palette Cycling

Sun, 22 Feb 2026 00:00:00 +0000

Sprites are where a renderer starts to feel like a game engine. In Mode X, the challenge is not just drawing images quickly. The challenge is managing transparency, overlap order, and visual dynamism while staying within the strict memory and bandwidth constraints of VGA-era hardware.

If your primitives and clipping are not stable yet, go back to Part 2. Sprite bugs are hard enough without foundational uncertainty.

Sprite data strategy: keep it explicit

A reliable sprite pipeline separates three concerns:

Source pixel data.
Optional transparency mask.
Draw routine that respects clipping and planes.

Trying to “infer” transparency from arbitrary colors in ad-hoc code works until assets evolve. Use explicit conventions and document them in your asset converter notes.

Masked blit pattern

A classic masked blit uses one pass to preserve destination where mask says transparent, then overlays sprite pixels where opaque. In Turbo Pascal, even simple byte-level logic remains effective if your loops are predictable.

Pseudo-shape:

for sy := 0 to SpriteH - 1 do
  for sx := 0 to SpriteW - 1 do
    if Mask[sx, sy] <> 0 then
      PutPixelX(DstX + sx, DstY + sy, Sprite[sx, sy]);

You can optimize later with span-based opaque runs. First make it correct under clipping and page boundaries.

Clipping sprites without branching chaos

A practical trick: precompute clipped source and destination windows once per sprite draw call. Then inner loops run branch-light:

srcStartX/srcStartY
srcEndX/srcEndY
dstStartX/dstStartY

This keeps the “should I draw this pixel?” decision out of every iteration and dramatically reduces bug surface.

Draw order as policy

In old-school 2D engines, z-order usually means “draw in sorted sequence.” Keep that sequence explicit:

background
terrain decals
actors
projectiles
effects
HUD

When overlap glitches appear, deterministic order lets you debug with confidence instead of guessing whether timing or memory corruption is involved.

Palette cycling: cheap motion, strong mood

Palette tricks are one of the most useful VGA-era superpowers. Instead of rewriting pixel memory, rotate a subset of palette entries and let existing pixels “animate” automatically. Water shimmer, terminal glow, warning lights, and magic effects become nearly free per frame.

procedure RotatePaletteRange(FirstIdx, LastIdx: Byte);
var
  TmpR, TmpG, TmpB: Byte;
  I: Integer;
begin
  { Assume Palette[] holds RGB triples in 0..63 VGA range }
  TmpR := Palette[LastIdx].R;
  TmpG := Palette[LastIdx].G;
  TmpB := Palette[LastIdx].B;
  for I := LastIdx downto FirstIdx + 1 do
    Palette[I] := Palette[I - 1];
  Palette[FirstIdx].R := TmpR;
  Palette[FirstIdx].G := TmpG;
  Palette[FirstIdx].B := TmpB;
  ApplyPaletteRange(FirstIdx, LastIdx);
end;

The artistic rule is simple: reserve palette bands intentionally. If artists and programmers share the same palette map vocabulary, effects stay predictable.

Timing: lock behavior before optimization

Animation quality depends more on frame pacing than raw speed. Old DOS projects often tied simulation to variable frame rate and then fought phantom bugs for weeks. Better pattern:

fixed simulation tick (e.g., 70 Hz or 60 Hz equivalent)
render as often as practical
interpolate only when necessary

Even on retro hardware, disciplined timing produces smoother perceived motion than occasional fast spikes.

Debug overlays save projects

Add optional overlays you can toggle with a key:

sprite bounding boxes
clip rectangles
page index
tick/frame counters
palette band IDs

These overlays are not “debug clutter.” They are observability for graphics systems that otherwise fail visually without explanation.

Cross references that help this stage

Each one contributes a different layer: memory model, primitive discipline, and workflow habits.

Part 4 moves to tilemaps, camera movement, and data streaming from disk into playable scenes:

Mode X in Turbo Pascal, Part 4: Tilemaps and Streaming

Sprites make a renderer feel alive. Palette cycling makes it feel alive on a budget. Together they are a practical lesson in constraint-driven expressiveness.

If you maintain this code over time, keep a small palette allocation map next to your asset pipeline notes. Which index bands are reserved for UI, which are cycle-safe, which are gameplay-critical. Teams that write this down once avoid months of accidental palette collisions later.

Mode X in Turbo Pascal, Part 4: Tilemaps and Streaming

Sun, 22 Feb 2026 00:00:00 +0000

A renderer becomes a game when it can show world-scale structure, not just local effects. That means tilemaps, camera movement, and disciplined data loading. In Mode X-era development, these systems were not optional polish. They were the only way to present rich scenes inside strict memory budgets.

This final Mode X article focuses on operational structure: how to build scenes that scroll smoothly, load predictably, and remain debuggable.

Start with memory budget, not features

Before defining map format, set your memory envelope:

available conventional/extended memory
VRAM page layout
sprite and tile cache size
IO buffer size

Then derive map chunk dimensions from those limits. Teams that reverse the order usually rewrite their map loader halfway through the project.

Tilemap schema that survives growth

A practical map record often includes:

tile index grid (primary layer)
collision flags
optional overlay/effect layer
spawn metadata
trigger markers

Keep versioning in the file header. Old DOS projects often outlived their first map format and paid dearly for “quick binary dumps” with no compatibility markers.

type
  TMapHeader = record
    Magic: array[0..3] of Char;  { 'MAPX' }
    Version: Word;
    Width, Height: Word;         { in tiles }
    TileW, TileH: Byte;
    LayerCount: Byte;
  end;

Version fields are boring until you need to load yesterday’s assets under today’s executable.

Camera math and draw windows

For each frame:

determine camera pixel position
convert to tile-space window
draw only visible tile rectangle plus one-tile margin

The one-tile margin prevents edge pop during sub-tile movement. Combine this with clipped blits from Part 2 and you get stable scrolling without full-map redraw.

Chunked streaming from disk

Large maps should be chunked. Load around camera, evict far chunks, keep hot set warm.

A simple policy works well:

chunk size fixed (for example 32x32 tiles)
maintain 3x3 chunk neighborhood around camera chunk
prefetch movement direction neighbor

This is not overengineering. On slow storage, missing prefetch translates directly into visible hitching.

Keep IO deterministic

Disk access must avoid unpredictable burst behavior during input-critical moments. Two rules help:

schedule loads at known frame points (post-render or pre-update)
cap max bytes read per frame under stress

When a chunk is not ready, prefer visual fallback tile over frame stall. Small visual degradation is often less disruptive than control latency spikes.

Practical cache keys

Use integer chunk coordinates as cache keys. String keys are unnecessary overhead in this environment and complicate diagnostics.

type
  TChunkKey = record
    CX, CY: SmallInt;
  end;

Pair keys with explicit state flags: Absent, Loading, Ready, Dirty. State clarity is more important than clever container choice.

HUD and world composition

Render world layers first, then entities, then HUD into same draw page. Keep HUD draw routines independent from camera transforms. Many old engines leaked camera offsets into UI code and carried that bug tax for years.

You can validate this quickly by forcing camera to extreme coordinates and checking whether UI still anchors correctly.

Failure modes to test intentionally

Test these early, not at content freeze:

camera crossing chunk boundaries repeatedly
high-speed movement through dense trigger zones
partial chunk read failure
map version mismatch
missing tile index fallback path

Each one should degrade gracefully with explicit logging. Silent corruption is far worse than a visible placeholder tile.

Cross references for full pipeline context

These pieces together describe not just rendering, but operation: startup profile, page policy, draw order, and asset logistics.

Closing note on Mode X projects

Mode X is often presented as nostalgic low-level craft. It is also a great systems-design classroom. You learn cache boundaries, streaming policies, deterministic updates, and diagnostic overlays in an environment where consequences are immediate.

If this series worked, you now have a path from first pixel to world-scale scene architecture:

memory model
primitives
sprites and timing
streaming and camera

That sequence is still useful on modern engines. The APIs changed. The discipline did not.

Treat your map format docs as part of runtime code quality. A map pipeline without explicit contracts eventually becomes an incident response problem.

Turbo Pascal BGI Tutorial: Dynamic Drivers, Linked Drivers, and Diagnostic Harnesses

Sun, 22 Feb 2026 00:00:00 +0000

This tutorial gives you a practical BGI workflow that survives deployment:

dynamic driver loading from filesystem
linked-driver strategy for lower runtime dependency risk
a minimal diagnostics harness for startup failures

Preflight: what you need

Turbo Pascal / Borland Pascal environment with Graph unit
one known-good BGI driver set and required .CHR fonts
a test machine/profile where paths are not identical to dev directories

TP5 baseline reminder:

compile needs GRAPH.TPU
runtime needs .BGI drivers
stroked fonts need .CHR files

Step 1: dynamic loading baseline

Create BGITEST.PAS:

program BgiTest;

uses
  Graph, Crt;

var
  gd, gm, gr: Integer;

begin
  gd := Detect;
  InitGraph(gd, gm, '.\BGI');
  gr := GraphResult;
  Writeln('Driver=', gd, ' Mode=', gm, ' GraphResult=', gr);
  if gr <> grOk then
    Halt(1);

  SetColor(15);
  OutTextXY(8, 8, 'BGI OK');
  Rectangle(20, 20, 200, 120);
  ReadKey;
  CloseGraph;
end.

Expected outcome:

with correct path/assets: startup succeeds and simple frame draws
with missing assets: GraphResult indicates error and program exits cleanly

Important TP5 behavior: GraphResult resets to zero after being called. Always store it to a variable once, then evaluate that value.

Path behavior detail: if InitGraph(..., PathToDriver) gets an empty path, the driver files must be in the current directory.

Step 2: deployment discipline for dynamic model

Package checklist:

executable
all required .BGI files for target adapters
all required .CHR fonts
documented runtime path policy

Most “BGI bugs” are missing files or wrong path assumptions.

Step 3: linked-driver strategy (when you need robustness)

Some Borland-era setups support converting/linking BGI driver binaries into object modules and registering them before InitGraph (for example through RegisterBGIdriver and related registration APIs).

General workflow:

run BINOBJ on .BGI file(s) to get .OBJ
link .OBJ file(s) into program
call RegisterBGIdriver before InitGraph
call InitGraph and verify GraphResult

Why teams did this:

fewer runtime file dependencies
simpler deployment to constrained/chaotic DOS installations

Tradeoff:

larger executable and tighter build coupling

Ordering constraint from TP5 docs: calling RegisterBGIdriver after graphics are already active yields grError (-11).

If you use InstallUserDriver with an autodetect callback, TP5 expects that callback to be a FAR-call function with no parameters returning an integer mode or grError.

Step 4: diagnostics harness you should keep forever

Keep a dedicated harness separate from game/app engine:

prints detected driver/mode and GraphResult
renders one line, one rectangle, one text string
exits on keypress

This lets you quickly answer: “is graphics stack alive?” before debugging your full renderer.

Add one negative test here too: intentionally pass wrong mode for a known driver and verify expected grInvalidMode (-10).

Step 5: test matrix (predict first, then run)

Define expected outcomes before running each case:

correct BGI path
missing driver file
missing font file
wrong current directory
TSR-heavy memory profile

For each case, record:

startup status
exact error code/output
whether fallback path triggers correctly

Recommended TP5 error codes to classify in logs:

grNotDetected (-2)
grFileNotFound (-3)
grInvalidDriver (-4)
grNoLoadMem (-5)
grFontNotFound (-8)
grNoFontMem (-9)
grInvalidMode (-10)

Step 6: fallback policy for production-ish DOS apps

Never rely on detect-only logic without fallback:

try preferred mode
fallback to known-safe mode
print actionable error if both fail

A black screen is a product bug, even in retro projects.

About creating custom BGI drivers

Writing full custom BGI drivers is advanced and depends on ABI/tooling details that are often version-specific and poorly documented. Practical teams usually ship stock drivers (dynamic or linked) unless there is a hard requirement for new hardware support.

If you must go custom, treat it as a separate reverse-engineering project with its own test harnesses and compatibility matrix.

Integration notes with overlays and memory strategy

If graphics startup becomes unstable after enabling overlays:

verify overlay initialization order
verify memory headroom before InitGraph
test graphics harness independently from overlayed application paths

This avoids mixing two failure domains during triage.

Memory interaction note from TP5 docs:

Graph allocates heap memory for graphics buffer/driver/font paths
OvrSetBuf also reshapes memory by shrinking heap
call order matters (OvrSetBuf before InitGraph when both are used)

Turbo Pascal Toolchain, Part 4: Graphics Drivers, BGI, and Rendering Integration

Sun, 22 Feb 2026 00:00:00 +0000

Turbo Pascal graphics was never just “call Graph and draw.” In production-ish DOS projects, graphics was an asset pipeline problem, a deployment problem, and a diagnostics problem at least as much as an API problem.

This part focuses on BGI driver mechanics, practical packaging, and the exact checks that separate real faults from folklore.

Structure map: BGI architecture and operational models → Graph unit runtime contracts and GraphResult handling → dynamic vs linked drivers, packaging and pitfalls → font/driver matrix and memory interactions → BGI artifacts in build and deploy pipelines → debugging rendering failures on real DOS → team checklists and release hardening.

BGI architecture in practical terms

The Graph unit provides the API. Under it, runtime driver/font assets do the hardware-specific work. The unit itself is statically linked; it does not contain adapter-specific code. Instead, it loads a driver binary that knows how to program the hardware (CGA, EGA, VGA, Hercules, etc.) and interpret high-level drawing calls. Fonts are separate assets because they are large and optional — you only load the ones your UI needs.

driver assets: usually .BGI (e.g. EGAVGA.BGI, CGA.BGI)
font assets: .CHR stroked fonts (e.g. TRIP.CHR, GOTH.CHR)
initialization: InitGraph(driver, mode, path)
status reporting: GraphResult
cleanup: CloseGraph

Two operational models exist:

Dynamic runtime loading from filesystem path — driver and font files are read from disk at InitGraph time.
Linked-driver — driver (and optionally font) binaries converted to .OBJ and linked into the executable; registration APIs make them available before InitGraph.

Both are valid. Pick by deployment constraints: dynamic keeps builds small and simple but requires correct runtime paths; linked reduces file dependencies and installer mistakes at the cost of executable size and build coupling. Many teams shipped dynamic for development and internal testing, then produced a linked-driver build for floppy or constrained deployments where users were unlikely to preserve directory structure correctly.

Graph unit runtime contracts and GraphResult handling

Every Graph operation that can fail updates an internal error code. GraphResult returns that code and, in TP5, resets it to zero on read. That one-read semantic causes subtle bugs when code checks GraphResult multiple times or assumes it remains set across calls.

Contract rules:

Call GraphResult once after any operation that may fail, store the value in a local variable, then branch on that variable.
Do not assume GraphResult stays non-zero until the next failed operation.
Never call GraphResult before the operation you intend to check — earlier successful operations clear it.

{ WRONG: second check sees zero from first read }
InitGraph(gd, gm, '.\BGI');
if GraphResult <> grOk then Halt(1);
if GraphResult <> grOk then ...   { always passes; result was cleared }

{ RIGHT: single read, then use stored value }
InitGraph(gd, gm, '.\BGI');
gr := GraphResult;
if gr <> grOk then
  begin
    Writeln('Init failed: ', gr);
    Halt(1);
  end;

TP5 error codes worth memorizing for triage:

Code	Constant	Typical cause
0	`grOk`	Success
-1	`grNoInitGraph`	Graphics not initialized
-2	`grNotDetected`	No compatible adapter found
-3	`grFileNotFound`	Driver or font file missing on path
-4	`grInvalidDriver`	Driver format invalid or mismatched
-5	`grNoLoadMem`	Not enough heap for driver/buffer
-8	`grFontNotFound`	Font file missing
-9	`grNoFontMem`	Not enough heap for font
-10	`grInvalidMode`	Mode not supported by driver
-11	`grError`	General error; often registration/order violation

When grNoLoadMem appears, suspect overlay buffer sizing or TSR load order before blaming hardware. When grFileNotFound appears, verify PathToDriver resolves from the process’s current directory, not the source tree. Some TP/BP variants may use PathStr or environment variables for default paths; the TP5 reference is explicit that an empty path means current directory, and documentation for later versions should be consulted if behavior differs.

Uncertainty note: Exact GraphResult semantics and numeric codes can vary slightly between TP5, TP6, TP7, and BP7. The table above reflects TP5 reference values; when targeting multiple versions, confirm codes in your toolchain’s GRAPH.TPU or include files.

TP5 baseline facts from the reference guide

For Turbo Pascal 5.0, the reference guide is explicit:

compile-time dependency: GRAPH.TPU
runtime dependency: one or more .BGI drivers
if stroked fonts are used: one or more .CHR files

InitGraph loads the selected driver and enters graphics mode. CloseGraph unloads/restores previous mode. This is the lifecycle baseline. After CloseGraph, you may re-enter graphics mode with another InitGraph call, but driver and font state are reset; any registered user drivers must be re-registered if you use the linked model.

Dynamic model: fastest to start, easiest to break in deployment

uses Graph;
var
  gd, gm, gr: Integer;
begin
  gd := Detect;
  InitGraph(gd, gm, 'C:\APP\BGI');
  gr := GraphResult;
  if gr <> grOk then
    begin
      Writeln('BGI init failed: ', gr);
      Halt(1);
    end;
  { render }
  CloseGraph;
end.

Expected outcome:

works immediately in dev environment with full BGI directory
fails fast if path/assets are missing, with actionable error code

Common failure is not code. It is wrong path assumptions after installation. Typical mistakes: hardcoding C:\TP\BGI or .\BGI when the app runs from A:\ or a network drive; assuming GetDir equals executable directory; using forward slashes on systems that expect backslashes.

TP5 path behavior: if PathToDriver is empty, driver files must be in the current directory. If you pass a path, it must end with a trailing backslash on some implementations to be treated as a directory. Conservative practice: always pass an explicit path built from ParamStr(0) or GetDir, and ensure it ends with \.

Path resolution example:

uses Dos, Graph;
var
  ExeDir, BgiPath: PathStr;
  Name, Ext: PathStr;
begin
  FSplit(ParamStr(0), ExeDir, Name, Ext);
  BgiPath := ExeDir + 'BGI' + '\';
  InitGraph(gd, gm, BgiPath);
  gr := GraphResult;
  ...
end.

This assumes BGI is a subdirectory next to the executable. If you ship with BGI alongside .EXE, this pattern works regardless of where the user installed the app.

Triage for dynamic-load failures:

Run the diagnostic harness (see below) from the same directory and path the app will use in production.
If harness works but app fails, compare paths and current-directory assumptions between harness and app.
If grFileNotFound: list directory contents, verify file names match exactly (case may matter on some setups).
If grNoLoadMem: reduce overlay buffer, close TSRs, or switch to linked driver.

Linked-driver model: more robust runtime, tighter build coupling

Some Borland-era toolchains support converting/linking driver binaries into object form and registering them at startup (for example via RegisterBGIdriver and companion font registration APIs). This avoids runtime dependency on external .BGI files but increases binary size and build complexity.

Practical pattern:

convert/select driver object module
link object into project ({$L ...} or linker config)
register driver before InitGraph
call InitGraph with empty or local path expectations

Exact symbol names and conversion utilities depend on installation/profile, so document your specific toolchain once and keep it version-pinned.

TP5 manual flow for linked drivers is concrete:

convert .BGI to .OBJ with BINOBJ
link resulting .OBJ into the executable
call RegisterBGIdriver before InitGraph

If you call RegisterBGIdriver after graphics are already active, TP5 reports grError (-11). Same rule applies to RegisterBGIfont: register before first use of that font.

BINOBJ invocation (exact syntax varies by Borland install):

`1`	`BINOBJ EGAVGA.BGI EGAVGA EGAVGA`

This produces EGAVGA.OBJ with symbols for the binary blob. The linker then pulls it in via {$L EGAVGA.OBJ}. The two symbol names after the filename are typically the public name and the segment/object name; consult your BINOBJ documentation. After conversion, add the .OBJ to your build and ensure it is linked before the unit that calls RegisterBGIdriver. If the symbol is undefined at link time, the .OBJ was not included or the declaration does not match BINOBJ output.

Illustrative registration shape (symbol names vary by conversion/tooling):

{$L EGAVGA.OBJ}

procedure RegisterEgaVga; external;

begin
  RegisterBGIdriver(@RegisterEgaVga);
  { or InstallUserDriver + callback, depending on toolchain }
  InitGraph(gd, gm, '');
  gr := GraphResult;
  if gr <> grOk then Halt(1);
  { ... }
end.

Treat symbol names as toolchain-specific; BINOBJ output and TP/BP docs define the exact entry. If registration order is wrong, you get grError with no obvious message — add logging before each Graph call during integration.

Pitfalls: Forgetting to register before InitGraph; registering after InitGraph; linking the wrong driver .OBJ for the target adapter; mixing driver versions (e.g. TP5 vs BP7) when BGI format differs. Another pitfall: assuming Detect returns the same driver on all VGA systems. Some VGA clones or BIOS quirks can cause Detect to fail or return a conservative mode; hardcoding a fallback (e.g. if gd = Detect then gd := VGA; gm := VGAHi) can improve robustness when autodetect is unreliable. When linking multiple drivers (e.g. VGA + CGA fallback), register all before InitGraph; the order may matter for some toolchains — consult your Graph unit docs. A linked build that works in the IDE can fail at standalone run if the .OBJ was not linked or the external symbol name does not match BINOBJ output; add a build step that verifies the linked executable size increased by the expected driver blob size.

Asset set discipline (driver + font matrix)

For each shipping mode profile, define and freeze:

required driver files (e.g. EGAVGA.BGI for VGA, CGA.BGI for CGA fallback)
required font files (e.g. TRIP.CHR, GOTH.CHR if SetTextStyle uses them)
fallback mode behavior (what mode to try if Detect fails or preferred mode unavailable)
startup diagnostics text (what to print on failure)

Without this matrix, BGI deployment drifts silently between machines. One developer ships with EGAVGA.BGI only; another’s machine has CGA.BGI in path; field reports “black screen” and nobody knows which adapter or driver set was used.

Driver and font packaging rules: Drivers and fonts must be version-pinned to the toolchain that produced GRAPH.TPU. TP5 EGAVGA.BGI is not guaranteed compatible with BP7’s Graph unit; format and entry-point layout can differ. Package drivers as a locked set: document “EGAVGA.BGI from TP5.0 install dated 1989” in your release notes. Fonts are similarly sensitive: a .CHR from one toolchain may load but render incorrectly with another. When upgrading the compiler, re-validate the full driver+font matrix against your harness before cutting a release. Include file sizes and checksums in the manifest so swapped or corrupted copies are detectable.

Font/driver matrix discipline: Not all fonts work with all drivers. Stroked fonts (.CHR) are driver-independent in principle, but SetTextStyle calls before a font is loaded fall back to default. Document which fonts are required for each UI path. If you use InstallUserFont or RegisterBGIfont, the registration order and timing must match the matrix — register before any SetTextStyle that selects that font. A minimal matrix might look like:

Target adapter	Driver	Fonts used	Fallback mode
VGA	EGAVGA.BGI	TRIP, GOTH	VGAHi
EGA	EGAVGA.BGI	TRIP	EGALo
CGA	CGA.BGI	(default)	CGAC0

Ship only drivers and fonts listed for your supported targets. Including extra files “just in case” increases install size and the chance of path confusion. Update the matrix when adding support for new adapters (e.g. Hercules, MCGA) or when dropping support for legacy hardware.

BGI artifacts in build and deploy pipelines

BGI assets are build outputs as much as runtime dependencies. Include them in your artifact pipeline so releases are reproducible.

Package layout:

RELEASE/
  MYAPP.EXE
  BGI/
    EGAVGA.BGI
    CGA.BGI
  FONTS/
    TRIP.CHR
    GOTH.CHR
  README.TXT

If using linked drivers, BGI/ and FONTS/ may be empty, but the layout should still be documented so installers know what to expect.

Build script integration:

@echo off
set BGI_SRC=C:\TP\BGI
set BGI_OUT=..\RELEASE\BGI
if not exist %BGI_OUT% mkdir %BGI_OUT%
copy %BGI_SRC%\EGAVGA.BGI %BGI_OUT%\
copy %BGI_SRC%\CGA.BGI %BGI_OUT%\
if not exist ..\RELEASE\FONTS mkdir ..\RELEASE\FONTS
copy %BGI_SRC%\TRIP.CHR ..\RELEASE\FONTS\
rem checksum for release manifest
... checksum tool ...

Run the diagnostic harness as a post-build step: execute it from RELEASE\ with BGI as subdirectory and assert GraphResult = grOk. If the harness fails in clean build output, fix paths before shipping. Some teams wired the harness as BUILD.BAT final step with if errorlevel 1 to fail the build.

Checksum discipline: Store MD5 or CRC of each .BGI and .CHR in a manifest. When field reports “weird corruption” or mode errors, compare checksums to rule out truncated or swapped files. A swapped CGA.BGI and EGAVGA.BGI (e.g. misnamed copies) produces grInvalidDriver or garbled output; checksums catch that quickly. Run checksum verification as part of the build pipeline: after copying assets to RELEASE\, compute checksums and append to a MANIFEST.TXT; archive that manifest with the release. During support triage, ask the user to run a simple checksum tool (or provide a tiny .COM that prints file sizes) and compare against the manifest — mismatches point to installer bugs, disk errors, or manual file replacements.

Floppy and installer considerations: If distributing on floppies, put MYAPP.EXE on disk 1 and BGI\ contents on the same or next disk. Installer scripts should copy BGI\ into the target directory and set current-directory expectations in a README. Avoid assuming users will run from a subdirectory; many double-click or type MYAPP from C:\GAMES\ and expect .\BGI to mean C:\GAMES\BGI.

Are BGI file formats fully documented?

Honest answer: not in a stable, complete way that is safe to treat as universal across all TP/BP-era variants. You can inspect BGI bytes and infer structure, but production workflows historically relied on Borland-provided drivers and APIs, not custom byte-level authoring from scratch. Third-party efforts (e.g. SDL_bgi, Free Pascal Graph unit) have reverse-engineered portions of the format for compatibility; those sources may help if you need to validate or debug driver files, but do not assume full specification coverage.

What you can reliably do today:

verify driver/font assets exist and match expected set
checksum assets as release artifacts
use diagnostic harnesses to confirm runtime load path

Diagnostics pitfall: Do not assume a BGI file is valid just because it exists. A truncated or corrupted file can produce grInvalidDriver or unpredictable behavior. If you suspect file integrity, compare size and checksum against a known-good copy from your toolchain installation.

“How are BGI drivers created?” practical answer

Three realistic paths:

Use stock Borland drivers (most common historical path). Ship EGAVGA.BGI, CGA.BGI, etc. from your TP/BP installation. Ensure version consistency: TP5 drivers are not guaranteed compatible with BP7 Graph unit and vice versa. When in doubt, use drivers from the same toolchain that produced GRAPH.TPU.
Link stock drivers into executable for deployment robustness. Convert with BINOBJ, link, register. Same version-pinning rule applies.
Author custom driver only if you own/understand ABI details and tooling. The BGI format includes device-specific entry points, mode tables, and drawing primitives. Third-party documentation (e.g. from replacement BGI projects) exists but varies in accuracy. Treat custom drivers as a separate maintenance burden.

Path 3 is advanced reverse-engineering/ABI work. It is possible, but not the right default for project delivery unless driver capabilities are missing.

BGI startup diagnostics harness (must-have)

program BgiDiag;
uses Graph, Crt;
var
  gd, gm, gr: Integer;
begin
  gd := Detect;
  InitGraph(gd, gm, '.\BGI');
  gr := GraphResult;
  Writeln('Driver=', gd, ' Mode=', gm, ' GraphResult=', gr);
  if gr = grOk then
  begin
    SetColor(15);
    OutTextXY(8, 8, 'BGI init OK');
    Line(0, 0, GetMaxX, GetMaxY);
    ReadKey;
    CloseGraph;
  end
  else
    Writeln('Init failed. Check path, files, memory.');
end.

Run this before debugging your game engine. It isolates path/driver faults from rendering logic faults. Keep it as a separate program in your tree; do not embed it inside the main app, because you want to run it in isolation when the full app crashes before any output. A harness that runs to completion proves the BGI stack works; if the harness fails, fix that before debugging renderer code. Extend the harness when you encounter new failure modes: add a font-load test if grFontNotFound appears in the field, or a Detect-then- forced-mode variant if adapter detection is unreliable. The harness becomes your regression suite for the BGI layer; document each variant and when to run it. Some teams maintained a BGIDIAG.EXE in the release package so support could ask users to run it and report the printed codes — a single number (GraphResult) often suffices to distinguish path, memory, and driver issues without requiring logs or repro steps.

Triage procedure with the harness:

Run from project root with .\BGI containing drivers — expect grOk.
Run from same directory but rename BGI to BGI_BACKUP — expect grFileNotFound; confirm printed code matches.
Run from a directory without BGI subfolder — expect grFileNotFound.
On a TSR-heavy config (mouse, network driver, etc.), run harness — if grNoLoadMem, document minimum free conventional memory for your build.

Important TP5 behavior: GraphResult resets to zero after it has been called. Store it in a variable once and evaluate that variable.

Font handling is a real subsystem

If UI layout depends on font metrics, .CHR assets are first-class artifacts:

version and checksum them
package with same discipline as executables
test fallback behavior explicitly

Silent fallback to default font can break coordinates, clipping, and hit zones. A menu rendered with GOTH.CHR has different line heights than the default; if the font fails to load, text may overlap or clip incorrectly.

TP5 adds two separate extension points:

InstallUserFont (register by name/file path)
RegisterBGIfont (register loaded or linked-in font pointer)

As with drivers, registration must be done before normal graphics workflow relies on those resources. After SetTextStyle(...), check GraphResult if the font was user-installed; grFontNotFound or grNoFontMem indicate load failure.

Memory interaction: Stroked fonts are loaded into heap. A large .CHR plus graphics buffer plus overlay buffer can exhaust conventional memory. If grNoFontMem appears only with certain fonts, try smaller fonts or linked-font approach for the critical path. Font packaging parallels driver packaging: ship only the fonts your UI actually uses, version-pin them to your toolchain, and include checksums in the release manifest. A common mistake is bundling every .CHR from the TP install “for completeness” — this bloats the package and increases the chance of loading the wrong font by typo or path confusion. If SetTextStyle references a font that was never loaded or registered, the unit falls back to default; the fallback is silent, so layout assumptions (lower height, different metrics) can break. Add an explicit font-load check after SetTextStyle for user fonts and log GraphResult during development.

BGI + overlays + memory budget interaction

Graphics initialization and overlays interact with memory pressure. If startup becomes unstable after enabling overlays or TSR-heavy profiles, validate:

available memory headroom before InitGraph
overlay manager buffer size (OvrSetBuf)
order of subsystem initialization

Treat graphics bugs and memory bugs as potentially coupled until proven otherwise. Memory interplay with overlays is the most common source of “works in dev, fails in release” BGI bugs: the overlay manager allocates a contiguous buffer from the heap; Graph allocates its own buffers from the same heap. If the overlay buffer is carved out first, Graph gets what remains; if Graph allocates first and overlays later try to grow, the heap can be fragmented or exhausted. grNoLoadMem often appears when overlay and Graph compete for the same pool without a clear initialization order.

TP5 memory detail: Graph uses heap for graphics buffer, loaded drivers, and loaded stroked fonts (unless linked/registered path is used). This is why overlay buffer sizing (OvrSetBuf) and InitGraph order can conflict.

Order rule: Call OvrSetBuf (and OvrInit) before InitGraph. The overlay manager carves its buffer from the heap; Graph then allocates from what remains. Reversing the order can leave insufficient room for either. A typical failure: InitGraph succeeds, then OvrSetBuf shrinks the heap, and a later overlay load or Graph operation fails with grNoLoadMem or overlay error. The fix is to establish overlay buffer first, then let Graph allocate from the remaining free memory.

OvrInit(OvrFile);
if OvrResult <> ovrOk then Halt(1);
OvrSetBuf(50000);     { before InitGraph }
InitGraph(gd, gm, '.\BGI');
gr := GraphResult;

Memory budgeting: On a 640 KB DOS machine, TSRs and DOS typically consume 50–150 KB. Your app gets the rest. A VGA buffer (640×480×1 byte) is ~300 KB; EGAVGA.BGI adds tens of KB when loaded; stroked fonts add more. If you use overlays, their buffer comes from the same pool. Document a minimum free-memory requirement (e.g. “400 KB free conventional memory”) and test at that threshold. Boot with a minimal CONFIG.SYS and AUTOEXEC.BAT to simulate a memory-tight environment; if your app runs there, it will usually run on richer systems. This simple test catches many “works on my machine” deployment failures.

Overlay–Graph allocation interplay: The heap layout after OvrSetBuf and InitGraph is toolchain- and order-dependent. A rough rule of thumb: VGA graphics buffer (~300 KB) + EGAVGA driver (~30–50 KB when loaded) + one stroked font (~20–40 KB) leaves little for overlays on a 640 KB system with 400 KB free. If you use both overlays and Graph, establish the overlay buffer first with a conservative size, then init Graph; measure free memory before and after each step during integration. Some teams added a startup banner (“Free mem: XXXXX”) before InitGraph to catch regressions. Uncertainty note: Exact allocation order and sizes can vary between TP5, TP6, and BP7; when in doubt, instrument and measure on your target configuration.

Debugging rendering failures on real DOS systems

When graphics fail in the field but work in development, systematic triage narrows the cause. Use a rendering triage loop: run the diagnostic harness first; if it passes, the fault is in application rendering logic or asset loading, not BGI init. If the harness fails, iterate on path, memory, or driver until it passes, then return to the full app. Do not debug a complex renderer while BGI fundamentals are still failing — you will waste time chasing symptoms (e.g. “Line draws wrong”) that stem from an earlier init or mode problem.

Release verification on real hardware: Before signing off a build, run the full checklist on at least one physical DOS machine (or a well-configured emulator that matches period behavior). Boot from floppy or minimal HD; run from A:\, C:\GAMES, and a nested subdirectory; try with and without common TSRs (mouse, sound driver). Known problematic configurations include: VGA clones with nonstandard BIOS mode tables, EGA systems with 256 KB vs 64 KB variants, and machines with < 400 KB free conventional memory. Document which adapter and memory profile you verified; when field reports arrive, compare against that baseline. A build that has never been run on real hardware is a risk.

Triage steps:

Black screen, no message: Program may be exiting before any output. Add a Writeln('Starting...') before InitGraph; if it never appears, the crash is earlier (e.g. overlay init, missing .OVR). On some DOS configurations, mode switch can also blank the screen before text output is visible; redirect output to a file (MYAPP > LOG.TXT 2>&1) to confirm whether any text was produced.
Black screen, message appeared then vanished: Mode switch may have failed, or the program exited immediately. Ensure GraphResult is checked and stored before any cleanup; add ReadKey or Delay before CloseGraph in harness to confirm. If the message flashes too quickly to read, write it to a file as well.
Wrong resolution or garbled display: Driver/mode mismatch. Detect may pick a different mode on different adapters; log gd and gm and compare to adapter documentation. Force a known mode (e.g. gd := VGA; gm := VGAHi) for compatibility testing.
Works once, fails on second run: TSR or environment pollution. Reboot to clean state; disable TSRs one by one. Some drivers leave video state inconsistent after CloseGraph.
grNoLoadMem on target only: Conventional memory too low. Run MEM before app; compare to dev machine. Reduce overlay buffer or ship linked driver build.

Keep a triage log: adapter type, driver set, free memory, TSR list, and exact GraphResult value. Reproducible cases go into the test matrix. When a new symptom appears (e.g. “screen flickers then goes black”), add a minimal reproducer to the harness: if you can trigger it there, debug there; if only the full app exhibits it, the cause is likely in overlay loading order, asset sequencing, or interaction with game/UI logic. This divide-and-conquer approach keeps triage loops short and deterministic.

Team checklists and release hardening

Before release, the team should complete:

Pre-build:

Unit search path, object path, and BGI asset path documented and version-pinned
Build script produces deterministic output (clean build, no stale artifacts)

Build:

All required .BGI and .CHR copied to release layout
Diagnostic harness runs successfully from release directory
Checksums recorded for .EXE, .OVR (if used), .BGI, .CHR

Post-build verification:

Test from directory different from source (e.g. C:\TEST\, A:\)
Intentionally remove one driver, run app — verify error message, no crash
Test with overlay file missing (if applicable) — verify controlled exit
One memory-stressed run (e.g. with MEM reporting < 400 KB free)
Run diagnostic harness from same release layout; assert it reports grOk
If distributing on floppy: boot from disk 1, run from A:\, confirm BGI path resolves correctly (e.g. A:\BGI\ when app is on A:\)

Release package:

README includes BGI path requirements and minimum memory
Build manifest (checksums, compiler version, options) archived with artifacts

Expected outcome: actionable startup message on any failure, never black-screen ambiguity. When a user reports “does not work,” the checklist gives you questions to ask (adapter, path, memory, exact error text) instead of blind guesswork. Teams that shipped without this discipline often spent hours on support calls trying to reproduce “black screen” with no data. A single Writeln('BGI error: ', gr) before Halt(1) can save days of debugging.

Useful TP5 InitGraph failure codes to log:

grNotDetected (-2)
grFileNotFound (-3)
grInvalidDriver (-4)
grNoLoadMem (-5)
grInvalidMode (-10)

Where to go deeper

Turbo Pascal Toolchain, Part 5: From 6.0 to 7.0 - Compiler, Linker, and Language Growth

Graphics on TurboVision

Mode 13h in Turbo Pascal: Graphics Programming Without Illusions

Mode X in Turbo Pascal, Part 1: Planar Memory and Pages

Why Mode X felt “faster” in real games

The key shift: from linear bytes to planes

Entering a workable 320x240-like unchained setup

Plotting one pixel with plane selection

Pages and start address flipping

Practical debugging advice

Where we go next

Mode X in Turbo Pascal, Part 2: Primitives and Clipping

Primitive design goals

Clipping is policy, not an afterthought

Horizontal fills with reduced state changes

Rectangle fills and UI panels

Line drawing without hidden chaos

Instrument your renderer early

Structured pass order

Cross-reference with existing DOS workflow

Next step

Mode X in Turbo Pascal, Part 3: Sprites and Palette Cycling

Sprite data strategy: keep it explicit

Masked blit pattern

Clipping sprites without branching chaos

Draw order as policy

Palette cycling: cheap motion, strong mood

Timing: lock behavior before optimization

Debug overlays save projects

Cross references that help this stage

Next article

Mode X in Turbo Pascal, Part 4: Tilemaps and Streaming

Start with memory budget, not features

Tilemap schema that survives growth

Camera math and draw windows

Chunked streaming from disk

Keep IO deterministic

Practical cache keys

HUD and world composition

Failure modes to test intentionally

Cross references for full pipeline context

Closing note on Mode X projects

Turbo Pascal BGI Tutorial: Dynamic Drivers, Linked Drivers, and Diagnostic Harnesses

Preflight: what you need

Step 1: dynamic loading baseline

Step 2: deployment discipline for dynamic model

Step 3: linked-driver strategy (when you need robustness)

Step 4: diagnostics harness you should keep forever

Step 5: test matrix (predict first, then run)

Step 6: fallback policy for production-ish DOS apps

About creating custom BGI drivers

Integration notes with overlays and memory strategy

Turbo Pascal Toolchain, Part 4: Graphics Drivers, BGI, and Rendering Integration

BGI architecture in practical terms

Graph unit runtime contracts and GraphResult handling

TP5 baseline facts from the reference guide

Dynamic model: fastest to start, easiest to break in deployment

Linked-driver model: more robust runtime, tighter build coupling

Asset set discipline (driver + font matrix)

BGI artifacts in build and deploy pipelines

Are BGI file formats fully documented?

“How are BGI drivers created?” practical answer

BGI startup diagnostics harness (must-have)

Font handling is a real subsystem

BGI + overlays + memory budget interaction

Debugging rendering failures on real DOS systems

Team checklists and release hardening

Where to go deeper