NextLibrary - Z80 Assembly Utilities Library for Spectrum and Next

A high-performance, utility library for Z80 assembly development on the ZX Spectrum and ZX Spectrum Next platforms. The choice is yours, you can use device independent routines or limit yourself to platform specific routines for a single target architecture.

NextLibrary provides world-class mathematical operations, random number generation, screen management, DMA operations, and utility functions optimized for retro game development and system programming.

It offers hardware independent routines that work on both Spectrum and Spectrum Next hardware. It also provides equivalent and optimised Next only versions making use of Z80N Next only extended op codes and DMA for best performance.

T-State tables in this document also allow for easy performance and requirement assessment by the developer.

Release History

v1.10 - Plus 3 Hardware Double Buffering

Key improvements:

• Plus 3 Double Buffering: Complete hardware double buffering implementation for Spectrum +3 and Next
• Hardware Bank Switching: True hardware double buffering using +3 memory banking (99.93% faster than software copying)
• Smart Buffer Management: Intelligent off-screen buffer setup with automatic bank switching at $C000
• Frame-Synchronized Swapping: HALT-synchronized buffer swaps to eliminate screen tearing
• State Synchronization: Robust tracking of hardware banking state with automatic correction
• Optimized Performance: Buffer swaps in ~75-95 T-states vs 145,152 T-states for memory copying
• Complete Double Buffering Suite: Software copying (all platforms) + hardware switching (+3/Next)
• Developer-Friendly API: Simple setup, set, and toggle operations with consistent addressing

Plus 3 double buffering performance achievements:

• Setup: ~200 T-states + screen clearing (one-time initialization)
• Buffer Set: ~35-55 T-states (smart banking, only when needed)
• Buffer Toggle: ~75-95 T-states (instant display swap with HALT synchronization)
• Performance vs Software: 99.93% faster than traditional screen copying methods
• Frame Rate: 1 frame per vsync due to use of HALT, so we get 50FPS (PAL 50Hz) or 60FPS (NTSC 60Hz)

Architecture completion:

• Universal Double Buffering: Software methods (48K/128K/+2/+3/Next) + hardware methods (+3/Next)
• Comprehensive Graphics Pipeline: Traditional screens + Layer 2 + hardware double buffering
• Platform Optimization: Optimal methods for every Spectrum platform and capability
• Complete Screen Operations: Clearing, copying, and double buffering with maximum performance

v1.9 - Layer 2 Screen Copying and Advanced Graphics Pipeline

Key improvements:

• Layer 2 Screen Copying: Complete Layer 2 copying suite with 8 performance levels from LDIRX to DMA burst acceleration
• Multi-Resolution Layer 2 Support: Full support for all Layer 2 modes (256×192, 320×256, 640×256) with optimized copying routines
• Layer 2 Manual Copying: Direct address and resolution specification for maximum control
  • LDIRX methods: 78,663 to 262,224 T-states depending on resolution
  • DMA methods: 260 to 600 T-states for hardware-accelerated copying
• Layer 2 Auto-Detection Copying: Intelligent Layer 2 configuration detection with optimal method selection
  • Auto LDIRX: Automatic resolution detection with Z80N optimization
  • Auto DMA: Automatic detection with DMA burst for maximum performance
• Advanced Graphics Pipeline: Foundation for sophisticated Layer 2 graphics operations and double-buffering
• Unified Copy API: Single interface supporting traditional screens and all Layer 2 modes seamlessly
• Performance Optimization: Layer 2 256×192 mode 46% faster than traditional screen copying with LDIRX

Layer 2 copying performance achievements:

• Layer 2 256×192 LDIRX: 44.4 FPS (46% faster than traditional screen)
• Layer 2 320×256 LDIRX: 26.7 FPS (enhanced resolution with good performance)
• Layer 2 640×256 LDIRX: 13.3 FPS (maximum resolution with acceptable performance)
• Layer 2 DMA Methods: 5,800+ to 13,500+ FPS (99.5%+ faster than traditional methods)
• Cross-Resolution Support: Same API works across all Layer 2 modes with automatic optimization

Notable pending features:

• Hardware Double Buffer Swapping: Layer 2 bank switching for instant buffer swaps (SCREEN_COPY_LAYER2_DOUBLE_BUFFER_BANK)
• Plus 3 Double Buffering: Spectrum Plus 3 specific double buffering optimization (SCREEN_COPY_DOUBLE_BUFFER_PLUS_3)

Architecture enhancements:

• Layer 2 Memory Management: Intelligent handling of large Layer 2 buffers with multi-bank DMA operations
• Resolution-Aware Operations: Automatic memory size calculation based on Layer 2 mode detection
• Hardware Acceleration: DMA burst modes optimized for different Layer 2 resolutions
• Performance Scaling: Excellent performance across all Next CPU speeds (3.5MHz to 28MHz)

v1.8 - Advanced Screen Copying and DMA Memory Operations

Key improvements:

• Advanced Screen Copying: Complete screen copying suite with 9 performance levels from basic LDIR to DMA acceleration
• Multi-Platform Screen Copy: Unified API supporting all Spectrum platforms (48K/128K/+2/+3/Next)
• Software Optimization Mastery: Progressive stack-based optimizations (1PUSH through ALLPUSH) achieving up to 27.9 FPS on standard Z80
• Z80N Screen Copy Acceleration: LDIRX optimization providing 31.6 FPS theoretical maximum (31% faster than LDIR)
• DMA Screen Copy Revolution: DMA-based copying achieving 12,500+ FPS theoretical maximum (99.8% faster than LDIR)
• Flexible Screen Addressing: Support for custom source and destination addresses enabling advanced software double-buffering
• DMA Memory Copy Utilities: General-purpose memory copying routines with standard and burst modes
• Frame Rate Analysis: Complete performance analysis across all Next CPU speeds (3.5MHz to 28MHz)
• Optimal Algorithm Selection: Intelligent performance level selection based on available hardware capabilities

Screen copying performance achievements:

• Standard Z80 Peak: ALLPUSH method achieving 27.9 FPS (14% faster than LDIR)
• Z80N Enhancement: LDIRX achieving 31.6 FPS (24% faster than LDIR)
• DMA Acceleration: DMA_BURST achieving 12,500+ FPS (99.8% faster than LDIR)

v1.7 - Layer 2 Graphics Support and Enhanced Modularity

Key improvements:

• 62 Test Cases: Expanded test suite from 59 to 62 comprehensive test cases including Layer 2 validation
• Layer 2 Graphics Support: Complete Layer 2 utility functions for Next hardware graphics programming
• Layer 2 Screen Clearing: Ultra-fast Layer 2 clearing using DMA with support for all resolutions (256×192, 320×256, 640×256)
• Layer 2 Detection: Hardware detection for active Layer 2 with resolution and address retrieval
• Enhanced Modularity: Split constants and variables into separate domain-specific files for easier partial library adoption
• Improved Developer Experience: Cleaner file organization allowing developers to include only needed components
• Layer 2 Information Retrieval: Complete Layer 2 configuration detection including resolution, color depth, and memory requirements
• Extended Graphics Pipeline: Foundation for advanced Layer 2 graphics operations and double-buffering

Layer 2 performance improvements:

• Layer 2 DMA Clearing: Up to 99.8% faster Layer 2 screen clearing using DMA burst mode
• Resolution Detection: Fast Layer 2 configuration retrieval (83-157 T-states)
• Memory Efficient: Optimized Layer 2 operations with minimal CPU overhead
• Hardware Adaptive: Automatic fallback to standard operations if Layer 2 unavailable

File structure improvements:

• Modular Constants: Separate files for Maths, Random, Display, and DMA constants
• Organized Variables: Domain-specific variable files for cleaner partial library usage
• Developer Friendly: Extract only needed components without dependency overhead

v1.6 - Enhanced Screen Management and DMA Support

Key improvements:

• 59 Test Cases: Expanded test suite from 57 to 59 comprehensive test cases including DMA validation
• Flexible Screen Addressing: All screen clearing routines now accept HL parameter for custom screen locations
• In-Memory Screen Support: Full support for off-screen rendering and secondary screen buffers
• DMA Screen Clearing: Ultra-fast screen clearing using Spectrum Next DMA controller (99% faster)
• Z80N Enhanced Screen Operations: LDIRX optimization for 33% faster screen clearing on Next hardware
• Hardware Detection: Automatic detection of Z80N and DMA capabilities with graceful fallbacks
• Memory Fill Operations: Complete