VIXL - Vector Input Execution Loop

A lightweight, modern C++ library for window management and input handling on Windows platforms. VIXL provides direct control over window creation, event processing, and OpenGL context management through a clean, developer-friendly API.

Features

• Window Management: Create and manage multiple windows with full property control
• Input Handling: Real-time keyboard and mouse input with per-window state isolation
• Event System: Comprehensive callback system for window, keyboard, and mouse events
• OpenGL Integration: Native OpenGL context management with multiple contexts support
• Error Handling: Robust exception system with detailed error codes and categories
• Thread Safety: Safe concurrent access to input states and window properties
• Modern C++: Built with C++17 features, RAII resource management, and clean APIs

Quick Start

Prerequisites

• Windows 10/11
• MSYS2 environment with GCC 15.2.0+
• Basic C++ development knowledge

Installation

1. Clone the repository:

git clone <repository-url>
cd vixl

2. Build the library:

make static    # Build static library
# or
make dynamic   # Build dynamic library

3. Build examples:

make examples

Basic Usage

#include "include/vixl.h"

int main() {
    try {
        // Initialize VIXL system
        vixl::initialize();
        
        // Create a window
        vixl::Window window(800, 600, "Hello VIXL!");
        window.show();
        
        // Set up event callback
        vixl::addEventCallback(vixl::EventType::KEY_PRESS, 
            [&window](const vixl::Event& event) {
                if (event.data.keyboard.key == static_cast<int>(vixl::KeyCode::ESCAPE)) {
                    window.setShouldClose(true);
                }
            });
        
        // Main loop
        while (!window.shouldClose()) {
            vixl::pollEvents(16); // ~60 FPS
        }
        
        // Cleanup
        vixl::terminate();
        
    } catch (const vixl::VixlException& e) {
        std::cerr << "VIXL Error: " << e.what() << std::endl;
        return 1;
    }
    
    return 0;
}

OpenGL Example

#include "include/vixl.h"
#include <windows.h>
#include <gl/GL.h>

int main() {
    try {
        vixl::initialize();
        
        vixl::Window window(800, 600, "VIXL OpenGL");
        vixl::OpenGLContext context(&window);
        
        window.show();
        context.makeCurrent();
        
        // Set clear color
        glClearColor(0.2f, 0.3f, 0.8f, 1.0f);
        
        while (!window.shouldClose()) {
            vixl::pollEvents(16);
            
            glClear(GL_COLOR_BUFFER_BIT);
            context.swapBuffers();
        }
        
        vixl::terminate();
    } catch (const vixl::VixlException& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }
    
    return 0;
}

Build System

VIXL uses GNU Make with MSYS2 integration:

# Build targets
make all        # Build static library, dynamic library, and examples
make static     # Build static library (.a)
make dynamic    # Build dynamic library (.dll)
make examples   # Build example applications
make test       # Build and run tests (requires Google Test)

# Documentation
make docs       # Generate API documentation using Doxygen
make view-docs  # Generate and open documentation in browser

# Utility targets
make clean      # Remove all build artifacts
make clean-all  # Remove all artifacts including documentation
make rebuild    # Clean and rebuild everything
make help       # Show all available targets

Project Structure

vixl/
├── include/            # Public API headers
│   └── vixl.h         # Main public header
├── src/               # Implementation source files
│   ├── window.cpp     # Window management
│   ├── event_system.cpp # Event handling
│   ├── input_manager.cpp # Input processing
│   ├── opengl_context.cpp # OpenGL integration
│   ├── system.cpp     # Core system
│   └── error_handling.cpp # Error management
├── examples/          # Example applications
│   ├── basic_window.cpp
│   ├── input_handling.cpp
│   ├── multi_window.cpp
│   └── opengl_rendering.cpp
├── tests/             # Unit and integration tests
├── docs/              # Documentation
│   ├── index.html     # Documentation portal
│   ├── quick.md       # Quick start guide
│   ├── intro.md       # Comprehensive introduction
│   └── api/           # Generated API documentation
├── build/             # Compiled binaries and libraries
└── obj/               # Object files

Documentation

Comprehensive documentation is available in multiple formats:

• Quick Start Guide - Get running in 5 minutes
• Introduction - Detailed concepts and architecture
• API Reference - Complete API documentation
• Interactive Portal - Web-based documentation hub

Generate the complete documentation:

make docs

Examples

The examples/ directory contains practical demonstrations:

• basic_window.cpp - Simple window creation and management
• input_handling.cpp - Keyboard and mouse input processing
• multi_window.cpp - Multiple window management
• opengl_rendering.cpp - OpenGL context and rendering
• window_events_demo.cpp - Event system demonstration
• error_handling_demo.cpp - Error handling patterns

Build and run examples:

make examples
./build/basic_window

Testing

VIXL includes comprehensive unit and integration tests using Google Test:

# Build and run all tests
make test

# Individual test categories are available in tests/
# - test_window.cpp: Window management tests
# - test_events.cpp: Event system tests  
# - test_input.cpp: Input handling tests
# - test_opengl.cpp: OpenGL context tests
# - test_system.cpp: Core system tests
# - test_error_handling.cpp: Error handling tests

Architecture

VIXL is designed with a modular architecture:

• Core System: Initialization, cleanup, and global state management
• Window Management: Window creation, properties, and lifecycle
• Event System: Event queue, callbacks, and message processing
• Input Manager: Keyboard and mouse state tracking with per-window isolation
• OpenGL Context: Context creation, management, and operations
• Error Handling: Comprehensive exception system with categorized error codes

Platform Requirements

• Operating System: Windows 10/11
• Compiler: GCC 15.2.0+ with C++17 support
• Build System: GNU Make 3.81+
• Environment: MSYS2 (recommended)
• Libraries: Win32 API (user32, gdi32, opengl32)

Performance Characteristics

• Minimal Overhead: Direct Win32 API integration without abstraction layers
• Memory Efficient: RAII resource management with automatic cleanup
• Thread Safe: Safe concurrent access to input states and window properties
• Scalable: Supports multiple windows and OpenGL contexts efficiently

API Highlights

Core Functions

void vixl::initialize();                    // Initialize VIXL system
void vixl::terminate();                     // Clean up VIXL system
void vixl::pollEvents(int timeoutMs = 0);   // Process events

Window Management

vixl::Window window(800, 600, "Title");     // Create window
window.show();                              // Show window
window.setSize(1024, 768);                  // Resize window
window.setPosition(100, 100);               // Move window

Event Handling

vixl::addEventCallback(vixl::EventType::KEY_PRESS, callback);
vixl::addEventCallback(vixl::EventType::MOUSE_MOVE, callback);
vixl::addEventCallback(vixl::EventType::WINDOW_RESIZE, callback);

Input Queries

vixl::KeyState state;
vixl::getKeyState(&window, vixl::KeyCode::W, state);
vixl::getMouseButtonState(&window, vixl::MouseButton::LEFT, state);
vixl::getCursorPosition(&window, x, y);

OpenGL Integration

vixl::OpenGLContext context(&window);       // Create context
context.makeCurrent();                      // Activate context
context.swapBuffers();                      // Present frame
context.setSwapInterval(1);                 // Enable VSync

Error Handling

VIXL uses a comprehensive exception system:

try {
    vixl::Window window(800, 600, "App");
} catch (const vixl::VixlException& e) {
    std::cout << "Error Code: " << static_cast<int>(e.getErrorCode()) << std::endl;
    std::cout << "Message: " << e.what() << std::endl;
    std::cout << "Category: " << (e.isWindowError() ? "Window" : "Other") << std::endl;
}

Error categories include:

• System errors (initialization, state)
• Window errors (creation, properties)
• Context errors (OpenGL operations)
• Input errors (state queries)
• Operation errors (general failures)

Contributing

We welcome contributions to VIXL! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes with appropriate tests
4. Ensure all tests pass: make test
5. Update documentation if needed: make docs
6. Submit a pull request

Development Setup

# Clone and setup
git clone https://github.com/AdrianParedez/vixl
cd vixl

# Build everything
make clean; make all; make test

# Generate documentation
make docs

License

VIXL is released under the MIT License. See LICENSE.md for details.

Support

• Documentation: docs/index.html
• Examples: examples/
• Issues: GitHub Issues
• API Reference: docs/api/

Acknowledgments

• Built with the Win32 API for native Windows integration
• Uses Google Test for comprehensive testing
• Documentation generated with Doxygen
• Inspired by GLFW's clean API design

---

VIXL - Empowering developers with direct control over Windows applications