README.rst
1pyGLFW
2======
3
4This module provides Python bindings for `GLFW <http://www.glfw.org/>`__
5(on GitHub: `glfw/glfw <http://github.com/glfw/glfw>`__). It is a
6``ctypes`` wrapper which keeps very close to the original GLFW API,
7except for:
8
9- function names use the pythonic ``words_with_underscores`` notation
10 instead of ``camelCase``
11- ``GLFW_`` and ``glfw`` prefixes have been removed, as their function
12 is replaced by the module namespace
13 (you can use ``from glfw.GLFW import *`` if you prefer the naming
14 convention used by the GLFW C API)
15- structs have been replaced with Python sequences and namedtuples
16- functions like ``glfwGetMonitors`` return a list instead of a pointer
17 and an object count
18- Gamma ramps use floats between 0.0 and 1.0 instead of unsigned shorts
19 (use ``glfw.NORMALIZE_GAMMA_RAMPS=False`` to disable this)
20- GLFW errors are reported as ``glfw.GLFWError`` warnings if no error
21 callback is set (use ``glfw.ERROR_REPORTING=False`` to disable this,
22 set it to 'warn' instead to issue warnings, set it to 'log' to log it
23 using the 'glfw' logger or set it to a dict to define the behavior for
24 specific error codes)
25- instead of a sequence for ``GLFWimage`` structs, PIL/pillow ``Image``
26 objects can be used
27
28Installation
29------------
30
31pyGLFW can be installed using pip:
32
33.. code:: sh
34
35 pip install glfw
36
37Windows
38~~~~~~~
39
40The GLFW shared library and Visual C++ runtime are included in the Python wheels.
41
42To use a different GLFW library, you can set ``PYGLFW_LIBRARY`` to its location.
43
44macOS
45~~~~~
46
47The GLFW shared library for 64-bit is included in the Python wheels for macOS.
48
49If you are using a 32-bit Python installation or otherwise cannot use the
50library downloaded with the wheel, you can build and install it yourself by
51`compiling GLFW from source <http://www.glfw.org/docs/latest/compile.html>`__
52(use ``-DBUILD_SHARED_LIBS=ON``).
53
54pyGLFW will search for the library in a list of search paths (including those
55in ``DYLD_LIBRARY_PATH``). If you want to use a specific library, you can set
56the ``PYGLFW_LIBRARY`` environment variable to its path.
57
58Linux
59~~~~~
60
61The GLFW shared library is included in the Python wheels for Linux.
62
63If you cannot use these on your system, you can install the GLFW shared
64library using a package management system (e.g. ``apt install libglfw3``
65on Debian or Ubuntu) or you can build and install it yourself by
66`compiling GLFW from source <http://www.glfw.org/docs/latest/compile.html>`__
67(use ``-DBUILD_SHARED_LIBS=ON``).
68
69pyGLFW will search for the library in a list of search paths (including those
70in ``LD_LIBRARY_PATH``). If you want to use a specific library, you can set
71the ``PYGLFW_LIBRARY`` environment variable to its path.
72
73Development Version
74~~~~~~~~~~~~~~~~~~~
75
76If you are using the development version of GLFW and would like to use wrappers
77for currently unreleased macros and functions, you can instead install:
78
79.. code:: sh
80
81 pip install glfw[preview]
82
83or set the ``PYGLFW_PREVIEW`` environment variable.
84
85Note, however, that there will be a slight delay between the development
86version of GLFW and the wrappers provided by this package.
87
88Example Code
89------------
90
91The example from the `GLFW
92documentation <http://www.glfw.org/documentation.html>`__ ported to
93pyGLFW:
94
95.. code:: python
96
97 import glfw
98
99 def main():
100 # Initialize the library
101 if not glfw.init():
102 return
103 # Create a windowed mode window and its OpenGL context
104 window = glfw.create_window(640, 480, "Hello World", None, None)
105 if not window:
106 glfw.terminate()
107 return
108
109 # Make the window's context current
110 glfw.make_context_current(window)
111
112 # Loop until the user closes the window
113 while not glfw.window_should_close(window):
114 # Render here, e.g. using pyOpenGL
115
116 # Swap front and back buffers
117 glfw.swap_buffers(window)
118
119 # Poll for and process events
120 glfw.poll_events()
121
122 glfw.terminate()
123
124 if __name__ == "__main__":
125 main()
126