diff options
Diffstat (limited to 'include/pugl/pugl.h')
| -rw-r--r-- | include/pugl/pugl.h | 1624 |
1 files changed, 1624 insertions, 0 deletions
diff --git a/include/pugl/pugl.h b/include/pugl/pugl.h new file mode 100644 index 0000000..ad24c0d --- /dev/null +++ b/include/pugl/pugl.h @@ -0,0 +1,1624 @@ +/* + 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 */ |