ctypes Wrapper Generation
=========================

The following modules in pyglet are entirely (or mostly) generated from one or
more C header files:

* pyglet.gl.gl
* pyglet.gl.gl_compat
* pyglet.gl.agl
* pyglet.gl.glext_abi
* pyglet.gl.glext_nv
* pyglet.gl.glx
* pyglet.gl.glxext_abi
* pyglet.gl.glxext_nv
* pyglet.gl.wgl
* pyglet.gl.wglext_abi
* pyglet.gl.wglext_nv
* pyglet.window.xlib.xlib
* pyglet.window.xlib.xinerama

The wrapping framework is in ``tools/wraptypes``, and pyglet-specialised batch
scripts are ``tools/genwrappers.py`` (generates xlib wrappers) and
``tools/gengl.py`` (generates gl wrappers).

Generating GL wrappers (new version)
------------------------------------

The new ``gengl.py`` script only generates the following modules:

* ``gl.py``: OpenGL 4.6 core profile enums and functions. All deprecated
  enums and functions are not included.
* ``gl_compat.py``: OpenGL 4.6 compatibility profile with all enums and
  functions all the way back to OpenGL 1.0.

Running the script:

    # Fetch latest gl.xml from Khronos github and generate new modules
    python tools/gengl.py
    python tools/gengl.py --source url

    # Read the local gl.xml version
    python tools/gengl.py --source local

The old ``gengl.py`` script also handled agl, wgl and glx.
The section below is still present for historical reasons
and the old script is still around in the tools directory.

Generating GL wrappers (old version)
------------------------------------

This process needs to be followed when the wraptypes is updated, the header
files are updated (e.g., a new release of the operating system), or the GL
extensions are updated.  Each file can only be generated a a specific
platform.

Before beginning, remove the file ``tools/.gengl.cache`` if it exists.  This
merely caches header files so they don't need to be repeatedly downloaded (but
you'd prefer to use the most recent uncached copies if you're reading this,
presumably).

On Linux, generate ``pyglet.gl.gl``, ``pyglet.gl.glext_abi`` and
``pyglet.gl.glext_nv`` (the complete user-visible GL
package)::

    python tools/gengl.py gl glext_abi glext_nv

The header files for ``pyglet.gl.gl`` are located in
``/usr/include/GL``.  Ensure your Linux distribution has recent versions
of these files (unfortunately they do not seem to be accessible outside of a
distribution or OS).

The header files for ``pyglet.glext_abi`` and ``pyglet.glext_nv`` are
downloaded from http://www.opengl.org and http://developer.nvidia.com,
respectively.

On Linux still, generate ``pyglet.gl.glx``, ``pyglet.gl.glxext_abi`` and
``pyglet.gl.glxext_nv``::

    python tools/gengl.py glx glxext_abi glxext_nv

The header file for ``pyglet.gl.glx`` is in ``/usr/include/GL``, and
is expected to depend on X11 header files from ``/usr/include/X11``.
``glext_abi`` and ``glext_nv`` header files are downloaded from the above
websites.

On OS X, generate ``pyglet.gl.agl``::

    python tools/gengl.py agl

Watch a movie while you wait -- it uses virtually every header file on the
system.  Expect to see one syntax error in ``PictUtils.h`` line 67, it is
unimportant.

On Windows XP, generate ``pyglet.gl.wgl``, ``pyglet.gl.wglext_abi`` and
``pyglet.gl.wglext_nv``::

    python tools/gengl.py wgl wglext_abi wglext_nv

You do not need to have a development environment installed on Windows.
``pyglet.gl.wgl`` is generated from ``tools/wgl.h``, which is a hand-coded
header file containing the prototypes and constants for WGL and its
dependencies.  In a real development environment you would find these mostly
in ``WinGDI.h``, but wraptypes is not quite sophisticated enough to parse
Windows system headers (see below for what needs implementing).  It is
extremely unlikely this header will ever need to change (excepting a bug fix).

The headers for ``pyglet.gl.wglext_abi`` and ``pyglet.gl.wglext_nv`` are
downloaded from the same websites as for GL and GLX.

Generated GL wrappers
---------------------

Each generated file contains a pair of markers ``# BEGIN GENERATED CONTENT``
and ``# END GENERATED CONTENT`` which are searched for when replacing the
file.  If either marker is missing or corrupt, the file will not be modified.
This allows for custom content around the generated content.  Only ``glx.py``
makes use of this, to include some additional enumerators that are not
generated by default.

If a generating process is interrupted (either you get sick of it, or it
crashes), it will leave a partially-complete file written, which will not
include both markers.  It is up to you to restore the file or otherwise
reinsert the markers.

Generating Xlib wrappers
------------------------

On Linux with the Xinerama extension installed (doesn't have to be in use,
just available), run::

    python tools/genwrappers.py

This generates ``pyglet.window.xlib.xlib`` and
``pyglet.window.xlib.xinerama``.

Note that this process, as well as the generated modules, depend on
``pyglet.gl.glx``.  So, you should always run this `after` the above GL
generation.


