pixo 0.1.0

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

@@ -0,0 +1,116 @@
+/*!
+
+@page internals_guide Internal structure
+
+@tableofcontents
+
+There are several interfaces inside GLFW.  Each interface has its own area of
+responsibility and its own naming conventions.
+
+
+@section internals_public Public interface
+
+The most well-known is the public interface, described in the glfw3.h header
+file.  This is implemented in source files shared by all platforms and these
+files contain no platform-specific code.  This code usually ends up calling the
+platform and internal interfaces to do the actual work.
+
+The public interface uses the OpenGL naming conventions except with GLFW and
+glfw instead of GL and gl.  For struct members, where OpenGL sets no precedent,
+it use headless camel case.
+
+Examples: @ref glfwCreateWindow, @ref GLFWwindow, @ref GLFWvidmode.redBits,
+`GLFW_RED_BITS`
+
+
+@section internals_native Native interface
+
+The [native interface](@ref native) is a small set of publicly available
+but platform-specific functions, described in the glfw3native.h header file and
+used to gain access to the underlying window, context and (on some platforms)
+display handles used by the platform interface.
+
+The function names of the native interface are similar to those of the public
+interface, but embeds the name of the interface that the returned handle is
+from.
+
+Examples: @ref glfwGetX11Window, @ref glfwGetWGLContext
+
+
+@section internals_internal Internal interface
+
+The internal interface consists of utility functions used by all other
+interfaces.  It is shared code implemented in the same shared source files as
+the public and event interfaces.  The internal interface is described in the
+internal.h header file.
+
+The internal interface is in charge of GLFW's global data, which it stores in
+a `_GLFWlibrary` struct named `_glfw`.
+
+The internal interface uses the same style as the public interface, except all
+global names have a leading underscore.
+
+Examples: @ref _glfwIsValidContextConfig, @ref _GLFWwindow, `_glfw.currentRamp`
+
+
+@section internals_platform Platform interface
+
+The platform interface implements all platform-specific operations as a service
+to the public interface.  This includes event processing.  The platform
+interface is never directly called by application code and never directly calls
+application-provided callbacks.  It is also prohibited from modifying the
+platform-independent part of the internal structs.  Instead, it calls the event
+interface when events interesting to GLFW are received.
+
+The platform interface mirrors those parts of the public interface that needs to
+perform platform-specific operations on some or all platforms.  The are also
+named the same except that the glfw function prefix is replaced by
+_glfwPlatform.
+
+Examples: @ref _glfwPlatformCreateWindow
+
+The platform interface also defines structs that contain platform-specific
+global and per-object state.  Their names mirror those of the internal
+interface, except that an interface-specific suffix is added.
+
+Examples: `_GLFWwindowX11`, `_GLFWcontextWGL`
+
+These structs are incorporated as members into the internal interface structs
+using special macros that name them after the specific interface used.  This
+prevents shared code from accidentally using these members.
+
+Examples: `window.win32.handle`, `_glfw.x11.display`
+
+
+@section internals_event Event interface
+
+The event interface is implemented in the same shared source files as the public
+interface and is responsible for delivering the events it receives to the
+application, either via callbacks, via window state changes or both.
+
+The function names of the event interface use a `_glfwInput` prefix and the
+ObjectEvent pattern.
+
+Examples: @ref _glfwInputWindowFocus, @ref _glfwInputCursorMotion
+
+
+@section internals_static Static functions
+
+Static functions may be used by any interface and have no prefixes or suffixes.
+These use headless camel case.
+
+Examples: `clearScrollOffsets`
+
+
+@section internals_config Configuration macros
+
+GLFW uses a number of configuration macros to select at compile time which
+interfaces and code paths to use.  They are defined in the glfw_config.h header file,
+which is generated from the `glfw_config.h.in` file by CMake.
+
+Configuration macros the same style as tokens in the public interface, except
+with a leading underscore.
+
+Examples: `_GLFW_HAS_XF86VM` 
+
+*/

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

@@ -0,0 +1,372 @@
+/*! 
+
+@page intro_guide Introduction to the API
+ 
+@tableofcontents
+
+This guide introduces the basic concepts of GLFW and describes initialization,
+error handling and API guarantees and limitations.  For a broad but shallow
+tutorial, see @ref quick_guide instead.  For details on a specific function in
+this category, see the @ref init.
+
+There are also guides for the other areas of GLFW.
+
+ - @ref window_guide
+ - @ref context_guide
+ - @ref vulkan_guide
+ - @ref monitor_guide
+ - @ref input_guide
+
+
+@section intro_init Initialization and termination
+
+Before most GLFW functions may be called, the library must be initialized.
+This initialization checks what features are available on the machine,
+enumerates monitors and joysticks, initializes the timer and performs any
+required platform-specific initialization.
+
+Only the following functions may be called before the library has been
+successfully initialized, and only from the main thread.
+
+ - @ref glfwGetVersion
+ - @ref glfwGetVersionString
+ - @ref glfwSetErrorCallback
+ - @ref glfwInit
+ - @ref glfwTerminate
+
+Calling any other function before successful initialization will cause a @ref
+GLFW_NOT_INITIALIZED error.
+
+
+@subsection intro_init_init Initializing GLFW
+
+The library is initialized with @ref glfwInit, which returns `GLFW_FALSE` if an
+error occurred.
+
+@code
+if (!glfwInit())
+{
+    // Handle initialization failure
+}
+@endcode
+
+If any part of initialization fails, any parts that succeeded are terminated as
+if @ref glfwTerminate had been called.  The library only needs to be initialized
+once and additional calls to an already initialized library will simply return
+`GLFW_TRUE` immediately.
+
+Once the library has been successfully initialized, it should be terminated
+before the application exits.  Modern systems are very good at freeing resources
+allocated by programs that simply exit, but GLFW sometimes has to change global
+system settings and these might not be restored without termination.
+
+
+@subsection intro_init_terminate Terminating GLFW
+
+Before your application exits, you should terminate the GLFW library if it has
+been initialized.  This is done with @ref glfwTerminate.
+
+@code
+glfwTerminate();
+@endcode
+
+This will destroy any remaining window, monitor and cursor objects, restore any
+modified gamma ramps, re-enable the screensaver if it had been disabled and free
+any other resources allocated by GLFW.
+
+Once the library is terminated, it is as if it had never been initialized and
+you will need to initialize it again before being able to use GLFW.  If the
+library was not initialized or had already been terminated, it return
+immediately. 
+
+
+@section error_handling Error handling
+
+Some GLFW functions have return values that indicate an error, but this is often
+not very helpful when trying to figure out _why_ the error occurred.  Some
+functions also return otherwise valid values on error.  Finally, far from all
+GLFW functions have return values.
+
+This is where the error callback comes in.  This callback is called whenever an
+error occurs.  It is set with @ref glfwSetErrorCallback, a function that may be
+called regardless of whether GLFW is initialized.
+
+@code
+glfwSetErrorCallback(error_callback);
+@endcode
+
+The error callback receives a human-readable description of the error and (when
+possible) its cause.  The description encoded as UTF-8.  The callback is also
+provided with an [error code](@ref errors). 
+
+@code
+void error_callback(int error, const char* description)
+{
+    puts(description);
+}
+@endcode
+
+The error code indicates the general category of the error.  Some error codes,
+such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like
+@ref GLFW_PLATFORM_ERROR are used for many different errors.
+
+The description string is only valid until the error callback returns, as it may
+have been generated specifically for that error.  This lets GLFW provide much
+more specific error descriptions but means you must make a copy if you want to
+keep the description string.
+
+@note Relying on erroneous behavior is not forward compatible.  In other words,
+do not rely on a currently invalid call to generate a specific error, as that
+same call may in future versions generate a different error or become valid.
+
+
+@section coordinate_systems Coordinate systems
+
+GLFW has two primary coordinate systems: the _virtual screen_ and the window
+_client area_ or _content area_.  Both use the same unit: _virtual screen
+coordinates_, or just _screen coordinates_, which don't necessarily correspond
+to pixels.
+
+<img src="spaces.svg" width="90%" />
+
+Both the virtual screen and the client area coordinate systems have the X-axis
+pointing to the right and the Y-axis pointing down.
+
+Window and monitor positions are specified as the position of the upper-left
+corners of their content areas relative to the virtual screen, while cursor
+positions are specified relative to a window's client area.
+
+Because the origin of the window's client area coordinate system is also the
+point from which the window position is specified, you can translate client area
+coordinates to the virtual screen by adding the window position.  The window
+frame, when present, extends out from the client area but does not affect the
+window position.
+
+Almost all positions and sizes in GLFW are measured in screen coordinates
+relative to one of the two origins above.  This includes cursor positions,
+window positions and sizes, window frame sizes, monitor positions and video mode
+resolutions.
+
+Two exceptions are the [monitor physical size](@ref monitor_size), which is
+measured in millimetres, and [framebuffer size](@ref window_fbsize), which is
+measured in pixels.
+
+Pixels and screen coordinates may map 1:1 on your machine, but they won't on
+every other machine, for example on a Mac with a Retina display.  The ratio
+between screen coordinates and pixels may also change at run-time depending on
+which monitor the window is currently considered to be on.
+
+
+@section guarantees_limitations Guarantees and limitations
+
+This section describes the conditions under which GLFW can be expected to
+function, barring bugs in the operating system or drivers.  Use of GLFW outside
+of these limits may work on some platforms, or on some machines, or some of the
+time, or on some versions of GLFW, but it may break at any time and this will
+not be considered a bug.
+
+
+@subsection lifetime Pointer lifetimes
+
+GLFW will never free any pointer you provide to it and you must never free any
+pointer it provides to you.
+
+Many GLFW functions return pointers to dynamically allocated structures, strings
+or arrays, and some callbacks are provided with strings or arrays.  These are
+always managed by GLFW and should never be freed by the application.  The
+lifetime of these pointers is documented for each GLFW function and callback.
+If you need to keep this data, you must copy it before its lifetime expires.
+
+Many GLFW functions accept pointers to structures or strings allocated by the
+application.  These are never freed by GLFW and are always the responsibility of
+the application.  If GLFW needs to keep the data in these structures or strings,
+it is copied before the function returns.
+
+Pointer lifetimes are guaranteed not to be shortened in future minor or patch
+releases.
+
+
+@subsection reentrancy Reentrancy
+
+GLFW event processing and object creation and destruction are not reentrant.
+This means that the following functions must not be called from any callback
+function:
+
+ - @ref glfwCreateWindow
+ - @ref glfwDestroyWindow
+ - @ref glfwCreateCursor
+ - @ref glfwCreateStandardCursor
+ - @ref glfwDestroyCursor
+ - @ref glfwPollEvents
+ - @ref glfwWaitEvents
+ - @ref glfwWaitEventsTimeout
+ - @ref glfwTerminate
+
+These functions may be made reentrant in future minor or patch releases, but
+functions not on this list will not be made non-reentrant.
+
+
+@subsection thread_safety Thread safety
+
+Most GLFW functions must only be called from the main thread, but some may be
+called from any thread.  However, no GLFW function may be called from any thread
+but the main thread until GLFW has been successfully initialized, including
+functions that may called before initialization.
+
+The reference documentation for every GLFW function states whether it is limited
+to the main thread.                                                        
+
+Initialization and termination, event processing and the creation and
+destruction of windows, contexts and cursors are all limited to the main thread
+due to limitations of one or several platforms.
+
+Because event processing must be performed on the main thread, all callbacks
+except for the error callback will only be called on that thread.  The error
+callback may be called on any thread, as any GLFW function may generate errors.
+
+The posting of empty events may be done from any thread.  The window user
+pointer and close flag may also be accessed and modified from any thread, but
+this is not synchronized by GLFW.  The following window related functions may
+be called from any thread:
+
+ - @ref glfwPostEmptyEvent
+ - @ref glfwGetWindowUserPointer
+ - @ref glfwSetWindowUserPointer
+ - @ref glfwWindowShouldClose
+ - @ref glfwSetWindowShouldClose
+
+Rendering may be done on any thread.  The following context related functions
+may be called from any thread:
+
+ - @ref glfwMakeContextCurrent
+ - @ref glfwGetCurrentContext
+ - @ref glfwSwapBuffers
+ - @ref glfwSwapInterval
+ - @ref glfwExtensionSupported
+ - @ref glfwGetProcAddress
+
+The raw timer may be queried from any thread.  The following raw timer related
+functions may be called from any thread:
+
+ - @ref glfwGetTimerFrequency
+ - @ref glfwGetTimerValue
+
+The regular timer may be used from any thread, but the reading and writing of
+the timer offset is not synchronized by GLFW.  The following timer related
+functions may be called from any thread:
+
+ - @ref glfwGetTime
+ - @ref glfwSetTime
+
+Library version information may be queried from any thread.  The following
+version related functions may be called from any thread:
+
+ - @ref glfwGetVersion
+ - @ref glfwGetVersionString
+
+Vulkan objects may be created and information queried from any thread.  The
+following Vulkan related functions may be called from any thread:
+
+ - @ref glfwVulkanSupported
+ - @ref glfwGetRequiredInstanceExtensions
+ - @ref glfwGetInstanceProcAddress
+ - @ref glfwGetPhysicalDevicePresentationSupport
+ - @ref glfwCreateWindowSurface
+
+GLFW uses no synchronization objects internally except for thread-local storage
+to keep track of the current context for each thread.  Synchronization is left
+to the application.
+
+Functions that may currently be called from any thread will always remain so,
+but functions that are currently limited to the main thread may be updated to
+allow calls from any thread in future releases.
+
+
+@subsection compatibility Version compatibility
+
+GLFW guarantees source and binary backward compatibility with earlier minor
+versions of the API.  This means that you can drop in a newer version of the
+library and existing programs will continue to compile and existing binaries
+will continue to run.
+
+Once a function or constant has been added, the signature of that function or
+value of that constant will remain unchanged until the next major version of
+GLFW.  No compatibility of any kind is guaranteed between major versions.
+
+Undocumented behavior, i.e. behavior that is not described in the documentation,
+may change at any time until it is documented.
+
+If the reference documentation and the implementation differ, the reference
+documentation is correct and the implementation will be fixed in the next
+release.
+
+
+@subsection event_order Event order
+
+The order of arrival of related events is not guaranteed to be consistent
+across platforms.  The exception is synthetic key and mouse button release
+events, which are always delivered after the window defocus event.
+
+
+@section intro_version Version management
+
+GLFW provides mechanisms for identifying what version of GLFW your application
+was compiled against as well as what version it is currently running against.
+If you are loading GLFW dynamically (not just linking dynamically), you can use
+this to verify that the library binary is compatible with your application.
+
+
+@subsection intro_version_compile Compile-time version
+
+The compile-time version of GLFW is provided by the GLFW header with the
+`GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros.
+
+@code
+printf("Compiled against GLFW %i.%i.%i\n",
+       GLFW_VERSION_MAJOR,
+       GLFW_VERSION_MINOR,
+       GLFW_VERSION_REVISION);
+@endcode
+
+
+@subsection intro_version_runtime Run-time version
+
+The run-time version can be retrieved with @ref glfwGetVersion, a function that
+may be called regardless of whether GLFW is initialized.
+
+@code
+int major, minor, revision;
+glfwGetVersion(&major, &minor, &revision);
+
+printf("Running against GLFW %i.%i.%i\n", major, minor, revision);
+@endcode
+
+
+@subsection intro_version_string Version string
+
+GLFW 3 also provides a compile-time generated version string that describes the
+version, platform, compiler and any platform-specific compile-time options.
+This is primarily intended for submitting bug reports, to allow developers to
+see which code paths are enabled in a binary.
+
+The version string is returned by @ref glfwGetVersionString, a function that may
+be called regardless of whether GLFW is initialized.
+
+__Do not use the version string__ to parse the GLFW library version.  The @ref
+glfwGetVersion function already provides the version of the running library
+binary.
+
+The format of the string is as follows:
+ - The version of GLFW
+ - The name of the window system API
+ - The name of the context creation API
+ - Any additional options or APIs
+
+For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
+back ends, the version string may look something like this:
+
+@code
+3.0.0 Win32 WGL MinGW
+@endcode
+
+*/

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

@@ -0,0 +1,47 @@
+/*!
+
+@mainpage notitle
+
+@section main_intro Introduction
+
+GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and
+Vulkan application development.  It provides a simple, platform-independent API
+for creating windows, contexts and surfaces, reading input, handling events, etc.
+
+See @ref news_32 for release highlights or the
+[version history](http://www.glfw.org/changelog.html) for details.
+
+@ref quick_guide is a guide for users new to GLFW.  It takes you through how to
+write a small but complete program.
+
+There are guides for each section of the API:
+
+ - @ref intro_guide – initialization, error handling and high-level design
+ - @ref window_guide – creating and working with windows and framebuffers
+ - @ref context_guide – working with OpenGL and OpenGL ES contexts
+ - @ref vulkan_guide - working with Vulkan objects and extensions
+ - @ref monitor_guide – enumerating and working with monitors and video modes
+ - @ref input_guide – receiving events, polling and processing input
+
+Once you have written a program, see @ref compile_guide and @ref build_guide.
+
+The [reference documentation](modules.html) provides more detailed information
+about specific functions.
+
+@ref moving_guide explains what has changed and how to update existing code to
+use the new API.
+
+There is a section on @ref guarantees_limitations for pointer lifetimes,
+reentrancy, thread safety, event order and backward and forward compatibility.
+
+The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the
+design, implementation and use of GLFW.
+
+Finally, @ref compat_guide explains what APIs, standards and protocols GLFW uses
+and what happens when they are not present on a given machine.
+
+This documentation was generated with Doxygen.  The sources for it are available
+in both the [source distribution](http://www.glfw.org/download.html) and
+[GitHub repository](https://github.com/glfw/glfw).
+
+*/