pixo 0.1.0

data/ext/pixo/ext/glfw/docs/compat.dox

@@ -0,0 +1,224 @@
+/*!
+
+@page compat_guide Standards conformance
+
+@tableofcontents
+
+This guide describes the various API extensions used by this version of GLFW.
+It lists what are essentially implementation details, but which are nonetheless
+vital knowledge for developers intending to deploy their applications on a wide
+range of machines.
+
+The information in this guide is not a part of GLFW API, but merely
+preconditions for some parts of the library to function on a given machine.  Any
+part of this information may change in future versions of GLFW and that will not
+be considered a breaking API change.
+
+
+@section compat_x11 X11 extensions, protocols and IPC standards
+
+As GLFW uses Xlib directly, without any intervening toolkit
+library, it has sole responsibility for interacting well with the many and
+varied window managers in use on Unix-like systems.  In order for applications
+and window managers to work well together, a number of standards and
+conventions have been developed that regulate behavior outside the scope of the
+X11 API; most importantly the
+[Inter-Client Communication Conventions Manual](http://www.tronche.com/gui/x/icccm/)
+(ICCCM) and
+[Extended Window Manager Hints](http://standards.freedesktop.org/wm-spec/wm-spec-latest.html)
+(EWMH) standards.
+
+GLFW uses the `_MOTIF_WM_HINTS` window property to support borderless windows.
+If the running window manager does not support this property, the
+`GLFW_DECORATED` hint will have no effect.
+
+GLFW uses the ICCCM `WM_DELETE_WINDOW` protocol to intercept the user
+attempting to close the GLFW window.  If the running window manager does not
+support this protocol, the close callback will never be called.
+
+GLFW uses the EWMH `_NET_WM_PING` protocol, allowing the window manager notify
+the user when the application has stopped responding, i.e. when it has ceased to
+process events.  If the running window manager does not support this protocol,
+the user will not be notified if the application locks up.
+
+GLFW uses the EWMH `_NET_WM_STATE_FULLSCREEN` window state to tell the window
+manager to make the GLFW window full screen.  If the running window manager does
+not support this state, full screen windows may not work properly.  GLFW has
+a fallback code path in case this state is unavailable, but every window manager
+behaves slightly differently in this regard.
+
+GLFW uses the EWMH `_NET_WM_BYPASS_COMPOSITOR` window property to tell a
+compositing window manager to un-redirect full screen GLFW windows.  If the
+running window manager uses compositing but does not support this property then
+additional copying may be performed for each buffer swap of full screen windows.
+
+GLFW uses the
+[clipboard manager protocol](http://www.freedesktop.org/wiki/ClipboardManager/)
+to push a clipboard string (i.e. selection) owned by a GLFW window about to be
+destroyed to the clipboard manager.  If there is no running clipboard manager,
+the clipboard string will be unavailable once the window has been destroyed.
+
+GLFW uses the
+[X drag-and-drop protocol](http://www.freedesktop.org/wiki/Specifications/XDND/)
+to provide file drop events.  If the application originating the drag does not
+support this protocol, drag and drop will not work.
+
+GLFW uses the XRandR 1.3 extension to provide multi-monitor support.  If the
+running X server does not support this version of this extension, multi-monitor
+support will not function and only a single, desktop-spanning monitor will be
+reported.
+
+GLFW uses the XRandR 1.3 and Xf86vidmode extensions to provide gamma ramp
+support.  If the running X server does not support either or both of these
+extensions, gamma ramp support will not function.
+
+GLFW uses the Xkb extension and detectable auto-repeat to provide keyboard
+input.  If the running X server does not support this extension, a non-Xkb
+fallback path is used.
+
+
+@section compat_glx GLX extensions
+
+The GLX API is the default API used to create OpenGL contexts on Unix-like
+systems using the X Window System.
+
+GLFW uses the GLX 1.3 `GLXFBConfig` functions to enumerate and select framebuffer pixel
+formats.  If GLX 1.3 is not supported, @ref glfwInit will fail.
+
+GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
+`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization
+(or _vsync_), in that order of preference.  Where none of these extension are
+available, calling @ref glfwSwapInterval will have no effect.
+
+GLFW uses the `GLX_ARB_multisample` extension to create contexts with
+multisampling anti-aliasing.  Where this extension is unavailable, the
+`GLFW_SAMPLES` hint will have no effect.
+
+GLFW uses the `GLX_ARB_create_context` extension when available, even when
+creating OpenGL contexts of version 2.1 and below.  Where this extension is
+unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
+hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
+will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
+`GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref
+glfwCreateWindow to fail.
+
+GLFW uses the `GLX_ARB_create_context_profile` extension to provide support for
+context profiles.  Where this extension is unavailable, setting the
+`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE`, or setting
+`GLFW_CLIENT_API` to anything but `GLFW_OPENGL_API` or `GLFW_NO_API` will cause
+@ref glfwCreateWindow to fail.
+
+GLFW uses the `GLX_ARB_context_flush_control` extension to provide control over
+whether a context is flushed when it is released (made non-current).  Where this
+extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
+effect and the context will always be flushed when released.
+
+GLFW uses the `GLX_ARB_framebuffer_sRGB` and `GLX_EXT_framebuffer_sRGB`
+extensions to provide support for sRGB framebuffers.  Where both of these
+extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.
+
+
+@section compat_wgl WGL extensions
+
+The WGL API is used to create OpenGL contexts on Microsoft Windows and other
+implementations of the Win32 API, such as Wine.
+
+GLFW uses either the `WGL_EXT_extension_string` or the
+`WGL_ARB_extension_string` extension to check for the presence of all other WGL
+extensions listed below.  If both are available, the EXT one is preferred.  If
+neither is available, no other extensions are used and many GLFW features
+related to context creation will have no effect or cause errors when used.
+
+GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
+synchronization (or _vsync_).  Where this extension is unavailable, calling @ref
+glfwSwapInterval will have no effect.
+
+GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to
+create contexts with multisampling anti-aliasing.  Where these extensions are
+unavailable, the `GLFW_SAMPLES` hint will have no effect.
+
+GLFW uses the `WGL_ARB_create_context` extension when available, even when
+creating OpenGL contexts of version 2.1 and below.  Where this extension is
+unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
+hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
+will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
+`GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref
+glfwCreateWindow to fail.
+
+GLFW uses the `WGL_ARB_create_context_profile` extension to provide support for
+context profiles.  Where this extension is unavailable, setting the
+`GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE` will cause
+@ref glfwCreateWindow to fail.
+
+GLFW uses the `WGL_ARB_context_flush_control` extension to provide control over
+whether a context is flushed when it is released (made non-current).  Where this
+extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
+effect and the context will always be flushed when released.
+
+GLFW uses the `WGL_ARB_framebuffer_sRGB` and `WGL_EXT_framebuffer_sRGB`
+extensions to provide support for sRGB framebuffers.  Where both of these
+extension are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.
+
+
+@section compat_osx OpenGL 3.2 and later on OS X
+
+Support for OpenGL 3.2 and above was introduced with OS X 10.7 and even then
+only forward-compatible, core profile contexts are supported.  Support for
+OpenGL 4.1 was introduced with OS X 10.9, also limited to forward-compatible,
+core profile contexts.  There is also still no mechanism for requesting debug
+contexts.  Versions of Mac OS X earlier than 10.7 support at most OpenGL
+version 2.1.
+
+Because of this, on OS X 10.7 and later, the `GLFW_CONTEXT_VERSION_MAJOR` and
+`GLFW_CONTEXT_VERSION_MINOR` hints will cause @ref glfwCreateWindow to fail if
+given version 3.0 or 3.1, the `GLFW_OPENGL_FORWARD_COMPAT` hint must be set to
+`GLFW_TRUE` and the `GLFW_OPENGL_PROFILE` hint must be set to
+`GLFW_OPENGL_CORE_PROFILE` when creating OpenGL 3.2 and later contexts and the
+`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.
+
+Also, on Mac OS X 10.6 and below, the `GLFW_CONTEXT_VERSION_MAJOR` and
+`GLFW_CONTEXT_VERSION_MINOR` hints will fail if given a version above 2.1,
+setting the `GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT` hints to
+a non-default value will cause @ref glfwCreateWindow to fail and the
+`GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.
+
+
+@section compat_vulkan Vulkan loader and API
+
+GLFW uses the standard system-wide Vulkan loader to access the Vulkan API.
+This should be installed by graphics drivers and Vulkan SDKs.  If this is not
+available, @ref glfwVulkanSupported will return `GLFW_FALSE` and all other
+Vulkan-related functions will fail with an @ref GLFW_API_UNAVAILABLE error.
+
+
+@section compat_wsi Vulkan WSI extensions
+
+The Vulkan WSI extensions are used to create Vulkan surfaces for GLFW windows on
+all supported platforms.
+
+GLFW uses the `VK_KHR_surface` and `VK_KHR_win32_surface` extensions to create
+surfaces on Microsoft Windows.  If any of these extensions are not available,
+@ref glfwGetRequiredInstanceExtensions will return an empty list and window
+surface creation will fail.
+
+GLFW uses the `VK_KHR_surface` and either the `VK_KHR_xlib_surface` or
+`VK_KHR_xcb_surface` extensions to create surfaces on X11.  If `VK_KHR_surface`
+or both `VK_KHR_xlib_surface` and `VK_KHR_xcb_surface` are not available, @ref
+glfwGetRequiredInstanceExtensions will return an empty list and window surface
+creation will fail.
+
+GLFW uses the `VK_KHR_surface` and `VK_KHR_wayland_surface` extensions to create
+surfaces on Wayland.  If any of these extensions are not available, @ref
+glfwGetRequiredInstanceExtensions will return an empty list and window surface
+creation will fail.
+
+GLFW uses the `VK_KHR_surface` and `VK_KHR_mir_surface` extensions to create
+surfaces on Mir.  If any of these extensions are not available, @ref
+glfwGetRequiredInstanceExtensions will return an empty list and window surface
+creation will fail.
+
+GLFW does not support any extensions for window surface creation on OS X,
+meaning@ref glfwGetRequiredInstanceExtensions will return an empty list and
+window surface creation will fail.
+
+*/

data/ext/pixo/ext/glfw/docs/compile.dox

@@ -0,0 +1,284 @@
+/*!
+
+@page compile_guide Compiling GLFW
+
+@tableofcontents
+
+This is about compiling the GLFW library itself.  For information on how to
+build applications that use GLFW, see @ref build_guide.
+
+
+@section compile_cmake Using CMake
+
+GLFW uses [CMake](http://www.cmake.org/) to generate project files or makefiles
+for a particular development environment.  If you are on a Unix-like system such
+as Linux or FreeBSD or have a package system like Fink, MacPorts, Cygwin or
+Homebrew, you can simply install its CMake package.  If not, you can download
+installers for Windows and OS X from the [CMake website](http://www.cmake.org/).
+
+@note CMake only generates project files or makefiles.  It does not compile the
+actual GLFW library.  To compile GLFW, first generate these files for your
+chosen development environment and then use them to compile the actual GLFW
+library.
+
+
+@subsection compile_deps Dependencies
+
+Once you have installed CMake, make sure that all other dependencies are
+available.  On some platforms, GLFW needs a few additional packages to be
+installed.  See the section for your chosen platform and development environment
+below.
+
+
+@subsubsection compile_deps_msvc Dependencies for Visual C++ on Windows
+
+The Microsoft Platform SDK that is installed along with Visual C++ already
+contains all the necessary headers, link libraries and tools except for CMake.
+Move on to @ref compile_generate.
+
+
+@subsubsection compile_deps_mingw Dependencies for MinGW or MinGW-w64 on Windows
+
+Both the MinGW and the MinGW-w64 packages already contain all the necessary
+headers, link libraries and tools except for CMake.  Move on to @ref
+compile_generate.
+
+
+@subsubsection compile_deps_mingw_cross Dependencies for MinGW or MinGW-w64 cross-compilation
+
+Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages.  For
+example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages
+for 32- and 64-bit version of MinGW-w64, while Debian GNU/Linux and derivatives
+like Ubuntu have the `mingw-w64` package for both.
+
+GLFW has CMake toolchain files in the `CMake/` directory that allow for easy
+cross-compilation of Windows binaries.  To use these files you need to add a
+special parameter when generating the project files or makefiles:
+
+@code{.sh}
+cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> .
+@endcode
+
+The exact toolchain file to use depends on the prefix used by the MinGW or
+MinGW-w64 binaries on your system.  You can usually see this in the /usr
+directory.  For example, both the Debian/Ubuntu and Cygwin MinGW-w64 packages
+have `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct
+invocation would be:
+
+@code{.sh}
+cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake .
+@endcode
+
+For more details see the article
+[CMake Cross Compiling](http://www.paraview.org/Wiki/CMake_Cross_Compiling) on
+the CMake wiki.
+
+Once you have this set up, move on to @ref compile_generate.
+
+
+@subsubsection compile_deps_xcode Dependencies for Xcode on OS X
+
+Xcode comes with all necessary tools except for CMake.  The required headers
+and libraries are included in the core OS X frameworks.  Xcode can be downloaded
+from the Mac App Store or from the ADC Member Center.
+
+Once you have Xcode installed, move on to @ref compile_generate.
+
+
+@subsubsection compile_deps_x11 Dependencies for Linux and X11
+
+To compile GLFW for X11, you need to have the X11 packages installed, as well as
+the basic development tools like GCC and make.  For example, on Ubuntu and other
+distributions based on Debian GNU/Linux, you need to install the `xorg-dev`
+package, which pulls in all X.org header packages.
+
+Once you have installed the necessary packages, move on to @ref
+compile_generate.
+
+
+@subsection compile_generate Generating build files with CMake
+
+Once you have all necessary dependencies it is time to generate the project
+files or makefiles for your development environment.  CMake needs to know two
+paths for this: the path to the _root_ directory of the GLFW source tree (i.e.
+_not_ the `src` subdirectory) and the target path for the generated files and
+compiled binaries.  If these are the same, it is called an in-tree build,
+otherwise it is called an out-of-tree build.
+
+One of several advantages of out-of-tree builds is that you can generate files
+and compile for different development environments using a single source tree.
+
+@note This section is about generating the project files or makefiles necessary
+to compile the GLFW library, not about compiling the actual library.
+
+
+@subsubsection compile_generate_cli Generating files with the CMake command-line tool
+
+To make an in-tree build, enter the _root_ directory of the GLFW source tree
+(i.e. _not_ the `src` subdirectory) and run CMake.  The current directory is
+used as target path, while the path provided as an argument is used to find the
+source tree.
+
+@code{.sh}
+cd <glfw-root-dir>
+cmake .
+@endcode
+
+To make an out-of-tree build, make a directory outside of the source tree, enter
+it and run CMake with the (relative or absolute) path to the root of the source
+tree as an argument.
+
+@code{.sh}
+mkdir glfw-build
+cd glfw-build
+cmake <glfw-root-dir>
+@endcode
+
+Once you have generated the project files or makefiles for your chosen
+development environment, move on to @ref compile_compile.
+
+
+@subsubsection compile_generate_gui Generating files with the CMake GUI
+
+If you are using the GUI version, choose the root of the GLFW source tree as
+source location and the same directory or another, empty directory as the
+destination for binaries.  Choose _Configure_, change any options you wish to,
+_Configure_ again to let the changes take effect and then _Generate_.
+
+Once you have generated the project files or makefiles for your chosen
+development environment, move on to @ref compile_compile.
+
+
+@subsection compile_compile Compiling the library
+
+You should now have all required dependencies and the project files or makefiles
+necessary to compile GLFW.  Go ahead and compile the actual GLFW library with
+these files, as you would with any other project.
+
+Once the GLFW library is compiled, you are ready to build your applications,
+linking it to the GLFW library.  See @ref build_guide for more information.
+
+
+@subsection compile_options CMake options
+
+The CMake files for GLFW provide a number of options, although not all are
+available on all supported platforms.  Some of these are de facto standards
+among projects using CMake and so have no `GLFW_` prefix.
+
+If you are using the GUI version of CMake, these are listed and can be changed
+from there.  If you are using the command-line version of CMake you can use the
+`ccmake` ncurses GUI to set options.  Some package systems like Ubuntu and other
+distributions based on Debian GNU/Linux have this tool in a separate
+`cmake-curses-gui` package.
+
+Finally, if you don't want to use any GUI, you can set options from the `cmake`
+command-line with the `-D` flag.
+
+@code{.sh}
+cmake -DBUILD_SHARED_LIBS=ON .
+@endcode
+
+
+@subsubsection compile_options_shared Shared CMake options
+
+`BUILD_SHARED_LIBS` determines whether GLFW is built as a static
+library or as a DLL / shared library / dynamic library.
+
+`LIB_SUFFIX` affects where the GLFW shared /dynamic library is installed.  If it
+is empty, it is installed to `${CMAKE_INSTALL_PREFIX}/lib`.  If it is set to
+`64`, it is installed to `${CMAKE_INSTALL_PREFIX}/lib64`.
+
+`GLFW_BUILD_EXAMPLES` determines whether the GLFW examples are built
+along with the library.
+
+`GLFW_BUILD_TESTS` determines whether the GLFW test programs are
+built along with the library.
+
+`GLFW_BUILD_DOCS` determines whether the GLFW documentation is built along with
+the library.
+
+`GLFW_VULKAN_STATIC` determines whether to use the Vulkan loader linked
+statically into the application.
+
+
+@subsubsection compile_options_osx OS X specific CMake options
+
+`GLFW_USE_CHDIR` determines whether `glfwInit` changes the current
+directory of bundled applications to the `Contents/Resources` directory.
+
+`GLFW_USE_MENUBAR` determines whether the first call to
+`glfwCreateWindow` sets up a minimal menu bar.
+
+`GLFW_USE_RETINA` determines whether windows will use the full resolution of
+Retina displays.
+
+
+@subsubsection compile_options_win32 Windows specific CMake options
+
+`USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version or the
+static library version of the Visual C++ runtime library.  If set to `ON`, the
+DLL version of the Visual C++ library is used.
+
+`GLFW_USE_HYBRID_HPG` determines whether to export the `NvOptimusEnablement` and
+`AmdPowerXpressRequestHighPerformance` symbols, which force the use of the
+high-performance GPU on Nvidia Optimus and AMD PowerXpress systems.  These symbols
+need to be exported by the EXE to be detected by the driver, so the override
+will not work if GLFW is built as a DLL.
+
+
+@section compile_manual Compiling GLFW manually
+
+If you wish to compile GLFW without its CMake build environment then you will
+have to do at least some of the platform detection yourself.  GLFW needs
+a configuration macro to be defined in order to know what window system it's
+being compiled for and also has optional, platform-specific ones for various
+features.
+
+When building with CMake, the `glfw_config.h` configuration header is generated
+based on the current platform and CMake options.  The GLFW CMake environment
+defines `_GLFW_USE_CONFIG_H`, which causes this header to be included by
+`internal.h`.  Without this macro, GLFW will expect the necessary configuration
+macros to be defined on the command-line.
+
+The window creation API is used to create windows, handle input, monitors, gamma
+ramps and clipboard.  The options are:
+
+ - `_GLFW_COCOA` to use the Cocoa frameworks
+ - `_GLFW_WIN32` to use the Win32 API
+ - `_GLFW_X11` to use the X Window System
+ - `_GLFW_WAYLAND` to use the Wayland API (experimental and incomplete)
+ - `_GLFW_MIR` to use the Mir API (experimental and incomplete)
+
+If you are building GLFW as a shared library / dynamic library / DLL then you
+must also define `_GLFW_BUILD_DLL`.  Otherwise, you must not define it.
+
+If you are linking the Vulkan loader statically into your application then you
+must also define `_GLFW_VULKAN_STATIC`.  Otherwise, GLFW will attempt to use the
+external version.
+
+For the EGL context creation API, the following options are available:
+
+ - `_GLFW_USE_EGLPLATFORM_H` to use `EGL/eglplatform.h` for native handle
+   definitions (fallback)
+
+If you are using the X11 window creation API, support for the following X11
+extensions can be enabled:
+
+ - `_GLFW_HAS_XF86VM` to use Xxf86vm as a fallback when RandR gamma is broken
+ (recommended)
+
+If you are using the Cocoa window creation API, the following options are
+available:
+
+ - `_GLFW_USE_CHDIR` to `chdir` to the `Resources` subdirectory of the
+   application bundle during @ref glfwInit (recommended)
+ - `_GLFW_USE_MENUBAR` to create and populate the menu bar when the first window
+   is created (recommended)
+ - `_GLFW_USE_RETINA` to have windows use the full resolution of Retina displays
+   (recommended)
+
+@note None of the @ref build_macros may be defined during the compilation of
+GLFW.  If you define any of these in your build files, make sure they are not
+applied to the GLFW sources.
+
+*/