0.0.9 opengl interop

Author: offerrall

.github/workflows/build.yml

@@ -39,7 +39,7 @@ jobs:
           CIBW_SKIP: "cp36-* cp37-* cp38-* cp39-* pp* *-musllinux_*"
           CIBW_BUILD_VERBOSITY: 1
           CIBW_BEFORE_ALL_LINUX: >
-            yum install -y yum-utils &&
+            yum install -y yum-utils mesa-libGL-devel &&
             yum-config-manager --add-repo https://developer.download.nvidia.com/compute/cuda/repos/rhel8/x86_64/cuda-rhel8.repo &&
             yum install -y cuda-nvcc-12-5 cuda-cudart-devel-12-5
           CIBW_ENVIRONMENT_LINUX: >

CMakeLists.txt

@@ -1,7 +1,6 @@
 cmake_minimum_required(VERSION 3.18)
 
 set(CMAKE_CUDA_RUNTIME_LIBRARY Static)
-
 set(CMAKE_POSITION_INDEPENDENT_CODE ON) 
 
 project(pyimagecuda_internal LANGUAGES CXX CUDA)
@@ -15,14 +14,19 @@ endif()
 
 find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
 find_package(CUDAToolkit REQUIRED)
+find_package(OpenGL REQUIRED)
 
 file(GLOB_RECURSE SOURCES "src/*.cu" "src/*.cpp")
 
 python_add_library(pyimagecuda_internal MODULE ${SOURCES} WITH_SOABI)
 
 target_include_directories(pyimagecuda_internal PRIVATE src)
 
-target_link_libraries(pyimagecuda_internal PRIVATE CUDA::cudart_static Python::Module)
+target_link_libraries(pyimagecuda_internal PRIVATE 
+    CUDA::cudart_static 
+    Python::Module
+    OpenGL::GL
+)
 
 install(TARGETS pyimagecuda_internal DESTINATION pyimagecuda)
 install(DIRECTORY pyimagecuda DESTINATION .)

README.md

@@ -1,4 +1,4 @@
-# PyImageCUDA 0.0.8
+# PyImageCUDA 0.0.9
 
 [![PyPI version](https://img.shields.io/pypi/v/pyimagecuda.svg)](https://pypi.org/project/pyimagecuda/)
 [![Build Status](https://github.com/offerrall/pyimagecuda/actions/workflows/build.yml/badge.svg)](https://github.com/offerrall/pyimagecuda/actions)
@@ -38,13 +38,15 @@ with Image(1024, 1024) as bg:
 * ✅ **Ultra-lightweight:** library weighs **~1 MB**.
 * ✅ **Studio Quality:** 32-bit floating-point precision (float32) to prevent color banding.
 * ✅ **Advanced Memory Control:** Reuse GPU buffers across operations and resize without reallocation—critical for video processing and batch workflows.
+* ✅ **OpenGL Integration:** Direct GPU-to-GPU display for real-time preview widgets.
 * ✅ **API Simplicity:** Intuitive, Pythonic API designed for ease of use.
 
 ## Use Cases
 
 * **Generative Art:** Create thousands of unique variations in seconds.
 * **Motion Graphics:** Process video frames or generate effects in real-time.
 * **Image Compositing:** Complex multi-layer designs with GPU-accelerated effects.
+* **Node Editors & Real-time Tools:** Build responsive image editors with instant preview.
 * **Game Development:** Procedural UI assets, icons, and sprite generation.
 * **Marketing Automation:** Mass-produce personalized graphics from templates.
 * **Data Augmentation:** High-speed batch transformations for ML datasets.
@@ -64,6 +66,7 @@ pip install pyimagecuda
 * [Getting Started Guide](https://offerrall.github.io/pyimagecuda/)
 * [Image & Memory](https://offerrall.github.io/pyimagecuda/image/) (Buffer management)
 * [IO](https://offerrall.github.io/pyimagecuda/io/) (Loading and Saving)
+* [OpenGL Integration](https://offerrall.github.io/pyimagecuda/opengl/) (Real-time preview, zero-copy display)
 
 ### Operations
 * [Fill](https://offerrall.github.io/pyimagecuda/fill/) (Solid colors, Gradients, Checkerboard, Grid, Stripes, Dots, Circle, Ngon, Noise, Perlin)
@@ -120,4 +123,4 @@ pytest tests/tests.py
 Contributions welcome! Open issues or submit PRs
 
 ## License
-MIT License. See [LICENSE](LICENSE) for details.
+MIT License. See [LICENSE](LICENSE) for details.

docs/io.md

@@ -133,6 +133,30 @@ How it works:
 2. Downloads from GPU to CPU
 3. Encodes and writes to disk
 
+### Saving U8 Images Directly
+
+When you've manually converted an image to uint8 for another purpose (e.g., OpenGL display, external library) and also want to save it to disk:
+```python
+from pyimagecuda import Image, ImageU8, convert_float_to_u8, save_u8
+
+f32_img = Image(1920, 1080)
+u8_img = ImageU8(1920, 1080)
+
+# Process in float32
+process(f32_img)
+
+# Convert once for multiple uses
+convert_float_to_u8(u8_img, f32_img)
+
+# Use u8_img for display, OpenGL, etc.
+display_opengl(u8_img)
+
+# Save the same u8 buffer
+save_u8(u8_img, "output.png")
+```
+
+**Note:** Most workflows use `save()` directly with float32 images. This function eliminates redundant conversion when you already have the uint8 buffer.
+
 ---
 
 ## NumPy Integration

docs/opengl.md

@@ -0,0 +1,86 @@
+# OpenGL Integration
+
+PyImageCUDA provides a GPU-to-GPU transfer with OpenGL through CUDA-OpenGL interop, enabling efficient real-time preview pipelines.
+
+---
+
+## Overview
+
+**Traditional approach:**
+```
+GPU Processing → CPU Download → CPU Upload → OpenGL Display
+```
+
+**With OpenGL interop:**
+```
+GPU Processing → GPU Copy → OpenGL Display
+```
+
+**Performance:**
+
+- Zero CPU involvement (all transfers GPU-side)
+- ~10x faster than CPU download/upload
+- Sub-millisecond updates for 2K images (~1ms measured)
+- Single GPU-GPU DMA copy (PBO→Texture, asynchronous)
+
+---
+
+## GLResource API
+
+### Constructor
+```python
+GLResource(pbo_id: int)
+```
+Registers an OpenGL PBO with CUDA for interop.
+
+**Parameters:**
+- `pbo_id`: OpenGL buffer ID from `glGenBuffers()`
+
+**Raises:**
+- `ValueError`: If `pbo_id` is invalid
+- `RuntimeError`: If CUDA registration fails
+
+---
+
+### copy_from()
+```python
+gl_resource.copy_from(image: ImageU8) -> None
+```
+Copies ImageU8 data directly to PBO (GPU→GPU, zero CPU overhead).
+
+**Parameters:**
+- `image`: Source ImageU8 buffer
+
+**Raises:**
+- `TypeError`: If image is not ImageU8
+- `RuntimeError`: If resource has been freed
+
+---
+
+### free()
+```python
+gl_resource.free() -> None
+```
+Unregisters the resource. Must be called before deleting the PBO.
+
+**Context Manager:**
+```python
+with GLResource(pbo) as gl_resource:
+    gl_resource.copy_from(image)
+```
+
+## Best Practices
+
+### Display Integration
+- Invert texture Y-coordinates if image appears upside-down
+- Enable `GL_BLEND` for alpha channel support
+
+### Resource Management
+- Create PBO with `GL_STREAM_DRAW` for best performance
+- Pre-allocate buffers to avoid reallocation overhead
+- Call `free()` before deleting OpenGL objects
+
+### Performance
+- Reuse `ImageU8` buffers when possible
+- Use texture size matching image size (or larger)
+- `glTexSubImage2D` with PBO is asynchronous (no CPU stall)

mkdocs.yml

@@ -50,6 +50,7 @@ nav:
   - Home: index.md
   - Image: image.md
   - Load and Save: io.md
+  - OpenGL: opengl.md
   - Fill: fill.md
   - Text: text.md
   - Blend: blend.md

pyimagecuda/__init__.py

@@ -1,7 +1,7 @@
 import ctypes
 import sys
 
-__version__ = "0.0.7"
+__version__ = "0.0.9"
 
 def _check_nvidia_driver():
     try:
@@ -37,7 +37,7 @@ def _check_nvidia_driver():
 if _INTERNAL_LOADED:
     try:
         from .image import Image, ImageU8
-        from .io import upload, download, copy, save, load, convert_float_to_u8, convert_u8_to_float, from_numpy, to_numpy
+        from .io import upload, download, copy, save, load, convert_float_to_u8, convert_u8_to_float, from_numpy, to_numpy, save_u8
         from .fill import Fill
         from .resize import Resize
         from .blend import Blend
@@ -46,6 +46,7 @@ def _check_nvidia_driver():
         from .adjust import Adjust
         from .transform import Transform
         from .text import Text
+        from .gl_interop import GLResource
         from .pyimagecuda_internal import cuda_sync # type: ignore
     except ImportError as e:
         print(f"Warning: Error importing Python wrappers: {e}")

pyimagecuda/gl_interop.py

@@ -0,0 +1,83 @@
+from .pyimagecuda_internal import (  # type: ignore
+    register_gl_pbo,
+    unregister_gl_resource,
+    copy_to_gl_pbo
+)
+from .image import ImageU8
+
+
+class GLResource:
+    """
+    CUDA-OpenGL interop resource for direct GPU-to-GPU transfers.
+    
+    Represents a registered OpenGL PBO that can receive ImageU8 data
+    directly without CPU roundtrips.
+    
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/opengl/
+    """
+    
+    def __init__(self, pbo_id: int):
+        """
+        Parameters:
+            pbo_id: Valid OpenGL PBO ID. The PBO must exist and remain 
+                    valid for the lifetime of this GLResource.
+        
+        Raises:
+            ValueError: If pbo_id is invalid
+            RuntimeError: If CUDA registration fails
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/opengl/
+        """
+        if not isinstance(pbo_id, int) or pbo_id <= 0:
+            raise ValueError(f"Invalid PBO ID: {pbo_id}")
+        
+        self._handle = None
+        self.pbo_id = pbo_id
+        self._handle = register_gl_pbo(pbo_id)
+    
+    def copy_from(self, image: ImageU8) -> None:
+        """
+        Copies ImageU8 data directly to the registered PBO (GPU→GPU).
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/opengl/
+        """
+        if not isinstance(image, ImageU8):
+            raise TypeError(f"Expected ImageU8, got {type(image).__name__}")
+        
+        if self._handle is None:
+            raise RuntimeError("GLResource has been freed")
+        
+        copy_to_gl_pbo(
+            image._buffer._handle,
+            self._handle,
+            image.width,
+            image.height
+        )
+    
+    def free(self) -> None:
+        """
+        Unregisters the OpenGL resource from CUDA.
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/opengl/
+        """
+        if self._handle is not None:
+            unregister_gl_resource(self._handle)
+            self._handle = None
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.free()
+        return False
+    
+    def __del__(self):
+        if hasattr(self, '_handle') and self._handle is not None:
+            try:
+                self.free()
+            except Exception:
+                pass
+    
+    def __repr__(self) -> str:
+        status = "active" if getattr(self, '_handle', None) is not None else "freed"
+        return f"GLResource(pbo_id={self.pbo_id}, status={status})"

pyimagecuda/io.py

@@ -121,26 +121,13 @@ def load(
     return f32_buffer if should_return else None
 
 
-def save(image: Image, filepath: str, u8_buffer: ImageU8 | None = None, quality: int | None = None) -> None:
-    """
-    Saves the floating-point image to a file (using an 8-bit buffer for conversion).
-
-    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#saving-images
-    """
-    if u8_buffer is None:
-        u8_buffer = ImageU8(image.width, image.height)
-        owns_buffer = True
-    else:
-        ensure_capacity(u8_buffer, image.width, image.height)
-        owns_buffer = False
-    
-    convert_float_to_u8(u8_buffer, image)
-    pixel_data = download(u8_buffer)
+def _save_internal(u8_image: ImageU8, filepath: str, quality: int | None = None) -> None:
+    pixel_data = download(u8_image)
 
     vips_img = pyvips.Image.new_from_memory(
         pixel_data,
-        image.width,
-        image.height,
+        u8_image.width,
+        u8_image.height,
         bands=4,
         format='uchar'
     )
@@ -157,10 +144,37 @@ def save(image: Image, filepath: str, u8_buffer: ImageU8 | None = None, quality:
             save_kwargs['Q'] = quality
 
     vips_img.write_to_file(filepath, **save_kwargs)
+
+
+def save(image: Image, filepath: str, u8_buffer: ImageU8 | None = None, quality: int | None = None) -> None:
+    """
+    Saves the floating-point image to a file (using an 8-bit buffer for conversion).
+
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#saving-images
+    """
+    if u8_buffer is None:
+        u8_buffer = ImageU8(image.width, image.height)
+        owns_buffer = True
+    else:
+        ensure_capacity(u8_buffer, image.width, image.height)
+        owns_buffer = False
+    
+    convert_float_to_u8(u8_buffer, image)
+    _save_internal(u8_buffer, filepath, quality)
 
     if owns_buffer:
         u8_buffer.free()
 
+
+def save_u8(image: ImageU8, filepath: str, quality: int | None = None) -> None:
+    """
+    Saves an 8-bit unsigned integer image directly to a file.
+
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#saving-images
+    """
+    _save_internal(image, filepath, quality)
+
+
 def from_numpy(array, f32_buffer: Image | None = None, u8_buffer: ImageU8 | None = None) -> Image:
     """
     Creates a PyImageCUDA Image from a NumPy array (e.g. from OpenCV, Pillow, Matplotlib).