VBXE FX and GTIA cores v1.27.3 - package, issue 3
==================================================

Tomasz Piórek / electron, 2026-11-04

VBXE cores v1.27.3 for VBXE 1.x and 2.x, the Atari tools to install and run
them, their sources, test programs, demos, the PAL and NTSC palettes and older
examples by other authors.

v1.27.3 is the base version of the v1.27 cores. Because of the palette
selection fix and the new SR16 graphics mode, cores v1.27 and v1.27.2 should
be upgraded to v1.27.3; an upgrade is recommended for everyone.

All cores in this package have the public beta status. There will be no
separate final release: use these cores and do not wait for a final version.

What is new in v1.27.3
----------------------

  - Palette selection bug of v1.27 and v1.27.2 fixed. A color palette
    selected by a program through the XDL should be in effect, as in v1.26,
    from the point where it is selected to the end of the screen, and every
    new screen should start with the default palette. In v1.27 and v1.27.2
    the selected palette carried over into the next screen, so its upper
    part, down to the point where the XDL selected the palette again, could
    show wrong colors. With the XDL switched off, the selected palette
    stayed on the whole screen until RESET. It now works as in v1.26.
  - New Overlay graphics mode SR16: 16 colors with the horizontal resolution
    of the SR mode (320 pixels for the NORMAL width), using as little memory
    as the LR mode (2 pixels per byte, 160 bytes per line). It is selected
    by XDLC_OV_HR and XDLC_OV_LR set together.
  - More precise synchronisation with the computer and more reliable data
    from the bus, which improves cooperation with devices that put their
    data on the bus late (for example SUBcart) and with modified computers.
  - Software cannot tell v1.27.3 from v1.27 or v1.27.2 (the same VERSION
    value). Apart from the SR16 mode, features and registers are the same,
    so existing programs need no changes.

The full list of changes is in the HISTORY section of the Programmer's Manual.

New VBXE DOCTOR v1.5
--------------------

The package contains a new version of VBXE DOCTOR (tests/vdoctor.xex, also on
the disk images), a diagnostic program that checks the VBXE registers, the
whole VRAM through the MEMAC windows and the Blitter. Among others it checks
how the VBXE cooperates with other devices on the bus: MEMAC-A windows that
reach the end of the address space ($FFFF), and the closing of the windows by
the VBXE soft reset. Single tests can be left out in its test selection
window. Its user manual is in tests/vdoctor.zip.

SR16 test
---------

tests/sr16test.xex (SR16TEST.XEX on the disk images) shows four pictures, each
in the SR16 mode and right below it in the SR mode as the reference: color
bars, 1-pixel stripes, 1-pixel lines and 8x8 text, with ANTIC hires ticks
above and below each picture to check the position against the ANTIC
playfield. With the SR16 mode both halves of every picture look the same;
tests/sr16test.zip contains reference pictures of the screen with and without
the SR16 mode (sr16_new.png, sr16_old.png, sr16_zoom.png). It is a tool
intended mainly for the development and testing of VBXE emulators.

Antonia 2 users
---------------

With the current Antonia 2 soft-core, VBXE DOCTOR v1.5 reports errors in three
tests. They come from two incompatibilities of the Antonia 2 soft-core, not
from a VBXE fault or a damaged Antonia 2:

  - A07 (Soft reset), errors with verdict R at 8123/4 and 7FF0/16: after the
    VBXE soft reset (write to $D080) Antonia 2 still treats the MEMAC
    windows as open and sends the accesses in the windows to the VBXE
    instead of the computer's RAM.
  - B04 (MEMAC-A windows) and B06 (MEMAC-A window writes), errors with M in
    column S of the log: Antonia 2 does not pass accesses to MEMAC-A windows
    that reach the end of the address space ($FFFF), so reads give the
    computer's RAM and writes go to it instead of VRAM. The detail view B04
    shows errors in all windows that reach $FFFF and none in the others.

These incompatibilities concern rarely used combinations of settings, so most
VBXE programs should work with Antonia 2 without problems.

An update of the Antonia 2 soft-core is required for full compatibility with
VBXE.

Until then, these tests can be left out in VBXE DOCTOR: press INVERSE to open
the test selection, move the cursor with - / = to A07 and press SPACE to
deselect it, then press B and deselect B04 and B06 the same way, and press
RETURN to start the tests again. At every start of the program all tests are
selected again, so the selection has to be repeated.

SUBcart users
-------------

SUBcart with its built-in 1 MB PORTB memory extension enabled is not
compatible with VBXE (SUBcart firmware v012 and v013 beta 1). In this mode
SUBcart puts its own memory in place of the computer's RAM at $A000-$BFFF, so
MEMAC windows in this area do not work (a limitation of SUBcart, not a VBXE
fault), while the smaller PORTB modes (128, 192, 320 and 576 KB) and SUBcart
with the extension off work with VBXE. Limited compatibility with VBXE is also
possible in some of the cartridge emulation modes of SUBcart (running programs
from .car files).

How to upgrade
--------------

Run FC (FC.XEX) from one of the disk images in images/ (VBXE_FX_127_MYDOS.ATR
or VBXE_FX_127_SDX.ATR) and install the core file for your board (VBXE 1.x /
2.x) and TV system (PAL / NTSC) into a FLASH bank. If the new core should
start at power-on and you install it into a bank other than the current
BootBank, make that bank the BootBank with the B key, as FC does not change
this by itself (when a core is replaced in the bank that already is the
BootBank, the setting is kept). Step-by-step instructions are in
tools/FC_and_DCFG_User_Manual.md ("Install a core from disk").

Loading FC from the MyDOS image:

  1. Mount VBXE_FX_127_MYDOS.ATR as drive D1: (for example in SIO2SD,
     SIO2PC or another device that supports 1.25 MB images with 256-byte
     sectors).
  2. Switch the computer on with the OPTION key held down (BASIC off);
     MyDOS loads and shows its menu. If BASIC starts instead, type DOS and
     press RETURN.
  3. Press L (Binary Load), type FC.XEX and press RETURN.

Compatibility
-------------

Compatibility has to be provided by all the devices connected to the
computer at the same time. There are situations in which VBXE works
correctly on its own, but does not in combination with another device,
either internal or connected externally to the bus of the computer.

Turbo systems (6502 replacements) change the architecture of the computer
in various, often quite radical ways, with consequences for compatibility
that are hard to predict and different for each device. VBXE works in such
an environment on a best-effort basis. See chapter 2 of the Programmer's
Manual.

Core files (cores/*.xbf)
------------------------

  v1f127a1.xbf
  | ||  ||
  | ||  |+-- 1 = PAL, 2 = NTSC
  | ||  +--- a = no RAMBO extended memory
  | |+------ 127 = core version 1.27
  | +------- f = FX core, g = GTIA core
  +--------- v1 = VBXE 1.x, v2 = VBXE 2.x

Choose the file for your board (VBXE 1.x or 2.x) and your TV system.
Install it into a FLASH bank with FC (key L) or load it once with DCFG.
See tools/FC_and_DCFG_User_Manual.md.

Requirements
------------

  FC, DCFG, VQREBOOT, VXREBOOT  any VBXE 1.x / 2.x
  VHCLIP                        FX or GTIA core v1.27
  vbxe240p                      FX core v1.26 or newer
  blitter1, blitter2            FX core v1.26 (tests 1-88) or v1.27 (all 150 tests)
  SIGS, Wolfette                FX core v1.27
  VBXE DOCTOR (vdoctor)         FX or GTIA core v1.26 or newer, 64 KB RAM
  sr16test                      FX core v1.26 or newer (SR16 mode: v1.27.3)

All programs are Atari DOS executables (.xex) for an Atari XL/XE with VBXE.
The disk images in images/ contain all .xex and .xbf files of the package:
  VBXE_FX_127_MYDOS.ATR  bootable MyDOS 4.55 Beta 4, 1.25 MB, 256-byte sectors
  VBXE_FX_127_SDX.ATR    SpartaDOS file system for SpartaDOS X 4.50,
                         1.25 MB, 256-byte sectors, not bootable
                         (SpartaDOS X starts from its cartridge)
  On the disks the Blitter tests are BLITTER1.XEX and BLITTER2.XEX.

Building the tools
------------------

MADS 2.1.7, in the mads directory:
  mads fc.mads -x -i:include -o:fc.xex
  mads dcfg.mads -x -i:include -o:dcfg.xex
  mads vqreboot.mads -x -i:include -o:vqreboot.xex
  mads vxreboot.mads -x -i:include -o:vxreboot.xex
  mads vhclip.mads -x -i:include -o:vhclip.xex
These commands build the files in tools/.
The test programs and demos are built with llvm-mos, see the README in
their source archives (tests/vdoctor.zip holds only the program and its
manual, without sources).

Palettes
--------

palettes/ holds the PAL and NTSC palettes of the cores:
  PAL.act        PAL palette, 256 colors x RGB, 8 bits per component
  NTSC.act       NTSC palette, the same format
  palettes.mads  both palettes for MADS: separate 256-byte tables of the
                 R, G and B components (pal_r, pal_g, pal_b, ntsc_r,
                 ntsc_g, ntsc_b), index = Atari color
The VBXE uses bits [7:1] of each component (CR, CG, CB registers), so the
values can be written to the registers directly.

Old examples
------------

old_examples/ contains older VBXE example programs and sources by other
authors, one directory per author: Candle, Electron, Fox, KMK,
LAMERS_Group, Rybags, TeBe. They are included as they are, without
changes, and are not described further here; see the readme files in the
author directories (KMK, Fox) where present.

File list
---------

  README.txt                                                    this file
  VBXE_FX_and_GTIA_cores_v1.27_Programmers_Manual.md    130701  Programmer's Manual of the FX and GTIA cores v1.27
  VBXE_FX_and_GTIA_cores_v1.27_Programmers_Manual.pdf   816287  the same manual as PDF
  cores/v1f127a1.xbf                                     98062  FX core v1.27.3, VBXE 1.x, PAL
  cores/v1f127a2.xbf                                     98062  FX core v1.27.3, VBXE 1.x, NTSC
  cores/v1g127a1.xbf                                     98062  GTIA core v1.27.3, VBXE 1.x, PAL
  cores/v1g127a2.xbf                                     98062  GTIA core v1.27.3, VBXE 1.x, NTSC
  cores/v2f127a1.xbf                                     98062  FX core v1.27.3, VBXE 2.x, PAL
  cores/v2f127a2.xbf                                     98062  FX core v1.27.3, VBXE 2.x, NTSC
  cores/v2g127a1.xbf                                     98062  GTIA core v1.27.3, VBXE 2.x, PAL
  cores/v2g127a2.xbf                                     98062  GTIA core v1.27.3, VBXE 2.x, NTSC
  tools/fc.xex                                            9439  FC - Flash Configurator v1.20
  tools/dcfg.xex                                          5182  DCFG - Direct Configurator v2.15
  tools/vqreboot.xex                                       580  VQREBOOT - restart the BootBank core, silent
  tools/vxreboot.xex                                       798  VXREBOOT - restart the BootBank core, with messages
  tools/vhclip.xex                                          61  VHCLIP - persistent hard clipping (CLIP + PXGF)
  tools/FC_and_DCFG_User_Manual.md                       11558  user manual of FC and DCFG
  tools/VQREBOOT_and_VXREBOOT_User_Manual.md              2761  user manual of VQREBOOT and VXREBOOT
  tools/VHCLIP_User_Manual.md                             1639  user manual of VHCLIP
  mads/fc.mads                                           50287  FC source
  mads/dcfg.mads                                         20068  DCFG source
  mads/vqreboot.mads                                      8649  VQREBOOT source
  mads/vxreboot.mads                                     10223  VXREBOOT source
  mads/vhclip.mads                                        2089  VHCLIP source
  mads/include/atarihw.mads                              11682  Atari hardware registers
  mads/include/atarios.mads                               8207  Atari OS variables and routines
  mads/include/filebox.mads                              42449  file selection box, windows, I/O routines
  mads/include/macros.mads                                9551  memory copy / fill macros
  mads/include/vbxefx.mads                               39002  VBXE FX core registers and macros
  tests/blitter1.xex                                     17158  Blitter test: all tests once, waits for keys
  tests/blitter2.xex                                     16966  Blitter test: endless loop, stops at the first failure
  tests/blitter.zip                                      54427  Blitter test sources (llvm-mos C) and test list
  tests/vbxe240p.xex                                     11253  VBXE 240p Test Suite v1.0
  tests/vbxe240p.zip                                     52262  VBXE 240p Test Suite sources (llvm-mos C) and user manual
  tests/vdoctor.xex                                      38169  VBXE DOCTOR v1.5 - VBXE diagnostic (registers, VRAM, Blitter)
  tests/vdoctor.zip                                     327122  VBXE DOCTOR program and user manual (MD, PDF)
  tests/sr16test.xex                                     11047  SR16 test: SR16 mode next to an SR reference
  tests/sr16test.zip                                     40735  SR16 test sources (llvm-mos C), README and reference pictures (PNG)
  demos/sigs.xex                                        124749  SIGS - Strong Independent Girls Demo
  demos/sigs.zip                                        872814  SIGS sources (llvm-mos C, Python asset tools)
  demos/wolfette.xex                                     29534  Wolfette - raycasting demo
  demos/wolfette.zip                                     57341  Wolfette sources (llvm-mos C)
  images/VBXE_FX_127_MYDOS.ATR                         1310352  bootable MyDOS 4.55 disk with all programs and cores
  images/VBXE_FX_127_SDX.ATR                           1310352  SpartaDOS X disk with all programs and cores
  palettes/PAL.act                                         768  PAL palette (ACT)
  palettes/NTSC.act                                        768  NTSC palette (ACT)
  palettes/palettes.mads                                  9968  PAL and NTSC palettes as MADS data tables
  old_examples/                                                 older examples by other authors (573 files, see above)
