Move includes to a separate directory

This is more conventional and directories named "include" are specially
understood by some tooling like clang-tidy.

1 files changed, 0 insertions, 1624 deletions

diff --git a/pugl/pugl.h b/pugl/pugl.h
deleted file mode 100644
index ad24c0d..0000000
--- a/pugl/pugl.h
+++ /dev/null
@@ -1,1624 +0,0 @@
-/*
-  Copyright 2012-2020 David Robillard <d@drobilla.net>
-
-  Permission to use, copy, modify, and/or distribute this software for any
-  purpose with or without fee is hereby granted, provided that the above
-  copyright notice and this permission notice appear in all copies.
-
-  THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-*/
-
-/**
-   @file pugl.h
-   @brief Pugl API.
-*/
-
-#ifndef PUGL_PUGL_H
-#define PUGL_PUGL_H
-
-#include <stdbool.h>
-#include <stddef.h>
-#include <stdint.h>
-
-#ifdef PUGL_SHARED
-#    ifdef _WIN32
-#        define PUGL_LIB_IMPORT __declspec(dllimport)
-#        define PUGL_LIB_EXPORT __declspec(dllexport)
-#    else
-#        define PUGL_LIB_IMPORT __attribute__((visibility("default")))
-#        define PUGL_LIB_EXPORT __attribute__((visibility("default")))
-#    endif
-#    ifdef PUGL_INTERNAL
-#        define PUGL_API PUGL_LIB_EXPORT
-#    else
-#        define PUGL_API PUGL_LIB_IMPORT
-#    endif
-#else
-#    define PUGL_API
-#endif
-
-#ifndef PUGL_DISABLE_DEPRECATED
-#    if defined(__clang__)
-#        define PUGL_DEPRECATED_BY(rep) __attribute__((deprecated("", rep)))
-#    elif defined(__GNUC__)
-#        define PUGL_DEPRECATED_BY(rep) __attribute__((deprecated("Use " rep)))
-#    else
-#        define PUGL_DEPRECATED_BY(rep)
-#    endif
-#endif
-
-#if defined(__GNUC__)
-#    define PUGL_CONST_FUNC __attribute__((const))
-#else
-#    define PUGL_CONST_FUNC
-#endif
-
-#ifdef __cplusplus
-#	define PUGL_BEGIN_DECLS extern "C" {
-#	define PUGL_END_DECLS }
-#else
-#	define PUGL_BEGIN_DECLS
-#	define PUGL_END_DECLS
-#endif
-
-PUGL_BEGIN_DECLS
-
-/**
-   @defgroup pugl Pugl
-   A minimal portable API for embeddable GUIs.
-   @{
-
-   @defgroup pugl_c C API
-   Public C API.
-   @{
-*/
-
-/**
-   A rectangle.
-
-   This is used to describe things like view position and size.  Pugl generally
-   uses coordinates where the top left corner is 0,0.
-*/
-typedef struct {
-	double x;
-	double y;
-	double width;
-	double height;
-} PuglRect;
-
-/**
-   @defgroup events Events
-
-   Event definitions.
-
-   All updates to the view happen via events, which are dispatched to the
-   view's event function by Pugl.  Most events map directly to one from the
-   underlying window system, but some are constructed by Pugl itself so there
-   is not necessarily a direct correspondence.
-
-   @{
-*/
-
-/**
-   Keyboard modifier flags.
-*/
-typedef enum {
-	PUGL_MOD_SHIFT = 1u << 0u, ///< Shift key
-	PUGL_MOD_CTRL  = 1u << 1u, ///< Control key
-	PUGL_MOD_ALT   = 1u << 2u, ///< Alt/Option key
-	PUGL_MOD_SUPER = 1u << 3u  ///< Mod4/Command/Windows key
-} PuglMod;
-
-/**
-   Bitwise OR of #PuglMod values.
-*/
-typedef uint32_t PuglMods;
-
-/**
-   Keyboard key codepoints.
-
-   All keys are identified by a Unicode code point in PuglEventKey::key.  This
-   enumeration defines constants for special keys that do not have a standard
-   code point, and some convenience constants for control characters.  Note
-   that all keys are handled in the same way, this enumeration is just for
-   convenience when writing hard-coded key bindings.
-
-   Keys that do not have a standard code point use values in the Private Use
-   Area in the Basic Multilingual Plane (`U+E000` to `U+F8FF`).  Applications
-   must take care to not interpret these values beyond key detection, the
-   mapping used here is arbitrary and specific to Pugl.
-*/
-typedef enum {
-	// ASCII control codes
-	PUGL_KEY_BACKSPACE = 0x08,
-	PUGL_KEY_ESCAPE    = 0x1B,
-	PUGL_KEY_DELETE    = 0x7F,
-
-	// Unicode Private Use Area
-	PUGL_KEY_F1 = 0xE000,
-	PUGL_KEY_F2,
-	PUGL_KEY_F3,
-	PUGL_KEY_F4,
-	PUGL_KEY_F5,
-	PUGL_KEY_F6,
-	PUGL_KEY_F7,
-	PUGL_KEY_F8,
-	PUGL_KEY_F9,
-	PUGL_KEY_F10,
-	PUGL_KEY_F11,
-	PUGL_KEY_F12,
-	PUGL_KEY_LEFT,
-	PUGL_KEY_UP,
-	PUGL_KEY_RIGHT,
-	PUGL_KEY_DOWN,
-	PUGL_KEY_PAGE_UP,
-	PUGL_KEY_PAGE_DOWN,
-	PUGL_KEY_HOME,
-	PUGL_KEY_END,
-	PUGL_KEY_INSERT,
-	PUGL_KEY_SHIFT,
-	PUGL_KEY_SHIFT_L = PUGL_KEY_SHIFT,
-	PUGL_KEY_SHIFT_R,
-	PUGL_KEY_CTRL,
-	PUGL_KEY_CTRL_L = PUGL_KEY_CTRL,
-	PUGL_KEY_CTRL_R,
-	PUGL_KEY_ALT,
-	PUGL_KEY_ALT_L = PUGL_KEY_ALT,
-	PUGL_KEY_ALT_R,
-	PUGL_KEY_SUPER,
-	PUGL_KEY_SUPER_L = PUGL_KEY_SUPER,
-	PUGL_KEY_SUPER_R,
-	PUGL_KEY_MENU,
-	PUGL_KEY_CAPS_LOCK,
-	PUGL_KEY_SCROLL_LOCK,
-	PUGL_KEY_NUM_LOCK,
-	PUGL_KEY_PRINT_SCREEN,
-	PUGL_KEY_PAUSE
-} PuglKey;
-
-/**
-   The type of a PuglEvent.
-*/
-typedef enum {
-	PUGL_NOTHING,        ///< No event
-	PUGL_CREATE,         ///< View created, a #PuglEventCreate
-	PUGL_DESTROY,        ///< View destroyed, a #PuglEventDestroy
-	PUGL_CONFIGURE,      ///< View moved/resized, a #PuglEventConfigure
-	PUGL_MAP,            ///< View made visible, a #PuglEventMap
-	PUGL_UNMAP,          ///< View made invisible, a #PuglEventUnmap
-	PUGL_UPDATE,         ///< View ready to draw, a #PuglEventUpdate
-	PUGL_EXPOSE,         ///< View must be drawn, a #PuglEventExpose
-	PUGL_CLOSE,          ///< View will be closed, a #PuglEventClose
-	PUGL_FOCUS_IN,       ///< Keyboard focus entered view, a #PuglEventFocus
-	PUGL_FOCUS_OUT,      ///< Keyboard focus left view, a #PuglEventFocus
-	PUGL_KEY_PRESS,      ///< Key pressed, a #PuglEventKey
-	PUGL_KEY_RELEASE,    ///< Key released, a #PuglEventKey
-	PUGL_TEXT,           ///< Character entered, a #PuglEventText
-	PUGL_POINTER_IN,     ///< Pointer entered view, a #PuglEventCrossing
-	PUGL_POINTER_OUT,    ///< Pointer left view, a #PuglEventCrossing
-	PUGL_BUTTON_PRESS,   ///< Mouse button pressed, a #PuglEventButton
-	PUGL_BUTTON_RELEASE, ///< Mouse button released, a #PuglEventButton
-	PUGL_MOTION,         ///< Pointer moved, a #PuglEventMotion
-	PUGL_SCROLL,         ///< Scrolled, a #PuglEventScroll
-	PUGL_CLIENT,         ///< Custom client message, a #PuglEventClient
-	PUGL_TIMER,          ///< Timer triggered, a #PuglEventTimer
-
-#ifndef PUGL_DISABLE_DEPRECATED
-	PUGL_ENTER_NOTIFY PUGL_DEPRECATED_BY("PUGL_POINTER_IN") = PUGL_POINTER_IN,
-	PUGL_LEAVE_NOTIFY PUGL_DEPRECATED_BY("PUGL_POINTER_OUT") = PUGL_POINTER_OUT,
-	PUGL_MOTION_NOTIFY PUGL_DEPRECATED_BY("PUGL_MOTION") = PUGL_MOTION,
-#endif
-
-} PuglEventType;
-
-/**
-   Common flags for all event types.
-*/
-typedef enum {
-	PUGL_IS_SEND_EVENT = 1, ///< Event is synthetic
-	PUGL_IS_HINT       = 2  ///< Event is a hint (not direct user input)
-} PuglEventFlag;
-
-/**
-   Bitwise OR of #PuglEventFlag values.
-*/
-typedef uint32_t PuglEventFlags;
-
-/**
-   Reason for a PuglEventCrossing.
-*/
-typedef enum {
-	PUGL_CROSSING_NORMAL, ///< Crossing due to pointer motion
-	PUGL_CROSSING_GRAB,   ///< Crossing due to a grab
-	PUGL_CROSSING_UNGRAB  ///< Crossing due to a grab release
-} PuglCrossingMode;
-
-/**
-   Scroll direction.
-
-   Describes the direction of a #PuglEventScroll along with whether the scroll
-   is a "smooth" scroll.  The discrete directions are for devices like mouse
-   wheels with constrained axes, while a smooth scroll is for those with
-   arbitrary scroll direction freedom, like some touchpads.
-*/
-typedef enum {
-	PUGL_SCROLL_UP,    ///< Scroll up
-	PUGL_SCROLL_DOWN,  ///< Scroll down
-	PUGL_SCROLL_LEFT,  ///< Scroll left
-	PUGL_SCROLL_RIGHT, ///< Scroll right
-	PUGL_SCROLL_SMOOTH ///< Smooth scroll in any direction
-} PuglScrollDirection;
-
-/**
-   Common header for all event structs.
-*/
-typedef struct {
-	PuglEventType  type;  ///< Event type
-	PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
-} PuglEventAny;
-
-/**
-   View create event.
-
-   This event is sent when a view is realized before it is first displayed,
-   with the graphics context entered.  This is typically used for setting up
-   the graphics system, for example by loading OpenGL extensions.
-
-   This event type has no extra fields.
-*/
-typedef PuglEventAny PuglEventCreate;
-
-/**
-   View destroy event.
-
-   This event is the counterpart to #PuglEventCreate, and it is sent when the
-   view is being destroyed.  This is typically used for tearing down the
-   graphics system, or otherwise freeing any resources allocated when the
-   create event was handled.
-
-   This is the last event sent to any view, and immediately after it is
-   processed, the view is destroyed and may no longer be used.
-
-   This event type has no extra fields.
-*/
-typedef PuglEventAny PuglEventDestroy;
-
-/**
-   View resize or move event.
-
-   A configure event is sent whenever the view is resized or moved.  When a
-   configure event is received, the graphics context is active but not set up
-   for drawing.  For example, it is valid to adjust the OpenGL viewport or
-   otherwise configure the context, but not to draw anything.
-*/
-typedef struct {
-	PuglEventType  type;   ///< #PUGL_CONFIGURE
-	PuglEventFlags flags;  ///< Bitwise OR of #PuglEventFlag values
-	double         x;      ///< New parent-relative X coordinate
-	double         y;      ///< New parent-relative Y coordinate
-	double         width;  ///< New width
-	double         height; ///< New height
-} PuglEventConfigure;
-
-/**
-   View show event.
-
-   This event is sent when a view is mapped to the screen and made visible.
-
-   This event type has no extra fields.
-*/
-typedef PuglEventAny PuglEventMap;
-
-/**
-   View hide event.
-
-   This event is sent when a view is unmapped from the screen and made
-   invisible.
-
-   This event type has no extra fields.
-*/
-typedef PuglEventAny PuglEventUnmap;
-
-/**
-   View update event.
-
-   This event is sent to every view near the end of a main loop iteration when
-   any pending exposures are about to be redrawn.  It is typically used to mark
-   regions to expose with puglPostRedisplay() or puglPostRedisplayRect().  For
-   example, to continuously animate, a view calls puglPostRedisplay() when an
-   update event is received, and it will then shortly receive an expose event.
-*/
-typedef PuglEventAny PuglEventUpdate;
-
-/**
-   Expose event for when a region must be redrawn.
-
-   When an expose event is received, the graphics context is active, and the
-   view must draw the entire specified region.  The contents of the region are
-   undefined, there is no preservation of anything drawn previously.
-*/
-typedef struct {
-	PuglEventType  type;   ///< #PUGL_EXPOSE
-	PuglEventFlags flags;  ///< Bitwise OR of #PuglEventFlag values
-	double         x;      ///< View-relative X coordinate
-	double         y;      ///< View-relative Y coordinate
-	double         width;  ///< Width of exposed region
-	double         height; ///< Height of exposed region
-} PuglEventExpose;
-
-/**
-   View close event.
-
-   This event is sent when the view is to be closed, for example when the user
-   clicks the close button.
-
-   This event type has no extra fields.
-*/
-typedef PuglEventAny PuglEventClose;
-
-/**
-   Keyboard focus event.
-
-   This event is sent whenever the view gains or loses the keyboard focus.  The
-   view with the keyboard focus will receive any key press or release events.
-*/
-typedef struct {
-	PuglEventType    type;  ///< #PUGL_FOCUS_IN or #PUGL_FOCUS_OUT
-	PuglEventFlags   flags; ///< Bitwise OR of #PuglEventFlag values
-	PuglCrossingMode mode;  ///< Reason for focus change
-} PuglEventFocus;
-
-/**
-   Key press or release event.
-
-   This event represents low-level key presses and releases.  This can be used
-   for "direct" keyboard handing like key bindings, but must not be interpreted
-   as text input.
-
-   Keys are represented portably as Unicode code points, using the "natural"
-   code point for the key where possible (see #PuglKey for details).  The `key`
-   field is the code for the pressed key, without any modifiers applied.  For
-   example, a press or release of the 'A' key will have `key` 97 ('a')
-   regardless of whether shift or control are being held.
-
-   Alternatively, the raw `keycode` can be used to work directly with physical
-   keys, but note that this value is not portable and differs between platforms
-   and hardware.
-*/
-typedef struct {
-	PuglEventType  type;    ///< #PUGL_KEY_PRESS or #PUGL_KEY_RELEASE
-	PuglEventFlags flags;   ///< Bitwise OR of #PuglEventFlag values
-	double         time;    ///< Time in seconds
-	double         x;       ///< View-relative X coordinate
-	double         y;       ///< View-relative Y coordinate
-	double         xRoot;   ///< Root-relative X coordinate
-	double         yRoot;   ///< Root-relative Y coordinate
-	PuglMods       state;   ///< Bitwise OR of #PuglMod flags
-	uint32_t       keycode; ///< Raw key code
-	uint32_t       key;     ///< Unshifted Unicode character code, or 0
-} PuglEventKey;
-
-/**
-   Character input event.
-
-   This event represents text input, usually as the result of a key press.  The
-   text is given both as a Unicode character code and a UTF-8 string.
-
-   Note that this event is generated by the platform's input system, so there
-   is not necessarily a direct correspondence between text events and physical
-   key presses.  For example, with some input methods a sequence of several key
-   presses will generate a single character.
-*/
-typedef struct {
-	PuglEventType  type;      ///< #PUGL_TEXT
-	PuglEventFlags flags;     ///< Bitwise OR of #PuglEventFlag values
-	double         time;      ///< Time in seconds
-	double         x;         ///< View-relative X coordinate
-	double         y;         ///< View-relative Y coordinate
-	double         xRoot;     ///< Root-relative X coordinate
-	double         yRoot;     ///< Root-relative Y coordinate
-	PuglMods       state;     ///< Bitwise OR of #PuglMod flags
-	uint32_t       keycode;   ///< Raw key code
-	uint32_t       character; ///< Unicode character code
-	char           string[8]; ///< UTF-8 string
-} PuglEventText;
-
-/**
-   Pointer enter or leave event.
-
-   This event is sent when the pointer enters or leaves the view.  This can
-   happen for several reasons (not just the user dragging the pointer over the
-   window edge), as described by the `mode` field.
-*/
-typedef struct {
-	PuglEventType    type;  ///< #PUGL_POINTER_IN or #PUGL_POINTER_OUT
-	PuglEventFlags   flags; ///< Bitwise OR of #PuglEventFlag values
-	double           time;  ///< Time in seconds
-	double           x;     ///< View-relative X coordinate
-	double           y;     ///< View-relative Y coordinate
-	double           xRoot; ///< Root-relative X coordinate
-	double           yRoot; ///< Root-relative Y coordinate
-	PuglMods         state; ///< Bitwise OR of #PuglMod flags
-	PuglCrossingMode mode;  ///< Reason for crossing
-} PuglEventCrossing;
-
-/**
-   Button press or release event.
-*/
-typedef struct {
-	PuglEventType  type;   ///< #PUGL_BUTTON_PRESS or #PUGL_BUTTON_RELEASE
-	PuglEventFlags flags;  ///< Bitwise OR of #PuglEventFlag values
-	double         time;   ///< Time in seconds
-	double         x;      ///< View-relative X coordinate
-	double         y;      ///< View-relative Y coordinate
-	double         xRoot;  ///< Root-relative X coordinate
-	double         yRoot;  ///< Root-relative Y coordinate
-	PuglMods       state;  ///< Bitwise OR of #PuglMod flags
-	uint32_t       button; ///< Button number starting from 1
-} PuglEventButton;
-
-/**
-   Pointer motion event.
-*/
-typedef struct {
-	PuglEventType  type;   ///< #PUGL_MOTION
-	PuglEventFlags flags;  ///< Bitwise OR of #PuglEventFlag values
-	double         time;   ///< Time in seconds
-	double         x;      ///< View-relative X coordinate
-	double         y;      ///< View-relative Y coordinate
-	double         xRoot;  ///< Root-relative X coordinate
-	double         yRoot;  ///< Root-relative Y coordinate
-	PuglMods       state;  ///< Bitwise OR of #PuglMod flags
-} PuglEventMotion;
-
-/**
-   Scroll event.
-
-   The scroll distance is expressed in "lines", an arbitrary unit that
-   corresponds to a single tick of a detented mouse wheel.  For example, `dy` =
-   1.0 scrolls 1 line up.  Some systems and devices support finer resolution
-   and/or higher values for fast scrolls, so programs should handle any value
-   gracefully.
-*/
-typedef struct {
-	PuglEventType       type;      ///< #PUGL_SCROLL
-	PuglEventFlags      flags;     ///< Bitwise OR of #PuglEventFlag values
-	double              time;      ///< Time in seconds
-	double              x;         ///< View-relative X coordinate
-	double              y;         ///< View-relative Y coordinate
-	double              xRoot;     ///< Root-relative X coordinate
-	double              yRoot;     ///< Root-relative Y coordinate
-	PuglMods            state;     ///< Bitwise OR of #PuglMod flags
-	PuglScrollDirection direction; ///< Scroll direction
-	double              dx;        ///< Scroll X distance in lines
-	double              dy;        ///< Scroll Y distance in lines
-} PuglEventScroll;
-
-/**
-   Custom client message event.
-
-   This can be used to send a custom message to a view, which is delivered via
-   the window system and processed in the event loop as usual.  Among other
-   things, this makes it possible to wake up the event loop for any reason.
-*/
-typedef struct {
-	PuglEventType  type;  ///< #PUGL_CLIENT
-	PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
-	uintptr_t      data1; ///< Client-specific data
-	uintptr_t      data2; ///< Client-specific data
-} PuglEventClient;
-
-/**
-   Timer event.
-
-   This event is sent at the regular interval specified in the call to
-   puglStartTimer() that activated it.
-
-   The `id` is the application-specific ID given to puglStartTimer() which
-   distinguishes this timer from others.  It should always be checked in the
-   event handler, even in applications that register only one timer.
-*/
-typedef struct {
-	PuglEventType  type;  ///< #PUGL_TIMER
-	PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
-	uintptr_t      id;    ///< Timer ID
-} PuglEventTimer;
-
-/**
-   View event.
-
-   This is a union of all event types.  The type must be checked to determine
-   which fields are safe to access.  A pointer to PuglEvent can either be cast
-   to the appropriate type, or the union members used.
-
-   The graphics system may only be accessed when handling certain events.  The
-   graphics context is active for #PUGL_CREATE, #PUGL_DESTROY, #PUGL_CONFIGURE,
-   and #PUGL_EXPOSE, but only enabled for drawing for #PUGL_EXPOSE.
-*/
-typedef union {
-	PuglEventAny       any;       ///< Valid for all event types
-	PuglEventType      type;      ///< Event type
-	PuglEventButton    button;    ///< #PUGL_BUTTON_PRESS, #PUGL_BUTTON_RELEASE
-	PuglEventConfigure configure; ///< #PUGL_CONFIGURE
-	PuglEventExpose    expose;    ///< #PUGL_EXPOSE
-	PuglEventKey       key;       ///< #PUGL_KEY_PRESS, #PUGL_KEY_RELEASE
-	PuglEventText      text;      ///< #PUGL_TEXT
-	PuglEventCrossing  crossing;  ///< #PUGL_POINTER_IN, #PUGL_POINTER_OUT
-	PuglEventMotion    motion;    ///< #PUGL_MOTION
-	PuglEventScroll    scroll;    ///< #PUGL_SCROLL
-	PuglEventFocus     focus;     ///< #PUGL_FOCUS_IN, #PUGL_FOCUS_OUT
-	PuglEventClient    client;    ///< #PUGL_CLIENT
-	PuglEventTimer     timer;     ///< #PUGL_TIMER
-} PuglEvent;
-
-/**
-   @}
-   @defgroup status Status
-
-   Status codes and error handling.
-
-   @{
-*/
-
-/**
-   Return status code.
-*/
-typedef enum {
-	PUGL_SUCCESS,               ///< Success
-	PUGL_FAILURE,               ///< Non-fatal failure
-	PUGL_UNKNOWN_ERROR,         ///< Unknown system error
-	PUGL_BAD_BACKEND,           ///< Invalid or missing backend
-	PUGL_BAD_CONFIGURATION,     ///< Invalid view configuration
-	PUGL_BAD_PARAMETER,         ///< Invalid parameter
-	PUGL_BACKEND_FAILED,        ///< Backend initialisation failed
-	PUGL_REGISTRATION_FAILED,   ///< Class registration failed
-	PUGL_REALIZE_FAILED,        ///< System view realization failed
-	PUGL_SET_FORMAT_FAILED,     ///< Failed to set pixel format
-	PUGL_CREATE_CONTEXT_FAILED, ///< Failed to create drawing context
-	PUGL_UNSUPPORTED_TYPE,      ///< Unsupported data type
-} PuglStatus;
-
-/**
-   Return a string describing a status code.
-*/
-PUGL_API PUGL_CONST_FUNC
-const char*
-puglStrerror(PuglStatus status);
-
-/**
-   @}
-   @defgroup world World
-
-   The top-level context of a Pugl application or plugin.
-
-   The world contains all library-wide state.  There is no static data in Pugl,
-   so it is safe to use multiple worlds in a single process.  This is to
-   facilitate plugins or other situations where it is not possible to share a
-   world, but a single world should be shared for all views where possible.
-
-   @{
-*/
-
-/**
-   The "world" of application state.
-
-   The world represents everything that is not associated with a particular
-   view.  Several worlds can be created in a single process, but code using
-   different worlds must be isolated so they are never mixed.  Views are
-   strongly associated with the world they were created in.
-*/
-typedef struct PuglWorldImpl PuglWorld;
-
-/**
-   Handle for the world's opaque user data.
-*/
-typedef void* PuglWorldHandle;
-
-/**
-   The type of a World.
-*/
-typedef enum {
-	PUGL_PROGRAM, ///< Top-level application
-	PUGL_MODULE   ///< Plugin or module within a larger application
-} PuglWorldType;
-
-/**
-   World flags.
-*/
-typedef enum {
-	/**
-	   Set up support for threads if necessary.
-
-	   - X11: Calls XInitThreads() which is required for some drivers.
-	*/
-	PUGL_WORLD_THREADS = 1u << 0u
-} PuglWorldFlag;
-
-/**
-   Bitwise OR of #PuglWorldFlag values.
-*/
-typedef uint32_t PuglWorldFlags;
-
-/**
-   A log message level, compatible with syslog.
-*/
-typedef enum {
-	PUGL_LOG_LEVEL_ERR     = 3, ///< Error
-	PUGL_LOG_LEVEL_WARNING = 4, ///< Warning
-	PUGL_LOG_LEVEL_INFO    = 6, ///< Informational message
-	PUGL_LOG_LEVEL_DEBUG   = 7  ///< Debug message
-} PuglLogLevel;
-
-/**
-   A function called to report log messages.
-
-   @param world The world that produced this log message.
-   @param level Log level.
-   @param msg Message string.
-*/
-typedef void (*PuglLogFunc)(PuglWorld*   world,
-                            PuglLogLevel level,
-                            const char*  msg);
-
-/**
-   Create a new world.
-
-   @param type The type, which dictates what this world is responsible for.
-   @param flags Flags to control world features.
-   @return A new world, which must be later freed with puglFreeWorld().
-*/
-PUGL_API PuglWorld*
-puglNewWorld(PuglWorldType type, PuglWorldFlags flags);
-
-/**
-   Free a world allocated with puglNewWorld().
-*/
-PUGL_API void
-puglFreeWorld(PuglWorld* world);
-
-/**
-   Set the user data for the world.
-
-   This is usually a pointer to a struct that contains all the state which must
-   be accessed by several views.
-
-   The handle is opaque to Pugl and is not interpreted in any way.
-*/
-PUGL_API void
-puglSetWorldHandle(PuglWorld* world, PuglWorldHandle handle);
-
-/**
-   Get the user data for the world.
-*/
-PUGL_API PuglWorldHandle
-puglGetWorldHandle(PuglWorld* world);
-
-/**
-   Return a pointer to the native handle of the world.
-
-   @return
-   - X11: A pointer to the `Display`.
-   - MacOS: `NULL`.
-   - Windows: The `HMODULE` of the calling process.
-*/
-PUGL_API void*
-puglGetNativeWorld(PuglWorld* world);
-
-/**
-   Set the function to call to log a message.
-
-   This will be called to report any log messages generated internally by Pugl
-   which are enabled according to the log level.
-*/
-PUGL_API PuglStatus
-puglSetLogFunc(PuglWorld* world, PuglLogFunc logFunc);
-
-/**
-   Set the level of log messages to emit.
-
-   Any log messages with a level less than or equal to `level` will be emitted.
-*/
-PUGL_API PuglStatus
-puglSetLogLevel(PuglWorld* world, PuglLogLevel level);
-
-/**
-   Set the class name of the application.
-
-   This is a stable identifier for the application, used as the window
-   class/instance name on X11 and Windows.  It is not displayed to the user,
-   but can be used in scripts and by window managers, so it should be the same
-   for every instance of the application, but different from other
-   applications.
-*/
-PUGL_API PuglStatus
-puglSetClassName(PuglWorld* world, const char* name);
-
-/**
-   Return the time in seconds.
-
-   This is a monotonically increasing clock with high resolution.  The returned
-   time is only useful to compare against other times returned by this
-   function, its absolute value has no meaning.
-*/
-PUGL_API double
-puglGetTime(const PuglWorld* world);
-
-/**
-   Update by processing events from the window system.
-
-   This function is a single iteration of the main loop, and should be called
-   repeatedly to update all views.
-
-   If `timeout` is zero, then this function will not block.  Plugins should
-   always use a timeout of zero to avoid blocking the host.
-
-   If a positive `timeout` is given, then events will be processed for that
-   amount of time, starting from when this function was called.
-
-   If a negative `timeout` is given, this function will block indefinitely
-   until an event occurs.
-
-   For continuously animating programs, a timeout that is a reasonable fraction
-   of the ideal frame period should be used, to minimise input latency by
-   ensuring that as many input events are consumed as possible before drawing.
-
-   @return
-   - #PUGL_SUCCESS if events are read
-   - #PUGL_FAILURE if not, or an error.
-*/
-PUGL_API PuglStatus
-puglUpdate(PuglWorld* world, double timeout);
-
-/**
-   @}
-
-   @defgroup view View
-
-   A drawable region that receives events.
-
-   A view can be thought of as a window, but does not necessarily correspond to
-   a top-level window in a desktop environment.  For example, a view can be
-   embedded in some other window, or represent an embedded system where there
-   is no concept of multiple windows at all.
-
-   @{
-*/
-
-/**
-   A drawable region that receives events.
-*/
-typedef struct PuglViewImpl PuglView;
-
-/**
-   A graphics backend.
-
-   The backend dictates how graphics are set up for a view, and how drawing is
-   performed.  A backend must be set by calling puglSetBackend() before
-   realising a view.
-
-   If you are using a local copy of Pugl, it is possible to implement a custom
-   backend.  See the definition of `PuglBackendImpl` in the source code for
-   details.
-*/
-typedef struct PuglBackendImpl PuglBackend;
-
-/**
-   A native view handle.
-
-   X11: This is a `Window`.
-
-   MacOS: This is a pointer to an `NSView*`.
-
-   Windows: This is a `HWND`.
-*/
-typedef uintptr_t PuglNativeView;
-
-/**
-   Handle for a view's opaque user data.
-*/
-typedef void* PuglHandle;
-
-/**
-   A hint for configuring a view.
-*/
-typedef enum {
-	PUGL_USE_COMPAT_PROFILE,    ///< Use compatible (not core) OpenGL profile
-	PUGL_USE_DEBUG_CONTEXT,     ///< True to use a debug OpenGL context
-	PUGL_CONTEXT_VERSION_MAJOR, ///< OpenGL context major version
-	PUGL_CONTEXT_VERSION_MINOR, ///< OpenGL context minor version
-	PUGL_RED_BITS,              ///< Number of bits for red channel
-	PUGL_GREEN_BITS,            ///< Number of bits for green channel
-	PUGL_BLUE_BITS,             ///< Number of bits for blue channel
-	PUGL_ALPHA_BITS,            ///< Number of bits for alpha channel
-	PUGL_DEPTH_BITS,            ///< Number of bits for depth buffer
-	PUGL_STENCIL_BITS,          ///< Number of bits for stencil buffer
-	PUGL_SAMPLES,               ///< Number of samples per pixel (AA)
-	PUGL_DOUBLE_BUFFER,         ///< True if double buffering should be used
-	PUGL_SWAP_INTERVAL,         ///< Number of frames between buffer swaps
-	PUGL_RESIZABLE,             ///< True if view should be resizable
-	PUGL_IGNORE_KEY_REPEAT,     ///< True if key repeat events are ignored
-	PUGL_REFRESH_RATE,          ///< Refresh rate in Hz
-
-	PUGL_NUM_VIEW_HINTS
-} PuglViewHint;
-
-/**
-   A special view hint value.
-*/
-typedef enum {
-	PUGL_DONT_CARE = -1, ///< Use best available value
-	PUGL_FALSE     = 0,  ///< Explicitly false
-	PUGL_TRUE      = 1   ///< Explicitly true
-} PuglViewHintValue;
-
-/**
-   A function called when an event occurs.
-*/
-typedef PuglStatus (*PuglEventFunc)(PuglView* view, const PuglEvent* event);
-
-/**
-   @name Setup
-   Functions for creating and destroying a view.
-   @{
-*/
-
-/**
-   Create a new view.
-
-   A newly created view does not correspond to a real system view or window.
-   It must first be configured, then the system view can be created with
-   puglRealize().
-*/
-PUGL_API PuglView*
-puglNewView(PuglWorld* world);
-
-/**
-   Free a view created with puglNewView().
-*/
-PUGL_API void
-puglFreeView(PuglView* view);
-
-/**
-   Return the world that `view` is a part of.
-*/
-PUGL_API PuglWorld*
-puglGetWorld(PuglView* view);
-
-/**
-   Set the user data for a view.
-
-   This is usually a pointer to a struct that contains all the state which must
-   be accessed by a view.  Everything needed to process events should be stored
-   here, not in static variables.
-
-   The handle is opaque to Pugl and is not interpreted in any way.
-*/
-PUGL_API void
-puglSetHandle(PuglView* view, PuglHandle handle);
-
-/**
-   Get the user data for a view.
-*/
-PUGL_API PuglHandle
-puglGetHandle(PuglView* view);
-
-/**
-   Set the graphics backend to use for a view.
-
-   This must be called once to set the graphics backend before calling
-   puglRealize().
-
-   Pugl includes the following backends:
-
-   - puglGlBackend(), declared in pugl_gl.h
-   - puglCairoBackend(), declared in pugl_cairo.h
-
-   Note that backends are modular and not compiled into the main Pugl library
-   to avoid unnecessary dependencies.  To use a particular backend,
-   applications must link against the appropriate backend library, or be sure
-   to compile in the appropriate code if using a local copy of Pugl.
-*/
-PUGL_API PuglStatus
-puglSetBackend(PuglView* view, const PuglBackend* backend);
-
-/**
-   Set the function to call when an event occurs.
-*/
-PUGL_API PuglStatus
-puglSetEventFunc(PuglView* view, PuglEventFunc eventFunc);
-
-/**
-   Set a hint to configure view properties.
-
-   This only has an effect when called before puglRealize().
-*/
-PUGL_API PuglStatus
-puglSetViewHint(PuglView* view, PuglViewHint hint, int value);
-
-/**
-   Get the value for a view hint.
-
-   If the view has been realized, this can be used to get the actual value of a
-   hint which was initially set to PUGL_DONT_CARE, or has been adjusted from
-   the suggested value.
-*/
-PUGL_API int
-puglGetViewHint(const PuglView* view, PuglViewHint hint);
-
-/**
-   @}
-   @anchor frame
-   @name Frame
-   Functions for working with the position and size of a view.
-   @{
-*/
-
-/**
-   Get the current position and size of the view.
-
-   The position is in screen coordinates with an upper left origin.
-*/
-PUGL_API PuglRect
-puglGetFrame(const PuglView* view);
-
-/**
-   Set the current position and size of the view.
-
-   The position is in screen coordinates with an upper left origin.
-
-   @return #PUGL_UNKNOWN_ERROR on failure, in which case the view frame is
-   unchanged.
-*/
-PUGL_API PuglStatus
-puglSetFrame(PuglView* view, PuglRect frame);
-
-/**
-   Set the default size of the view.
-
-   This should be called before puglResize() to set the default size of the
-   view, which will be the initial size of the window if this is a top level
-   view.
-
-   @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is
-   not yet realized.
-*/
-PUGL_API PuglStatus
-puglSetDefaultSize(PuglView* view, int width, int height);
-
-/**
-   Set the minimum size of the view.
-
-   If an initial minimum size is known, this should be called before
-   puglRealize() to avoid stutter, though it can be called afterwards as well.
-
-   @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is
-   not yet realized.
-*/
-PUGL_API PuglStatus
-puglSetMinSize(PuglView* view, int width, int height);
-
-/**
-   Set the maximum size of the view.
-
-   If an initial maximum size is known, this should be called before
-   puglRealize() to avoid stutter, though it can be called afterwards as well.
-
-   @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is
-   not yet realized.
-*/
-PUGL_API PuglStatus
-puglSetMaxSize(PuglView* view, int width, int height);
-
-/**
-   Set the view aspect ratio range.
-
-   The x and y values here represent a ratio of width to height.  To set a
-   fixed aspect ratio, set the minimum and maximum values to the same ratio.
-
-   Note that setting different minimum and maximum constraints does not
-   currenty work on MacOS (the minimum is used), so only setting a fixed aspect
-   ratio works properly across all platforms.
-
-   If an initial aspect ratio is known, this should be called before
-   puglRealize() to avoid stutter, though it can be called afterwards as well.
-
-   @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is
-   not yet realized.
-*/
-PUGL_API PuglStatus
-puglSetAspectRatio(PuglView* view, int minX, int minY, int maxX, int maxY);
-
-/**
-   @}
-   @name Windows
-   Functions for working with system views and the window hierarchy.
-   @{
-*/
-
-/**
-   Set the title of the window.
-
-   This only makes sense for non-embedded views that will have a corresponding
-   top-level window, and sets the title, typically displayed in the title bar
-   or in window switchers.
-*/
-PUGL_API PuglStatus
-puglSetWindowTitle(PuglView* view, const char* title);
-
-/**
-   Set the parent window for embedding a view in an existing window.
-
-   This must be called before puglRealize(), reparenting is not supported.
-*/
-PUGL_API PuglStatus
-puglSetParentWindow(PuglView* view, PuglNativeView parent);
-
-/**
-   Set the transient parent of the window.
-
-   Set this for transient children like dialogs, to have them properly
-   associated with their parent window.  This should be called before
-   puglRealize().
-
-   A view can either have a parent (for embedding) or a transient parent (for
-   top-level windows like dialogs), but not both.
-*/
-PUGL_API PuglStatus
-puglSetTransientFor(PuglView* view, PuglNativeView parent);
-
-/**
-   Realise a view by creating a corresponding system view or window.
-
-   After this call, the (initially invisible) underlying system view exists and
-   can be accessed with puglGetNativeWindow().  There is currently no
-   corresponding unrealize function, the system view will be destroyed along
-   with the view when puglFreeView() is called.
-
-   The view should be fully configured using the above functions before this is
-   called.  This function may only be called once per view.
-*/
-PUGL_API PuglStatus
-puglRealize(PuglView* view);
-
-/**
-   Show the view.
-
-   If the view has not yet been realized, the first call to this function will
-   do so automatically.
-
-   If the view is currently hidden, it will be shown and possibly raised to the
-   top depending on the platform.
-*/
-PUGL_API PuglStatus
-puglShowWindow(PuglView* view);
-
-/**
-   Hide the current window.
-*/
-PUGL_API PuglStatus
-puglHideWindow(PuglView* view);
-
-/**
-   Return true iff the view is currently visible.
-*/
-PUGL_API bool
-puglGetVisible(const PuglView* view);
-
-/**
-   Return the native window handle.
-*/
-PUGL_API PuglNativeView
-puglGetNativeWindow(PuglView* view);
-
-/**
-   @}
-   @name Graphics
-   Functions for working with the graphics context and scheduling redisplays.
-   @{
-*/
-
-/**
-   Get the graphics context.
-
-   This is a backend-specific context used for drawing if the backend graphics
-   API requires one.  It is only available during an expose.
-
-   @return
-   - Cairo: A pointer to a
-     [`cairo_t`](http://www.cairographics.org/manual/cairo-cairo-t.html).
-   - OpenGL: `NULL`.
-   - Stub: `NULL`.
-*/
-PUGL_API void*
-puglGetContext(PuglView* view);
-
-/**
-   Request a redisplay for the entire view.
-
-   This will cause an expose event to be dispatched later.  If called from
-   within the event handler, the expose should arrive at the end of the current
-   event loop iteration, though this is not strictly guaranteed on all
-   platforms.  If called elsewhere, an expose will be enqueued to be processed
-   in the next event loop iteration.
-*/
-PUGL_API PuglStatus
-puglPostRedisplay(PuglView* view);
-
-/**
-   Request a redisplay of the given rectangle within the view.
-
-   This has the same semantics as puglPostRedisplay(), but allows giving a
-   precise region for redrawing only a portion of the view.
-*/
-PUGL_API PuglStatus
-puglPostRedisplayRect(PuglView* view, PuglRect rect);
-
-/**
-   @}
-   @anchor interaction
-   @name Interaction
-   Functions for interacting with the user and window system.
-   @{
-*/
-
-/**
-   A mouse cursor type.
-
-   This is a portable subset of mouse cursors that exist on X11, MacOS, and
-   Windows.
-*/
-typedef enum {
-	PUGL_CURSOR_ARROW,      ///< Default pointing arrow
-	PUGL_CURSOR_CARET,      ///< Caret (I-Beam) for text entry
-	PUGL_CURSOR_CROSSHAIR,  ///< Cross-hair
-	PUGL_CURSOR_HAND,       ///< Hand with a pointing finger
-	PUGL_CURSOR_NO,         ///< Operation not allowed
-	PUGL_CURSOR_LEFT_RIGHT, ///< Left/right arrow for horizontal resize
-	PUGL_CURSOR_UP_DOWN,    ///< Up/down arrow for vertical resize
-} PuglCursor;
-
-/**
-   Grab the keyboard input focus.
-*/
-PUGL_API PuglStatus
-puglGrabFocus(PuglView* view);
-
-/**
-   Return whether `view` has the keyboard input focus.
-*/
-PUGL_API bool
-puglHasFocus(const PuglView* view);
-
-/**
-   Set the clipboard contents.
-
-   This sets the system clipboard contents, which can be retrieved with
-   puglGetClipboard() or pasted into other applications.
-
-   @param view The view.
-   @param type The MIME type of the data, "text/plain" is assumed if `NULL`.
-   @param data The data to copy to the clipboard.
-   @param len The length of data in bytes (including terminator if necessary).
-*/
-PUGL_API PuglStatus
-puglSetClipboard(PuglView*   view,
-                 const char* type,
-                 const void* data,
-                 size_t      len);
-
-/**
-   Get the clipboard contents.
-
-   This gets the system clipboard contents, which may have been set with
-   puglSetClipboard() or copied from another application.
-
-   @param view The view.
-   @param[out] type Set to the MIME type of the data.
-   @param[out] len Set to the length of the data in bytes.
-   @return The clipboard contents, or `NULL`.
-*/
-PUGL_API const void*
-puglGetClipboard(PuglView* view, const char** type, size_t* len);
-
-/**
-   Set the mouse cursor.
-
-   This changes the system cursor that is displayed when the pointer is inside
-   the view.  May fail if setting the cursor is not supported on this system,
-   for example if compiled on X11 without Xcursor support.
-
-   @return
-   - #PUGL_BAD_PARAMETER if the given cursor is invalid.
-   - #PUGL_FAILURE if the cursor isknown but loading it from the system fails.
-*/
-PUGL_API PuglStatus
-puglSetCursor(PuglView* view, PuglCursor cursor);
-
-/**
-   Request user attention.
-
-   This hints to the system that the window or application requires attention
-   from the user.  The exact effect depends on the platform, but is usually
-   something like a flashing task bar entry or bouncing application icon.
-*/
-PUGL_API PuglStatus
-puglRequestAttention(PuglView* view);
-
-/**
-   Activate a repeating timer event.
-
-   This starts a timer which will send a #PuglEventTimer to `view` every
-   `timeout` seconds.  This can be used to perform some action in a view at a
-   regular interval with relatively low frequency.  Note that the frequency of
-   timer events may be limited by how often puglUpdate() is called.
-
-   If the given timer already exists, it is replaced.
-
-   @param view The view to begin seding #PUGL_TIMER events to.
-
-   @param id The identifier for this timer.  This is an application-specific ID
-   that should be a low number, typically the value of a constant or `enum`
-   that starts from 0.  There is a platform-specific limit to the number of
-   supported timers, and overhead associated with each, so applications should
-   create only a few timers and perform several tasks in one if necessary.
-
-   @param timeout The period, in seconds, of this timer.  This is not
-   guaranteed to have a resolution better than 10ms (the maximum timer
-   resolution on Windows) and may be rounded up if it is too short.  On X11 and
-   MacOS, a resolution of about 1ms can usually be relied on.
-
-   @return
-   - #PUGL_FAILURE if timers are not supported by this system or build.
-   - #PUGL_UNKNOWN_ERROR if setting the timer failed.
-*/
-PUGL_API PuglStatus
-puglStartTimer(PuglView* view, uintptr_t id, double timeout);
-
-/**
-   Stop an active timer.
-
-   @param view The view that the timer is set for.
-   @param id The ID previously passed to puglStartTimer().
-
-   @return
-   - #PUGL_FAILURE if timers are not supported by this system or build.
-   - #PUGL_UNKNOWN_ERROR if stopping the timer failed.
-*/
-PUGL_API PuglStatus
-puglStopTimer(PuglView* view, uintptr_t id);
-
-/**
-   Send an event to a view via the window system.
-
-   If supported, the event will be delivered to the view via the event loop
-   like other events.  Note that this function only works for certain event
-   types.
-
-   Currently, only #PUGL_CLIENT events are supported on all platforms.
-
-   X11: A #PUGL_EXPOSE event can be sent, which is similar to calling
-   puglPostRedisplayRect(), but will always send a message to the X server,
-   even when called in an event handler.
-
-   @return
-   - #PUGL_UNSUPPORTED_TYPE if sending events of this type is not supported.
-   - #PUGL_UNKNOWN_ERROR if sending the event failed.
-*/
-PUGL_API PuglStatus
-puglSendEvent(PuglView* view, const PuglEvent* event);
-
-/**
-   @}
-*/
-
-#ifndef PUGL_DISABLE_DEPRECATED
-
-/**
-   @}
-   @name Deprecated API
-   @{
-*/
-
-/**
-   A native window handle.
-
-   X11: This is a `Window`.
-
-   MacOS: This is a pointer to an `NSView*`.
-
-   Windows: This is a `HWND`.
-*/
-typedef uintptr_t PuglNativeWindow;
-
-/**
-   Create a Pugl application and view.
-
-   To create a window, call the various puglInit* functions as necessary, then
-   call puglRealize().
-
-   @deprecated Use puglNewApp() and puglNewView().
-
-   @param pargc Pointer to argument count (currently unused).
-   @param argv  Arguments (currently unused).
-   @return A newly created view.
-*/
-static inline PUGL_DEPRECATED_BY("puglNewView") PuglView*
-puglInit(const int* pargc, char** argv)
-{
-	(void)pargc;
-	(void)argv;
-
-	return puglNewView(puglNewWorld(PUGL_MODULE, 0));
-}
-
-/**
-   Destroy an app and view created with `puglInit()`.
-
-   @deprecated Use puglFreeApp() and puglFreeView().
-*/
-static inline PUGL_DEPRECATED_BY("puglFreeView") void
-puglDestroy(PuglView* view)
-{
-	PuglWorld* const world = puglGetWorld(view);
-
-	puglFreeView(view);
-	puglFreeWorld(world);
-}
-
-/**
-   Set the window class name before creating a window.
-*/
-static inline PUGL_DEPRECATED_BY("puglSetClassName") void
-puglInitWindowClass(PuglView* view, const char* name)
-{
-	puglSetClassName(puglGetWorld(view), name);
-}
-
-/**
-   Set the window size before creating a window.
-
-   @deprecated Use puglSetFrame().
-*/
-static inline PUGL_DEPRECATED_BY("puglSetFrame") void
-puglInitWindowSize(PuglView* view, int width, int height)
-{
-	PuglRect frame = puglGetFrame(view);
-
-	frame.width = width;
-	frame.height = height;
-
-	puglSetFrame(view, frame);
-}
-
-/**
-   Set the minimum window size before creating a window.
-*/
-static inline PUGL_DEPRECATED_BY("puglSetMinSize") void
-puglInitWindowMinSize(PuglView* view, int width, int height)
-{
-	puglSetMinSize(view, width, height);
-}
-
-/**
-   Set the window aspect ratio range before creating a window.
-
-   The x and y values here represent a ratio of width to height.  To set a
-   fixed aspect ratio, set the minimum and maximum values to the same ratio.
-
-   Note that setting different minimum and maximum constraints does not
-   currenty work on MacOS (the minimum is used), so only setting a fixed aspect
-   ratio works properly across all platforms.
-*/
-static inline PUGL_DEPRECATED_BY("puglSetAspectRatio") void
-puglInitWindowAspectRatio(PuglView* view,
-                          int       minX,
-                          int       minY,
-                          int       maxX,
-                          int       maxY)
-{
-	puglSetAspectRatio(view, minX, minY, maxX, maxY);
-}
-
-/**
-   Set transient parent before creating a window.
-
-   On X11, parent must be a Window.
-   On OSX, parent must be an NSView*.
-*/
-static inline PUGL_DEPRECATED_BY("puglSetTransientFor") void
-puglInitTransientFor(PuglView* view, uintptr_t parent)
-{
-	puglSetTransientFor(view, (PuglNativeWindow)parent);
-}
-
-/**
-   Enable or disable resizing before creating a window.
-
-   @deprecated Use puglSetViewHint() with #PUGL_RESIZABLE.
-*/
-static inline PUGL_DEPRECATED_BY("puglSetViewHint") void
-puglInitResizable(PuglView* view, bool resizable)
-{
-	puglSetViewHint(view, PUGL_RESIZABLE, resizable);
-}
-
-/**
-   Get the current size of the view.
-
-   @deprecated Use puglGetFrame().
-
-*/
-static inline PUGL_DEPRECATED_BY("puglGetFrame") void
-puglGetSize(PuglView* view, int* width, int* height)
-{
-	const PuglRect frame = puglGetFrame(view);
-
-	*width  = (int)frame.width;
-	*height = (int)frame.height;
-}
-
-/**
-   Ignore synthetic repeated key events.
-
-   @deprecated Use puglSetViewHint() with #PUGL_IGNORE_KEY_REPEAT.
-*/
-static inline PUGL_DEPRECATED_BY("puglSetViewHint") void
-puglIgnoreKeyRepeat(PuglView* view, bool ignore)
-{
-	puglSetViewHint(view, PUGL_IGNORE_KEY_REPEAT, ignore);
-}
-
-/**
-   Set a hint before creating a window.
-
-   @deprecated Use puglSetWindowHint().
-*/
-static inline PUGL_DEPRECATED_BY("puglSetViewHint") void
-puglInitWindowHint(PuglView* view, PuglViewHint hint, int value)
-{
-	puglSetViewHint(view, hint, value);
-}
-
-/**
-   Set the parent window before creating a window (for embedding).
-
-   @deprecated Use puglSetWindowParent().
-*/
-static inline PUGL_DEPRECATED_BY("puglSetParentWindow") void
-puglInitWindowParent(PuglView* view, PuglNativeWindow parent)
-{
-	puglSetParentWindow(view, parent);
-}
-
-/**
-   Set the graphics backend to use.
-
-   @deprecated Use puglSetBackend().
-*/
-static inline PUGL_DEPRECATED_BY("puglSetBackend") int
-puglInitBackend(PuglView* view, const PuglBackend* backend)
-{
-	return (int)puglSetBackend(view, backend);
-}
-
-/**
-   Realise a view by creating a corresponding system view or window.
-
-   The view should be fully configured using the above functions before this is
-   called.  This function may only be called once per view.
-
-   @deprecated Use puglRealize(), or just show the view.
-*/
-static inline PUGL_DEPRECATED_BY("puglRealize") PuglStatus
-puglCreateWindow(PuglView* view, const char* title)
-{
-	puglSetWindowTitle(view, title);
-	return puglRealize(view);
-}
-
-/**
-   Block and wait for an event to be ready.
-
-   This can be used in a loop to only process events via puglProcessEvents when
-   necessary.  This function will block indefinitely if no events are
-   available, so is not appropriate for use in programs that need to perform
-   regular updates (e.g. animation).
-
-   @deprecated Use puglPollEvents().
-*/
-PUGL_API PUGL_DEPRECATED_BY("puglPollEvents") PuglStatus
-puglWaitForEvent(PuglView* view);
-
-/**
-   Process all pending window events.
-
-   This handles input events as well as rendering, so it should be called
-   regularly and rapidly enough to keep the UI responsive.  This function does
-   not block if no events are pending.
-
-   @deprecated Use puglDispatchEvents().
-*/
-PUGL_API PUGL_DEPRECATED_BY("puglDispatchEvents") PuglStatus
-puglProcessEvents(PuglView* view);
-
-/**
-   Poll for events that are ready to be processed.
-
-   This polls for events that are ready for any view in the world, potentially
-   blocking depending on `timeout`.
-
-   @param world The world to poll for events.
-
-   @param timeout Maximum time to wait, in seconds.  If zero, the call returns
-   immediately, if negative, the call blocks indefinitely.
-
-   @return #PUGL_SUCCESS if events are read, #PUGL_FAILURE if not, or an error.
-
-   @deprecated Use puglUpdate().
-*/
-PUGL_API PUGL_DEPRECATED_BY("puglUpdate") PuglStatus
-puglPollEvents(PuglWorld* world, double timeout);
-
-/**
-   Dispatch any pending events to views.
-
-   This processes all pending events, dispatching them to the appropriate
-   views.  View event handlers will be called in the scope of this call.  This
-   function does not block, if no events are pending then it will return
-   immediately.
-
-   @deprecated Use puglUpdate().
-*/
-PUGL_API PUGL_DEPRECATED_BY("puglUpdate") PuglStatus
-puglDispatchEvents(PuglWorld* world);
-
-/**
-   Enter the graphics context.
-
-   Note that, unlike some similar libraries, Pugl automatically enters and
-   leaves the graphics context when required and application should not
-   normally do this.  Drawing in Pugl is only allowed during the processing of
-   an expose event.
-
-   However, this can be used to enter the graphics context elsewhere, for
-   example to call any GL functions during setup.
-
-   @param view The view being entered.
-   @param drawing If true, prepare for drawing.
-
-   @deprecated Set up graphics when a #PUGL_CREATE event is received.
-*/
-PUGL_API PUGL_DEPRECATED_BY("PUGL_CREATE") PuglStatus
-puglEnterContext(PuglView* view, bool drawing);
-
-/**
-   Leave the graphics context.
-
-   This must be called after puglEnterContext() with a matching `drawing`
-   parameter.
-
-   @param view The view being left.
-   @param drawing If true, finish drawing, for example by swapping buffers.
-
-   @deprecated Shut down graphics when a #PUGL_DESTROY event is received.
-*/
-PUGL_API PUGL_DEPRECATED_BY("PUGL_DESTROY") PuglStatus
-puglLeaveContext(PuglView* view, bool drawing);
-
-#endif  /* PUGL_DISABLE_DEPRECATED */
-
-/**
-   @}
-   @}
-   @}
-*/
-
-PUGL_END_DECLS
-
-#endif  /* PUGL_PUGL_H */