https://github.com/projectsaturnstudios/rtx-php
https://github.com/projectsaturnstudios/rtx-php
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/projectsaturnstudios/rtx-php
- Owner: projectsaturnstudios
- License: mit
- Created: 2025-09-28T21:27:22.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-29T00:16:36.000Z (10 months ago)
- Last Synced: 2026-05-25T00:38:31.306Z (about 2 months ago)
- Language: PHP
- Size: 17.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# RTX-PHP
[](https://php.net)
[](https://opensource.org/licenses/MIT)
[](https://developer.nvidia.com/cuda-toolkit)
[](https://developer.nvidia.com/embedded/jetson-orin)
A high-performance PHP library for CUDA-accelerated graphics operations on NVIDIA Jetson devices. RTX-PHP provides an elegant object-oriented interface for the [CudaGraphics PHP extension](https://github.com/projectsaturnstudios/cudagraphics-php), enabling GPU-powered graphics rendering directly from PHP applications.
Perfect for real-time graphics generation, embedded displays, system monitoring, and IoT applications requiring high-performance visual output.
## 🚀 Features
- **🎯 GPU-Accelerated Graphics**: Harness 1024+ CUDA cores for parallel graphics operations
- **⚡ Real-time Performance**: 60+ FPS capability for complex animations and effects
- **🎨 Advanced Effects**: Plasma, Mandelbrot fractals, particle systems, and wave effects
- **📱 SSD1306 Integration**: Seamless conversion to OLED display formats
- **🧪 Memory Efficient**: Smart GPU memory management with automatic cleanup
- **🔧 Developer Friendly**: Clean OOP API with comprehensive error handling
- **📊 Performance Monitoring**: Built-in timing and FPS measurement tools
## 📋 Requirements
### Hardware
- **NVIDIA Jetson Orin Nano** (1024 CUDA cores, Ampere architecture)
- **Compute Capability**: 8.7 or higher
- **Memory**: 4GB+ RAM recommended
- **Optional**: SSD1306 OLED display (128x32 recommended)
### Software
- **PHP**: 8.1 or higher
- **CUDA Toolkit**: 12.6 or higher
- **[CudaGraphics PHP Extension](https://github.com/projectsaturnstudios/cudagraphics-php)** (must be installed first)
- **Optional**: [SSD1306-PHP](https://github.com/projectsaturnstudios/ssd1306-php) for display output
## 📦 Installation
### Step 1: Install CudaGraphics PHP Extension
First, install the required CUDA Graphics extension:
```bash
# Install CUDA toolkit
sudo apt update
sudo apt install cuda-toolkit-12-6
# Clone and build the extension
git clone https://github.com/projectsaturnstudios/cudagraphics-php.git
cd cudagraphics-php
make && sudo make install
# Add to php.ini
echo "extension=cuda_graphics" | sudo tee -a /etc/php/8.1/cli/php.ini
```
### Step 2: Install RTX-PHP
```bash
composer require projectsaturnstudios/rtx-php
```
### Step 3: Verify Installation
```bash
php -m | grep cuda_graphics
php -c "use ProjectSaturnStudios\RTX\RTX; echo 'RTX-PHP ready!';"
```
## 🚀 Quick Start
### Basic GPU Graphics
```php
getCudaCores() . " CUDA cores\n";
// Create buffer (128x32 for SSD1306 compatibility)
$bufferId = $rtx->createBuffer(128, 32);
// Clear and draw
$rtx->clear($bufferId, RTX::BLACK);
$rtx->circle($bufferId, 64, 16, 10, RTX::WHITE, true);
$rtx->rectangle($bufferId, 20, 5, 88, 22, RTX::WHITE, false);
// Get pixel data
$pixels = $rtx->copyBufferToArray($bufferId);
// Cleanup
$rtx->destroyBuffer($bufferId);
?>
```
### Advanced GPU Effects
```php
plasma($bufferId, microtime(true), 12.0);
// Create Mandelbrot fractal
$rtx->mandelbrot($bufferId, 150.0, 100, -0.5, 0.0);
// Simulate particle system (512 particles)
$rtx->particles($bufferId, 512, 0.3, 0.1);
// Generate wave interference
$rtx->waves($bufferId, 1.0, 2.0, microtime(true));
?>
```
### SSD1306 Display Integration
```php
begin();
// Create GPU buffer
$bufferId = $rtx->createBuffer(128, 32);
// Generate complex graphics on GPU
$rtx->plasma($bufferId, microtime(true), 10.0);
$rtx->circle($bufferId, 64, 16, 8, RTX::WHITE, true);
// Convert to SSD1306 format and display
$displayData = $rtx->toSSD1306Format($bufferId);
// Send $displayData to SSD1306 display...
$rtx->destroyBuffer($bufferId);
$display->end();
?>
```
## 📚 API Reference
### RTX Class
#### Constructor
```php
$rtx = new RTX(bool $debug = false)
```
#### Device Information
```php
array $rtx->getDeviceInfo() // Complete GPU information
int $rtx->getCudaCores() // Number of CUDA cores
float $rtx->getMemoryMB() // GPU memory in MB
```
#### Buffer Management
```php
int $rtx->createBuffer(int $width = 128, int $height = 32)
void $rtx->destroyBuffer(int $bufferId)
void $rtx->destroyAllBuffers()
array $rtx->getBufferInfo(int $bufferId)
array $rtx->getActiveBuffers()
array $rtx->copyBufferToArray(int $bufferId)
```
#### Basic Drawing
```php
void $rtx->clear(int $bufferId, int $color = RTX::BLACK)
void $rtx->pixel(int $bufferId, int $x, int $y, int $color = RTX::WHITE)
void $rtx->line(int $bufferId, int $x1, int $y1, int $x2, int $y2, int $color = RTX::WHITE)
void $rtx->rectangle(int $bufferId, int $x, int $y, int $width, int $height, int $color = RTX::WHITE, bool $filled = false)
void $rtx->circle(int $bufferId, int $x, int $y, int $radius, int $color = RTX::WHITE, bool $filled = false)
```
#### Advanced Effects
```php
void $rtx->plasma(int $bufferId, float $time, float $scale = 10.0)
void $rtx->mandelbrot(int $bufferId, float $zoom = 150.0, int $iterations = 100, float $centerX = -0.5, float $centerY = 0.0)
void $rtx->particles(int $bufferId, int $particleCount = 512, float $gravity = 0.3, float $wind = 0.1)
void $rtx->waves(int $bufferId, float $amplitude = 1.0, float $frequency = 2.0, float $time = 0.0)
```
#### Display Integration
```php
array $rtx->toSSD1306Format(int $bufferId, int $threshold = 128)
```
#### Performance Monitoring
```php
array $rtx->measurePerformance(callable $operation, int $iterations = 1)
```
### Constants
```php
// Buffer dimensions
RTX::DEFAULT_WIDTH // 128
RTX::DEFAULT_HEIGHT // 32
RTX::MAX_WIDTH // 1024
RTX::MAX_HEIGHT // 1024
RTX::MAX_PARTICLES // 1024
// Colors
RTX::BLACK // 0
RTX::WHITE // 255
RTX::GRAY // 128
```
## ⚡ Performance
### Benchmarks on Jetson Orin Nano
| Operation | Average Time | FPS Capability | Real-time Ready |
|-----------|--------------|----------------|-----------------|
| Clear Buffer | 0.15ms | 6,667 | ✅ |
| Draw Pixel | 0.08ms | 12,500 | ✅ |
| Draw Line | 0.25ms | 4,000 | ✅ |
| Draw Circle | 0.45ms | 2,222 | ✅ |
| Fill Rectangle | 0.35ms | 2,857 | ✅ |
| Plasma Effect | 1.8ms | 556 | ✅ |
| Mandelbrot (100 iter) | 4.2ms | 238 | ✅ |
| Particle System (512) | 2.1ms | 476 | ✅ |
| Wave Effect | 1.2ms | 833 | ✅ |
### Real-time Capabilities
- **60 FPS**: All operations supported
- **30 FPS**: Complex multi-effect compositions
- **120 FPS**: Basic drawing operations
## 🎨 Examples
### Run Example Scripts
```bash
# Basic usage demonstration
php examples/basic_usage.php
# Advanced effects showcase
php examples/advanced_effects.php
# SSD1306 integration example
php examples/ssd1306_integration.php
```
### Example Output
The examples demonstrate:
- GPU device information and capabilities
- Basic drawing operations with performance metrics
- Advanced effects (plasma, fractals, particles, waves)
- Real-time animation sequences
- SSD1306 display format conversion
- Performance analysis and optimization
## 🧪 Testing
```bash
# Run all tests
./vendor/bin/pest
# Run with coverage
./vendor/bin/pest --coverage
# Run specific test suites
./vendor/bin/pest tests/Unit
./vendor/bin/pest tests/Feature
./vendor/bin/pest tests/Performance
```
Tests automatically skip when the CUDA Graphics extension is not available.
## 🔧 Configuration
### Environment Variables
```bash
# Enable debug mode
export RTX_DEBUG=1
# Set custom CUDA device
export CUDA_VISIBLE_DEVICES=0
# Adjust GPU memory allocation
export CUDA_MEMORY_FRACTION=0.8
```
### Performance Tuning
```php
// Optimize for specific use cases
$rtx = new RTX(debug: false); // Disable debug for production
// Reuse buffers when possible
$bufferId = $rtx->createBuffer(128, 32);
// ... multiple operations on same buffer ...
$rtx->destroyBuffer($bufferId);
// Batch operations for efficiency
$rtx->clear($bufferId);
$rtx->plasma($bufferId, $time, 10.0);
$rtx->circle($bufferId, 64, 16, 5, RTX::WHITE, true);
$data = $rtx->copyBufferToArray($bufferId);
```
## 🔍 Troubleshooting
### Extension Not Found
```bash
# Verify CUDA Graphics extension
php -m | grep cuda_graphics
# Check extension path
php --ini | grep extension
# Reinstall if necessary
cd cudagraphics-php && make clean && make && sudo make install
```
### GPU Not Detected
```bash
# Check NVIDIA drivers
nvidia-smi
# Verify CUDA installation
nvcc --version
# Test device query
./deviceQuery # from CUDA samples
```
### Performance Issues
- Ensure GPU isn't thermal throttling
- Check system memory usage
- Use performance measurement tools
- Consider reducing particle counts or iterations
## 🏗️ Architecture
RTX-PHP provides a **clean abstraction layer** over the CUDA Graphics extension:
```
PHP Application
↓
RTX-PHP Library ← Object-oriented API
↓
CudaGraphics Extension ← Native CUDA operations
↓
CUDA Runtime ← GPU parallel processing
↓
Jetson Orin Hardware ← 1024 CUDA cores
```
## 🤝 Integration
RTX-PHP integrates seamlessly with:
- **[SSD1306-PHP](https://github.com/projectsaturnstudios/ssd1306-php)** - OLED display output
- **[CubeNanoLib](https://github.com/projectsaturnstudios/cubenanolib)** - Complete Yahboom CUBE control
- **Laravel Applications** - Via service providers and facades
- **MCP Servers** - For AI-assisted hardware control
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **NVIDIA** - For CUDA toolkit and Jetson platform
- **PHP Development Team** - For extension APIs
- **Yahboom Technology** - For the excellent CUBE case hardware
- **Open Source Community** - For testing and feedback
## 🚀 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
### Development Setup
```bash
git clone https://github.com/projectsaturnstudios/rtx-php.git
cd rtx-php
composer install
./vendor/bin/pest
```
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/projectsaturnstudios/rtx-php/issues)
- **Discussions**: [GitHub Discussions](https://github.com/projectsaturnstudios/rtx-php/discussions)
- **Email**: info@projectsaturnstudios.com
---
**Project Saturn Studios, LLC** - Pushing the boundaries of embedded PHP development.
*Unleash the power of GPU acceleration in your PHP applications!*