or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdinput-handling.mdlibrary-management.mdmonitor-display.mdopengl-context.mdvulkan-support.mdwindow-management.md
tile.json

tessl/pypi-glfw

A ctypes-based wrapper for GLFW3 that provides Python bindings for OpenGL, OpenGL ES, and Vulkan development on desktop platforms.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/glfw@2.9.x

To install, run

npx @tessl/cli install tessl/pypi-glfw@2.9.0

index.mddocs/

pyGLFW

A comprehensive Python ctypes-based wrapper for GLFW3 that provides complete bindings for OpenGL, OpenGL ES, and Vulkan development on desktop platforms. pyGLFW enables creation of windowed graphics applications with hardware-accelerated rendering, supporting Windows, macOS, and Linux (both X11 and Wayland variants).

Package Information

  • Package Name: glfw
  • Language: Python
  • Installation: pip install glfw
  • Version: 2.9.0
  • License: MIT

Core Imports

import glfw

For C-style API with GLFW prefixes:

import glfw.GLFW as GLFW
# Or to import all constants and functions:
from glfw.GLFW import *

Basic Usage

import glfw

# Initialize GLFW
if not glfw.init():
    raise Exception("GLFW could not be initialized!")

# Create a window
window = glfw.create_window(800, 600, "Hello World", None, None)
if not window:
    glfw.terminate()
    raise Exception("GLFW window could not be created!")

# Make the OpenGL context current
glfw.make_context_current(window)

# Main loop
while not glfw.window_should_close(window):
    # Poll for and process events
    glfw.poll_events()
    
    # Render here (OpenGL calls would go here)
    
    # Swap front and back buffers
    glfw.swap_buffers(window)

# Clean up
glfw.destroy_window(window)
glfw.terminate()

Architecture

pyGLFW closely follows the GLFW C API design with Pythonic enhancements:

  • Library Initialization: Must call glfw.init() before using any GLFW functions
  • Window Management: Create windows with OpenGL/Vulkan contexts for rendering
  • Event System: Callback-based event handling for input, window state changes
  • Cross-Platform: Automatic platform detection and library loading
  • Error Handling: Configurable error reporting (exceptions, warnings, or logging)
  • Memory Management: Automatic cleanup of Python objects and callbacks

Configuration

pyGLFW provides global configuration variables:

# Error reporting configuration
glfw.ERROR_REPORTING = 'warn'  # 'raise', 'warn', 'log', 'ignore', or dict

# Gamma ramp normalization (0.0-1.0 vs 0-65535)
glfw.NORMALIZE_GAMMA_RAMPS = True

Capabilities

Library Management

Core library initialization, termination, and version information functions that must be called before using any other GLFW functionality.

def init() -> int: ...
def terminate() -> None: ...
def init_hint(hint: int, value: int) -> None: ...
def get_version() -> tuple[int, int, int]: ...
def get_version_string() -> bytes: ...
def get_error() -> tuple[int, bytes]: ...

Library Management

Window Management

Complete window lifecycle management including creation, destruction, properties, and state control for OpenGL and Vulkan applications.

def create_window(width: int, height: int, title: str, monitor, share) -> ctypes.POINTER: ...
def destroy_window(window) -> None: ...
def window_should_close(window) -> int: ...
def set_window_should_close(window, value: int) -> None: ...
def set_window_title(window, title: str) -> None: ...
def get_window_pos(window) -> tuple[int, int]: ...
def set_window_pos(window, xpos: int, ypos: int) -> None: ...

Window Management

Input Handling

Comprehensive input system supporting keyboard, mouse, joystick, and gamepad input with both polling and callback-based event handling.

def get_key(window, key: int) -> int: ...
def get_mouse_button(window, button: int) -> int: ...
def get_cursor_pos(window) -> tuple[float, float]: ...
def set_cursor_pos(window, xpos: float, ypos: float) -> None: ...
def set_key_callback(window, cbfun) -> callable: ...
def set_mouse_button_callback(window, cbfun) -> callable: ...

Input Handling

Monitor and Display

Monitor enumeration, video mode queries, and display configuration for multi-monitor setups and fullscreen applications.

def get_monitors() -> list: ...
def get_primary_monitor() -> ctypes.POINTER: ...
def get_monitor_name(monitor) -> bytes: ...
def get_video_modes(monitor) -> list: ...
def get_video_mode(monitor) -> object: ...
def set_gamma(monitor, gamma: float) -> None: ...

Monitor and Display

OpenGL Context

OpenGL context creation, management, and OpenGL function loading for hardware-accelerated graphics rendering.

def make_context_current(window) -> None: ...
def get_current_context() -> ctypes.POINTER: ...
def swap_buffers(window) -> None: ...
def swap_interval(interval: int) -> None: ...
def extension_supported(extension: str) -> int: ...
def get_proc_address(procname: str) -> ctypes.c_void_p: ...

OpenGL Context

Vulkan Support

Vulkan surface creation and instance management for modern low-level graphics programming.

def vulkan_supported() -> bool: ...
def get_required_instance_extensions() -> list[str]: ...
def create_window_surface(instance, window, allocator, surface) -> int: ...
def get_physical_device_presentation_support(instance, device, queuefamily: int) -> int: ...
def get_instance_proc_address(instance, procname: str) -> ctypes.c_void_p: ...

Vulkan Support

Types

Core Types

class GLFWError(UserWarning):
    """Exception class for GLFW errors."""
    def __init__(self, message: str, error_code: int = None): ...
    error_code: int

Window and Monitor Handles

# Opaque handle types (ctypes.POINTER objects)
GLFWwindow = ctypes.POINTER  # Window handle
GLFWmonitor = ctypes.POINTER  # Monitor handle  
GLFWcursor = ctypes.POINTER  # Cursor handle

Data Structures

# Video mode information
GLFWvidmode = namedtuple('GLFWvidmode', ['size', 'bits', 'refresh_rate'])
Size = namedtuple('Size', ['width', 'height'])
Bits = namedtuple('Bits', ['red', 'green', 'blue'])

# Gamma ramp data
GLFWgammaramp = namedtuple('GLFWgammaramp', ['red', 'green', 'blue'])

# Image data (for icons and cursors)
GLFWimage = namedtuple('GLFWimage', ['width', 'height', 'pixels'])

# Gamepad state
GLFWgamepadstate = namedtuple('GLFWgamepadstate', ['buttons', 'axes'])

Constants

pyGLFW provides 480+ constants for keys, mouse buttons, window hints, and more:

# Version constants
VERSION_MAJOR: int = 3
VERSION_MINOR: int = 4
VERSION_REVISION: int = 0

# Boolean values
TRUE: int = 1
FALSE: int = 0

# Key actions
RELEASE: int = 0
PRESS: int = 1
REPEAT: int = 2

# Example key constants (100+ available)
KEY_SPACE: int = 32
KEY_A: int = 65
KEY_ESCAPE: int = 256
KEY_ENTER: int = 257

# Mouse button constants
MOUSE_BUTTON_LEFT: int = 0
MOUSE_BUTTON_RIGHT: int = 1
MOUSE_BUTTON_MIDDLE: int = 2

# Window hints and attributes
FOCUSED: int = 0x00020001
RESIZABLE: int = 0x00020003
VISIBLE: int = 0x00020004

Note: See individual capability documentation for complete constant listings by category.