Pugl¶

Pugl is a minimal portability layer for embeddable GUIs. It provides a drawing context and event-based main loop API, which can be used to create graphical applications or embedded views.

Pugl is particularly suitable for plugins, since it has no implicit context or mutable static data, and can be statically linked. The “core” library implements platform support, and depends only on standard system libraries. MacOS, Windows, and X11 are currently supported.

Graphics backends are built as separate libraries, so applications depend only on the APIs that they use. Pugl includes graphics backends for Cairo, OpenGL, and Vulkan. Other graphics APIs can be used by implementing a custom backend.

Usage¶

Using an Installed Version¶

When Pugl is installed, particularly on POSIX systems, pkg-config packages are provided that link with the core platform library and desired backend:

pkg-config --cflags --libs pugl-0
pkg-config --cflags --libs pugl-cairo-0
pkg-config --cflags --libs pugl-gl-0
pkg-config --cflags --libs pugl-vulkan-0

Depending on one of these packages should be all that is necessary to use Pugl. If pkg-config is not available, details on the individual libraries that are installed are available in the README.

Using a Meson Subproject¶

Pugl uses the meson build system, which allows it to be included as a subproject within other meson projects.

To use Pugl as a subproject, copy the source tree (or use a git submodule or subtree) to your subprojects directory, for example to subprojects/pugl, and use the subproject function in meson to include it:

pugl_proj = subproject('pugl')

See the Meson subproject documentation for details.

Vendoring Manually¶

To “vendor” Pugl with projects that use a different build system, the headers in the include subdirectory and sources in src are needed. The include directory needs to be added to the search path for the compiler, and the required source files need to be compiled. It is only necessary to build the needed platform and backend implementations. Due to the modular design, no centralized configuration is needed to enable or disable platform/backend support. However, a few preprocessor symbols can be used to control which X11 features are used, see the top of src/x11.c for details.

Overview¶

The Pugl API revolves around two main objects: the world and the view. An application creates a world to manage top-level state, then creates one or more views to display.

The core API (excluding backend-specific components) is declared in pugl.h:

#include <pugl/pugl.h>

Creating a World¶

The world is the top-level object which represents an instance of Pugl. It handles the connection to the window system, and manages views and the event loop.

An application typically has a single world, which is constructed once on startup and used to drive the main event loop.

Construction¶

A world must be created before any views, and it must outlive all of its views. A world is created with puglNewWorld(), for example:

PuglWorld* world = puglNewWorld(PUGL_PROGRAM, 0);

For a plugin, specify PUGL_MODULE instead. In some cases, it is necessary to pass additional flags. For example, Vulkan requires thread support:

PuglWorld* world = puglNewWorld(PUGL_MODULE, PUGL_WORLD_THREADS)

It is a good idea to set a class name for your project with puglSetWorldString(). This allows the window system to distinguish different applications and, for example, users to set up rules to manage their windows nicely:

puglSetWorldString(world, PUGL_CLASS_NAME, "MyAwesomeProject")

Setting Application Data¶

Pugl will call an event handler in the application with only a view pointer and an event, so there needs to be some way to access the data you use in your application. This is done by setting an opaque handle on the world with puglSetWorldHandle(), for example:

puglSetWorldHandle(world, myApp);

The handle can be later retrieved with puglGetWorldHandle():

MyApp* app = (MyApp*)puglGetWorldHandle(world);

All non-constant data should be accessed via this handle, to avoid problems associated with static mutable data.

Creating a View¶

A view is a drawable region that receives events. You may think of it as a window, though it may be embedded and not represent a top-level system window. [1]

Creating a visible view is a multi-step process. When a new view is created with puglNewView(), it does not yet represent a “real” system view:

PuglView* view = puglNewView(world);

Configuring the Frame¶

Before display, the necessary frame and window attributes should be set. These allow the window system (or plugin host) to arrange the view properly. For example:

const PuglSpan defaultWidth  = 1920;
const PuglSpan defaultHeight = 1080;

puglSetViewString(view, PUGL_WINDOW_TITLE, "My Window");
puglSetSizeHint(view, PUGL_DEFAULT_SIZE, 1920, 1080);
puglSetSizeHint(view, PUGL_MIN_SIZE, 640, 480);
puglSetSizeHint(view, PUGL_MIN_ASPECT, 1, 1);
puglSetSizeHint(view, PUGL_MAX_ASPECT, 16, 9);

There are also several hints for basic attributes that can be set:

puglSetViewHint(view, PUGL_RESIZABLE, PUGL_TRUE);
puglSetViewHint(view, PUGL_IGNORE_KEY_REPEAT, PUGL_TRUE);

Embedding¶

To embed the view in another window, you will need to somehow get the native view handle for the parent, then set it with puglSetParent(). If the parent is a Pugl view, the native handle can be accessed with puglGetNativeView(). For example:

puglSetParent(view, puglGetNativeView(parent));

Setting an Event Handler¶

In order to actually do anything, a view must process events from the system. Pugl dispatches all events to a single event handling function, which is set with puglSetEventFunc():

puglSetEventFunc(view, onEvent);

See Handling Events for details on writing the event handler itself.

Setting View Data¶

Since the event handler is called with only a view pointer and an event, there needs to be some way to access application data associated with the view. Similar to setting application data, this is done by setting an opaque handle on the view with puglSetHandle(), for example:

puglSetHandle(view, myViewData);

The handle can be later retrieved, likely in the event handler, with puglGetHandle():

MyViewData* data = (MyViewData*)puglGetHandle(view);

All non-constant data should be accessed via this handle, to avoid problems associated with static mutable data.

If data is also associated with the world, it can be retrieved via the view using puglGetWorld():

PuglWorld* world = puglGetWorld(view);
MyApp*     app   = (MyApp*)puglGetWorldHandle(world);

Setting a Backend¶

Before being realized, the view must have a backend set with puglSetBackend().

The backend manages the graphics API that will be used for drawing. Pugl includes backends and supporting API for Cairo, OpenGL, and Vulkan.

Using Cairo¶

Cairo-specific API is declared in the cairo.h header:

#include <pugl/cairo.h>

The Cairo backend is provided by puglCairoBackend():

puglSetBackend(view, puglCairoBackend());

No additional configuration is required for Cairo. To draw when handling an expose event, the Cairo context can be accessed with puglGetContext():

cairo_t* cr = (cairo_t*)puglGetContext(view);

Using OpenGL¶

OpenGL-specific API is declared in the gl.h header:

#include <pugl/gl.h>

The OpenGL backend is provided by puglGlBackend():

puglSetBackend(view, puglGlBackend());

Some hints must also be set so that the context can be set up correctly. For example, to use OpenGL 3.3 Core Profile:

puglSetViewHint(view, PUGL_CONTEXT_VERSION_MAJOR, 3);
puglSetViewHint(view, PUGL_CONTEXT_VERSION_MINOR, 3);
puglSetViewHint(view,
                PUGL_CONTEXT_PROFILE,
                PUGL_OPENGL_COMPATIBILITY_PROFILE);

If you need to perform some setup using the OpenGL API, there are two ways to do so.

The OpenGL context is active when PUGL_REALIZE and PUGL_UNREALIZE events are dispatched, so things like creating and destroying shaders and textures can be done then.

Alternatively, if it is cumbersome to set up and tear down OpenGL in the event handler, puglEnterContext() and puglLeaveContext() can be used to manually activate the OpenGL context during application setup. Note, however, that unlike many other APIs, these functions must not be used for drawing. It is only valid to use the OpenGL API for configuration in a manually entered context, rendering will not work. For example:

puglEnterContext(view);
setupOpenGL(myApp);
puglLeaveContext(view);

while (!myApp->quit) {
  puglUpdate(world, 0.0);
}

puglEnterContext(view);
teardownOpenGL(myApp);
puglLeaveContext(view);

Using Vulkan¶

Vulkan-specific API is declared in the vulkan.h header. This header includes Vulkan headers, so if you are dynamically loading Vulkan at runtime, you should define VK_NO_PROTOTYPES before including it.

#define VK_NO_PROTOTYPES

#include <pugl/vulkan.h>

The Vulkan backend is provided by puglVulkanBackend():

puglSetBackend(view, puglVulkanBackend());

Unlike OpenGL, almost all Vulkan configuration is done using the Vulkan API directly. Pugl only provides a portable mechanism to load the Vulkan library and get the functions used to load the rest of the Vulkan API.

Loading Vulkan¶

For maximum compatibility, it is best to not link to Vulkan at compile-time, but instead load the Vulkan API at run-time. To do so, first create a PuglVulkanLoader:

PuglVulkanLoader* loader = puglNewVulkanLoader(world, NULL);

The loader manages the dynamically loaded Vulkan library, so it must be kept alive for as long as the application is using Vulkan. You can get the function used to load Vulkan functions with puglGetInstanceProcAddrFunc():

PFN_vkGetInstanceProcAddr vkGetInstanceProcAddr =
  puglGetInstanceProcAddrFunc(loader);

This vkGetInstanceProcAddr function can be used to load the rest of the Vulkan API. For example, you can use it to get the vkCreateInstance function, then use that to create your Vulkan instance. In practice, you will want to use some loader or wrapper API since there are many Vulkan functions.

For advanced situations, there is also puglGetDeviceProcAddrFunc() which retrieves the vkGetDeviceProcAddr function instead.

The Vulkan loader is provided for convenience, so that applications to not need to write platform-specific code to load Vulkan. Its use it not mandatory and Pugl can be used with Vulkan loaded by some other method.

Linking with Vulkan¶

If you do want to link to the Vulkan library at compile time, note that the Pugl Vulkan backend does not depend on it, so you will have to do so explicitly.

Creating a Surface¶

The details of using Vulkan are far beyond the scope of this documentation, but Pugl provides a portable function, puglCreateSurface(), to get the Vulkan surface for a view. Assuming you have somehow created your VkInstance, you can get the surface for a view using puglCreateSurface():

VkSurfaceKHR* surface = NULL;
puglCreateSurface(puglGetDeviceProcAddrFunc(loader),
                  view,
                  vulkanInstance,
                  NULL,
                  &surface);

Showing the View¶

Once the view is configured, it can be “realized” with puglRealize(). This creates a “real” system view, for example:

PuglStatus status = puglRealize(view);
if (status) {
  fprintf(stderr, "Error realizing view (%s)\n", puglStrerror(status));
}

Note that realizing a view can fail for many reasons, so the return code should always be checked. This is generally the case for any function that interacts with the window system. Most functions also return a PuglStatus, but these checks are omitted for brevity in the rest of this documentation.

A realized view is not initially visible, but can be shown with puglShow():

puglShow(view);

To create an initially visible view, it is also possible to simply call puglShow() right away. The view will be automatically realized if necessary.

Footnotes

Handling Events¶

Events are sent to a view when it has received user input, must be drawn, or in other situations that may need to be handled such as resizing.

Events are sent to the event handler as a PuglEvent union. The type field defines the type of the event and which field of the union is active. The application must handle at least PUGL_CONFIGURE and PUGL_EXPOSE to draw anything, but there are many other event types.

For example, a basic event handler might look something like this:

static PuglStatus
onEvent(PuglView* view, const PuglEvent* event)
{
  MyApp* app = (MyApp*)puglGetHandle(view);

  switch (event->type) {
  case PUGL_REALIZE:
    return setupGraphics(app);
  case PUGL_UNREALIZE:
    return teardownGraphics(app);
  case PUGL_CONFIGURE:
    return resize(app, event->configure.width, event->configure.height);
  case PUGL_EXPOSE:
    return draw(app, view);
  case PUGL_CLOSE:
    return quit(app);
  case PUGL_BUTTON_PRESS:
     return onButtonPress(app, view, event->button);
  default:
    break;
  }

  return PUGL_SUCCESS;
}

Using the Graphics Context¶

Drawing¶

Note that Pugl uses a different drawing model than many libraries, particularly those designed for game-style main loops like SDL and GLFW.

In that style of code, drawing is performed imperatively in the main loop, but with Pugl, the application must draw only while handling an expose event. This is because Pugl supports event-driven applications that only draw the damaged region when necessary, and handles exposure internally to provide optimized and consistent behavior across platforms.

Cairo Context¶

A Cairo context is created for each PuglExposeEvent, and only exists during the handling of that event. Null is returned by puglGetContext() at any other time.

OpenGL Context¶

The OpenGL context is only active while handling realization (PUGL_REALIZE, PUGL_UNREALIZE) and exposure (PUGL_EXPOSE), and can only be used for rendering during exposure.

Note that the OpenGL context is not active while handling configuration. When a PUGL_CONFIGURE is received, the application should record it and prepare accordingly, but only apply it to OpenGL when the view is next exposed.

Vulkan Context¶

With Vulkan, the graphics context is managed by the application rather than Pugl. However, drawing must still only be performed during an expose.

Driving the Event Loop¶

Pugl does not contain any threads or other event loop “magic”. For flexibility, the event loop is driven explicitly by repeatedly calling puglUpdate(), which processes events from the window system and dispatches them to views when necessary.

The exact use of puglUpdate() depends on the application. Plugins should call it with a timeout of 0 in a callback driven by the host. This avoids blocking the main loop, since other plugins and the host itself need to run as well.

A program can use whatever timeout is appropriate: event-driven applications may wait forever by using a timeout of -1, while those that draw continuously may use a significant fraction of the frame period (with enough time left over to render).

Redrawing¶

Occasional redrawing can be requested by calling puglObscureView() or puglObscureRegion(). After these are called, a PuglExposeEvent will be dispatched on the next call to puglUpdate().

For continuous redrawing, obscure the view while handling a PuglUpdateEvent event. This event is sent just before views are redrawn, so it can be used as a hook to expand the update region right before the view is exposed. Anything else that needs to be done every frame can be handled similarly.

Event Dispatching¶

Ideally, pending events are dispatched during a call to puglUpdate(), directly within the scope of that call.

Unfortunately, this is not universally true due to differences between platforms.

MacOS¶

On MacOS, drawing is handled specially and not by the normal event queue mechanism. This means that configure and expose events, and possibly others, may be dispatched to a view outside the scope of a puglUpdate() call. In general, you can not rely on coherent event dispatching semantics on MacOS: the operating system can call into application code at “random” times, and these calls may result in Pugl events being dispatched.

An application that follows the Pugl guidelines should work fine, but there is one significant inconsistency you may encounter on MacOS: posting a redisplay will not wake up a blocked puglUpdate() call.

Windows¶

On Windows, the application has relatively tight control over the event loop, so events are typically dispatched explicitly by puglUpdate(). Drawing is handled by events, so posting a redisplay will wake up a blocked puglUpdate() call.

However, it is possible for the system to dispatch events at other times. So, it is possible for events to be dispatched outside the scope of a puglUpdate() call, but this does not happen in normal circumstances and can largely be ignored.

X11¶

On X11, the application strictly controls event dispatching, and there is no way for the system to call into application code at surprising times. So, all events are dispatched in the scope of a puglUpdate() call.

Recursive Event Loops¶

On Windows and MacOS, the event loop is stalled while the user is resizing the window or, on Windows, has displayed the window menu. This means that puglUpdate() will block until the resize is finished, or the menu is closed.

Pugl dispatches PuglLoopEnterEvent and PuglLoopLeaveEvent events to notify the application of this situation. If you want to continuously redraw during resizing on these platforms, you can schedule a timer with puglStartTimer() when the recursive loop is entered, and post redisplays when handling the PuglTimerEvent. Be sure to remove the timer with puglStopTimer() when the recursive loop is finished.

On X11, there are no recursive event loops, and everything works as usual while the user is resizing the window. There is nothing special about a “live resize” on X11, and the above loop events will never be dispatched.

Using Clipboards¶

Clipboards provide a way to transfer information between different views, including views in different processes.

In Pugl, both “copy and paste” and “drag and drop” interactions are supported by the same clipboard mechanism. Several functions are used for both, and take a PuglClipboard enumerator to distinguish which clipboard the operation applies to.

Because these interactions support transfer of data between processes and negotiation of the data type, each is a multi-step process. As with everything, events are used to notify the application about relevant changes.

Drag and Drop¶

To enable support for receiving a particular type of dragged data, puglRegisterDropType() must be called during setup to register a MIME type. For example, the common case of accepting a list of files is supported by the text/uri-list type.

puglRegisterDropType(view, "text/uri-list");

On Windows, this is the only type that is currently supported. On MacOS and X11, other data types can be used, such as text/plain (which is implicitly UTF-8 encoded), or application/zip:

puglRegisterDropType(view, "text/plain");
puglRegisterDropType(view, "application/zip");

Receiving dropped data begins by receiving a PUGL_DATA_OFFER event. This event signals that data is being “offered” by being dragged (but not yet dropped) over the view:

// ...

case PUGL_DATA_OFFER:
  onDataOffer(view, &event->offer);
  break;

When handling this event, puglGetNumClipboardTypes() and puglGetClipboardType() can be used to enumerate the available data types:

static void
onDataOffer(PuglView* view, const PuglDataOfferEVent* event)
{
  PuglClipboard clipboard = event->clipboard;
  uint32_t      numTypes  = puglGetNumClipboardTypes(view, clipboard);

  for (uint32_t t = 0; t < numTypes; ++t) {
    const char* type = puglGetClipboardType(view, clipboard, t);
    printf("Offered type: %s\n", type);
  }
}

If the view supports dropping one of the data types at the specified cursor location, it can accept the drop with puglAcceptOffer():

for (uint32_t t = 0; t < numTypes; ++t) {
  const char* type = puglGetClipboardType(view, clipboard, t);
  if (!strcmp(type, "text/uri-list")) {
    puglAcceptOffer(view,
                    event,
                    t,
                    0,
                    0,
                    UINT_MAX,
                    UINT_MAX);
  }
}

This process will happen repeatedly while the user drags the item around the view. Different actions may be given which may affect how the drag is presented to the user, for example by changing the mouse cursor. A view region must also be given, which may be used to optimize the exchange or provide user feedback. It is safe, though possibly sub-optimal, to simply specify the entire frame as is done above.

When the item is dropped, Pugl will transfer the data in the appropriate datatype behind the scenes, and send a PUGL_DATA event to signal that the data is ready to be fetched with puglGetClipboard():

// ...

case PUGL_DATA:
  onData(view, &event->data);
  break;

// ...

static void
onData(PuglView* view, const PuglDataEvent* event)
{
  PuglClipboard clipboard = event->clipboard;
  uint32_t      typeIndex = event->typeIndex;

  const char* type = puglGetClipboardType(view, clipboard, typeIndex);

  fprintf(stderr, "Received data type: %s\n", type);

  if (!strcmp(type, "text/plain")) {
    size_t      len  = 0;
    const void* data = puglGetClipboard(view, clipboard, typeIndex, &len);

    printf("Dropped: %s\n", (const char*)data);
  }
}

Copy and Paste¶

Data can be copied to the “general” clipboard with puglSetClipboard():

// ...

if ((event->state & PUGL_MOD_CTRL) && event->key == 'c') {
  const char* someString = /* ... */;

  puglSetClipboard(view,
                   PUGL_CLIPBOARD_GENERAL,
                   "text/plain",
                   someString,
                   strlen(someString) + 1);
}

Pasting data works nearly the same way as receiving dropped data, except the events use PUGL_CLIPBOARD_GENERAL instead of PUGL_CLIPBOARD_DRAG. Unlike dropping, however, the receiving application must itself initiate the transfer, using puglPaste():

if ((event->state & PUGL_MOD_CTRL) && event->key == 'v') {
  puglPaste(view);
}

This will result in a PUGL_DATA_OFFER event being sent as above, which must be accepted to ultimately receive the data in the desired data type.

Shutting Down¶

When a view is closed, it will receive a PuglCloseEvent. An application may also set a flag based on user input or other conditions, which can be used to break out of the main loop and stop calling puglUpdate().

When the main event loop has finished running, any views and the world need to be destroyed, in that order. For example:

puglFreeView(view);
puglFreeWorld(world);

Pugl C API¶

Geometry Types¶

typedef int16_t PuglCoord¶

A pixel coordinate within/of a view.

This is used to represent coordinates in two different spaces, depending on context: parent-relative and view-relative.

Parent-relative coordinates of a view are relative to the top-left of the parent it’s embedded in, or to that of a system-specific root. Top-level positions should be between -16000 and 16000.

View-relative coordinates in a view are relative to the top-left of the view.

typedef uint16_t PuglSpan¶

A pixel span (width or height) within/of a view.

The width and height of a view should be between 1 and 10000.

struct PuglArea¶: A 2-dimensional size within/of a view.

struct PuglPoint¶: A 2-dimensional position within/of a view.

Events¶

Management Events¶

PUGL_MAX_VIEW_STYLE_FLAG¶

PuglViewStyleFlag.PUGL_VIEW_STYLE_DEMANDING

The maximum PuglViewStyleFlag value.

typedef PuglAnyEvent PuglCloseEvent¶

View close event.

This is sent when the view is to be closed, for example when the user clicks the close button.

typedef PuglAnyEvent PuglLoopEnterEvent¶

Recursive loop enter event.

This is sent when the window system enters a recursive loop. While in the recursive loop, the main loop will be stalled and no expose events will be received. A typical use is to install a timer to perform continuous actions, such as drawing.

MacOS: A recursive loop is entered while the window is being live resized.
Windows: A recursive loop is entered while the window is being live resized or the menu is shown.
X11: A recursive loop is never entered and the event loop runs as usual while the view is being resized.

typedef PuglAnyEvent PuglLoopLeaveEvent¶

Recursive loop leave event.

This is sent after a loop enter event when the recursive loop is finished and normal iteration will continue.

typedef PuglAnyEvent PuglRealizeEvent¶

View realize event.

This is sent when a view is realized before it’s first displayed, with the graphics context entered (but not prepared to draw). This can be used to set up the graphics system, for example by loading OpenGL extensions.

typedef PuglAnyEvent PuglUnrealizeEvent¶

View unrealize event.

This counterpart to PuglRealizeEvent is sent when the view will no longer be displayed. This can be used to tear down the graphics system, or free any resources allocated when the view was realized.

typedef uint32_t PuglViewStyleFlags¶: Bitwise OR of PuglViewStyleFlag values.

enum PuglViewStyleFlag¶

View style flags.

Style flags reflect special modes and states supported by the window system. Applications can monitor or manipulate them to improve integration.

enumerator PUGL_VIEW_STYLE_MAPPED¶: View is mapped to a real window and potentially visible.

enumerator PUGL_VIEW_STYLE_MODAL¶: View is modal, typically a dialog box of its transient parent.

enumerator PUGL_VIEW_STYLE_ABOVE¶: View should be above most others.

enumerator PUGL_VIEW_STYLE_BELOW¶: View should be below most others.

enumerator PUGL_VIEW_STYLE_HIDDEN¶: View is minimized, shaded, or otherwise invisible.

enumerator PUGL_VIEW_STYLE_TALL¶: View is maximized to fill the screen vertically.

enumerator PUGL_VIEW_STYLE_WIDE¶: View is maximized to fill the screen horizontally.

enumerator PUGL_VIEW_STYLE_FULLSCREEN¶: View is enlarged to fill the entire screen with no decorations.

enumerator PUGL_VIEW_STYLE_RESIZING¶: View is being resized.

enumerator PUGL_VIEW_STYLE_DEMANDING¶: View is ready for input or otherwise demanding attention.

struct PuglConfigureEvent¶

View configure (resize/move) event.

This is sent whenever the view is resized or moved. The graphics context isn’t active during a configure event, so these values should be saved if necessary and applied the next time the view is exposed.

PuglEventType type¶: PuglEventType.PUGL_CONFIGURE

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

PuglCoord x¶: Parent-relative X coordinate of view.

PuglCoord y¶: Parent-relative Y coordinate of view.

PuglSpan width¶: Width of view.

PuglSpan height¶: Height of view.

PuglViewStyleFlags style¶: Bitwise OR of PuglViewStyleFlag flags.

Update Events¶

typedef PuglAnyEvent PuglUpdateEvent¶

View update event.

This is sent near the end of a main loop iteration when the view is potentially about to be redrawn. It can be used to mark regions for exposure with puglObscureView() or puglObscureRegion(). For example, to continuously animate, obscure the view whenever an update event is received, then receive and handle the expose event(s) shortly afterwards.

struct PuglExposeEvent¶

Expose event requiring a redraw.

This is sent when a region needs to be redrawn, with the graphics context entered and activated for drawing. The application must completely draw the given region.

PuglEventType type¶: PuglEventType.PUGL_EXPOSE

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

PuglCoord x¶: View-relative top-left X coordinate of region.

PuglCoord y¶: View-relative top-left Y coordinate of region.

PuglSpan width¶: Width of exposed region.

PuglSpan height¶: Height of exposed region.

Keyboard Events¶

typedef uint32_t PuglMods¶: Bitwise OR of PuglMod values.

enum PuglCrossingMode¶

Reason for a PuglCrossingEvent.

enumerator PUGL_CROSSING_NORMAL¶: Crossing due to pointer motion.

enumerator PUGL_CROSSING_GRAB¶: Crossing due to a grab.

enumerator PUGL_CROSSING_UNGRAB¶: Crossing due to a grab release.

enum PuglKey¶

Keyboard key codepoints.

All keys are identified by a Unicode code point in PuglKeyEvent.key. This enumeration defines constants for special keys that don’t 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 don’t 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.

enumerator PUGL_KEY_NONE¶: Sentinel value for no key.

enumerator PUGL_KEY_BACKSPACE¶: Backspace.

enumerator PUGL_KEY_TAB¶: Tab.

enumerator PUGL_KEY_ENTER¶: Enter.

enumerator PUGL_KEY_ESCAPE¶: Escape.

enumerator PUGL_KEY_DELETE¶: Delete.

enumerator PUGL_KEY_SPACE¶: Space.

enumerator PUGL_KEY_F1¶: F1.

enumerator PUGL_KEY_F2¶: F2.

enumerator PUGL_KEY_F3¶: F3.

enumerator PUGL_KEY_F4¶: F4.

enumerator PUGL_KEY_F5¶: F5.

enumerator PUGL_KEY_F6¶: F6.

enumerator PUGL_KEY_F7¶: F7.

enumerator PUGL_KEY_F8¶: F8.

enumerator PUGL_KEY_F9¶: F9.

enumerator PUGL_KEY_F10¶: F10.

enumerator PUGL_KEY_F11¶: F11.

enumerator PUGL_KEY_F12¶: F12.

enumerator PUGL_KEY_PAGE_UP¶: Page Up.

enumerator PUGL_KEY_PAGE_DOWN¶: Page Down.

enumerator PUGL_KEY_END¶: End.

enumerator PUGL_KEY_HOME¶: Home.

enumerator PUGL_KEY_LEFT¶: Left.

enumerator PUGL_KEY_UP¶: Up.

enumerator PUGL_KEY_RIGHT¶: Right.

enumerator PUGL_KEY_DOWN¶: Down.

enumerator PUGL_KEY_PRINT_SCREEN¶: Print Screen.

enumerator PUGL_KEY_INSERT¶: Insert.

enumerator PUGL_KEY_PAUSE¶: Pause/Break.

enumerator PUGL_KEY_MENU¶: Menu.

enumerator PUGL_KEY_NUM_LOCK¶: Num Lock.

enumerator PUGL_KEY_SCROLL_LOCK¶: Scroll Lock.

enumerator PUGL_KEY_CAPS_LOCK¶: Caps Lock.

enumerator PUGL_KEY_SHIFT_L¶: Left Shift.

enumerator PUGL_KEY_SHIFT_R¶: Right Shift.

enumerator PUGL_KEY_CTRL_L¶: Left Control.

enumerator PUGL_KEY_CTRL_R¶: Right Control.

enumerator PUGL_KEY_ALT_L¶: Left Alt.

enumerator PUGL_KEY_ALT_R¶: Right Alt / AltGr.

enumerator PUGL_KEY_SUPER_L¶: Left Super.

enumerator PUGL_KEY_SUPER_R¶: Right Super.

enumerator PUGL_KEY_PAD_0¶: Keypad 0.

enumerator PUGL_KEY_PAD_1¶: Keypad 1.

enumerator PUGL_KEY_PAD_2¶: Keypad 2.

enumerator PUGL_KEY_PAD_3¶: Keypad 3.

enumerator PUGL_KEY_PAD_4¶: Keypad 4.

enumerator PUGL_KEY_PAD_5¶: Keypad 5.

enumerator PUGL_KEY_PAD_6¶: Keypad 6.

enumerator PUGL_KEY_PAD_7¶: Keypad 7.

enumerator PUGL_KEY_PAD_8¶: Keypad 8.

enumerator PUGL_KEY_PAD_9¶: Keypad 9.

enumerator PUGL_KEY_PAD_ENTER¶: Keypad Enter.

enumerator PUGL_KEY_PAD_PAGE_UP¶: Keypad Page Up.

enumerator PUGL_KEY_PAD_PAGE_DOWN¶: Keypad Page Down.

enumerator PUGL_KEY_PAD_END¶: Keypad End.

enumerator PUGL_KEY_PAD_HOME¶: Keypad Home.

enumerator PUGL_KEY_PAD_LEFT¶: Keypad Left.

enumerator PUGL_KEY_PAD_UP¶: Keypad Up.

enumerator PUGL_KEY_PAD_RIGHT¶: Keypad Right.

enumerator PUGL_KEY_PAD_DOWN¶: Keypad Down.

enumerator PUGL_KEY_PAD_CLEAR¶: Keypad Clear/Begin.

enumerator PUGL_KEY_PAD_INSERT¶: Keypad Insert.

enumerator PUGL_KEY_PAD_DELETE¶: Keypad Delete.

enumerator PUGL_KEY_PAD_EQUAL¶: Keypad Equal.

enumerator PUGL_KEY_PAD_MULTIPLY¶: Keypad Multiply.

enumerator PUGL_KEY_PAD_ADD¶: Keypad Add.

enumerator PUGL_KEY_PAD_SEPARATOR¶: Keypad Separator.

enumerator PUGL_KEY_PAD_SUBTRACT¶: Keypad Subtract.

enumerator PUGL_KEY_PAD_DECIMAL¶: Keypad Decimal.

enumerator PUGL_KEY_PAD_DIVIDE¶: Keypad Divide.

enum PuglMod¶

Keyboard modifier flags.

enumerator PUGL_MOD_SHIFT¶: Shift pressed.

enumerator PUGL_MOD_CTRL¶: Control pressed.

enumerator PUGL_MOD_ALT¶: Alt/Option pressed.

enumerator PUGL_MOD_SUPER¶: Super/Command/Windows pressed.

enumerator PUGL_MOD_NUM_LOCK¶: Num lock enabled.

enumerator PUGL_MOD_SCROLL_LOCK¶: Scroll lock enabled.

enumerator PUGL_MOD_CAPS_LOCK¶: Caps lock enabled.

struct PuglFocusEvent¶

Keyboard focus event.

This 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.

PuglEventType type¶: PuglEventType.PUGL_FOCUS_IN or PuglEventType.PUGL_FOCUS_OUT

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

PuglCrossingMode mode¶: Reason for focus change.

struct PuglKeyEvent¶

Key press or release event.

This represents low-level key presses and releases. This can be used for “direct” keyboard handling 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 isn’t portable and differs between platforms and hardware.

PuglEventType type¶: PuglEventType.PUGL_KEY_PRESS or PuglEventType.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.

struct PuglTextEvent¶

Character input event.

This 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 isn’t 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.

PuglEventType type¶: PuglEventType.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.

Pointer Events¶

enum PuglScrollDirection¶

Scroll direction.

Describes the direction of a PuglScrollEvent 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.

enumerator PUGL_SCROLL_UP¶: Scroll up.

enumerator PUGL_SCROLL_DOWN¶: Scroll down.

enumerator PUGL_SCROLL_LEFT¶: Scroll left.

enumerator PUGL_SCROLL_RIGHT¶: Scroll right.

enumerator PUGL_SCROLL_SMOOTH¶: Smooth scroll in any direction.

struct PuglButtonEvent¶

Button press or release event.

Button numbers start from 0, and are ordered: primary, secondary, middle. So, on a typical right-handed mouse, the button numbers are:

Left: 0 Right: 1 Middle (often a wheel): 2

Higher button numbers are reported in the same order they are represented on the system. There is no universal standard here, but buttons 3 and 4 are typically a pair of buttons or a rocker, which are usually bound to “back” and “forward” operations.

Note that these numbers may differ from those used on the underlying platform, since they are manipulated to provide a consistent portable API.

PuglEventType type¶: PuglEventType.PUGL_BUTTON_PRESS or PuglEventType.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 0.

struct PuglCrossingEvent¶

Pointer enter or leave event.

This 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.

PuglEventType type¶: PuglEventType.PUGL_POINTER_IN or PuglEventType.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.

struct PuglMotionEvent¶

Pointer motion event.

PuglEventType type¶: PuglEventType.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.

struct PuglScrollEvent¶

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.

PuglEventType type¶: PuglEventType.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.

Custom Events¶

struct PuglClientEvent¶

Custom client message event.

This is a custom event sent to a view with puglSendEvent(), which wakes up the event loop and delivers two pointer-sized data fields. These client-specific fields are opaque to Pugl and aren’t interpreted in any way.

PuglEventType type¶: PuglEventType.PUGL_CLIENT

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

uintptr_t data1¶: Client-specific data.

uintptr_t data2¶: Client-specific data.

struct PuglTimerEvent¶

Timer event.

This is sent while the timer with the given id is activated at the regular interval specified in the corresponding puglStartTimer() call. Other platform-specific timers may exist, so applications must always check the id field before reacting to a timer event.

PuglEventType type¶: PuglEventType.PUGL_TIMER

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

uintptr_t id¶: Timer ID.

Clipboard Events¶

enum PuglClipboard¶

A system clipboard.

A clipboard provides a mechanism for transferring data between views, including views in different processes. Clipboards are used for both “copy and paste” and “drag and drop” interactions.

enumerator PUGL_CLIPBOARD_GENERAL¶: General clipboard for copy/pasted data.

enumerator PUGL_CLIPBOARD_DRAG¶: Drag clipboard for drag and drop data.

enum PuglDataAction¶

An action that can be performed on data from a clipboard.

This is given when accepting a data offer, so the system can provide user feedback, for example by changing the cursor or showing an animation.

enumerator PUGL_DATA_ACTION_COPY¶: Data will be copied.

enumerator PUGL_DATA_ACTION_LINK¶: Data will be linked to.

enumerator PUGL_DATA_ACTION_MOVE¶: Data will be moved.

enumerator PUGL_DATA_ACTION_PRIVATE¶: Unspecified private action.

struct PuglDataEvent¶

Clipboard data event.

This is sent after accepting a data offer when the data has been retrieved and converted. While handling this event, the data can be accessed with puglGetClipboard().

PuglEventType type¶: PuglEventType.PUGL_DATA

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

double time¶: Time in seconds.

double x¶: View-relative X coordinate.

double y¶: View-relative Y coordinate.

PuglClipboard clipboard¶: Clipboard with available data.

uint32_t typeIndex¶: Index of datatype.

struct PuglDataOfferEvent¶

Clipboard data offer event.

This is sent when a clipboard has data present, possibly with several datatypes. While handling this event, the types can be investigated with puglGetClipboardType() to decide whether to accept the offer with puglAcceptOffer().

PuglEventType type¶: PuglEventType.PUGL_DATA_OFFER

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

double time¶: Time in seconds.

double x¶: View-relative X coordinate.

double y¶: View-relative Y coordinate.

PuglClipboard clipboard¶: Clipboard with available data.

typedef uint32_t PuglEventFlags¶: Bitwise OR of PuglEventFlag values.

enum PuglEventFlag¶

Common flags for all event types.

enumerator PUGL_IS_SEND_EVENT¶: Event is synthetic.

enumerator PUGL_IS_HINT¶: Event is a hint (not direct user input)

enum PuglEventType¶

The type of a PuglEvent.

enumerator PUGL_NOTHING¶: No event.

enumerator PUGL_REALIZE¶: View realized, a PuglRealizeEvent.

enumerator PUGL_UNREALIZE¶: View unrealized, a PuglUnrealizeEvent.

enumerator PUGL_CONFIGURE¶: View configured, a PuglConfigureEvent.

enumerator PUGL_UPDATE¶: View update before draw, a PuglUpdateEvent.

enumerator PUGL_EXPOSE¶: View expose during draw, a PuglExposeEvent.

enumerator PUGL_CLOSE¶: View will be closed, a PuglCloseEvent.

enumerator PUGL_FOCUS_IN¶: Keyboard focus entered view, a PuglFocusEvent.

enumerator PUGL_FOCUS_OUT¶: Keyboard focus left view, a PuglFocusEvent.

enumerator PUGL_KEY_PRESS¶: Key pressed, a PuglKeyEvent.

enumerator PUGL_KEY_RELEASE¶: Key released, a PuglKeyEvent.

enumerator PUGL_TEXT¶: Character entered, a PuglTextEvent.

enumerator PUGL_POINTER_IN¶: Pointer entered view, a PuglCrossingEvent.

enumerator PUGL_POINTER_OUT¶: Pointer left view, a PuglCrossingEvent.

enumerator PUGL_BUTTON_PRESS¶: Mouse button pressed, a PuglButtonEvent.

enumerator PUGL_BUTTON_RELEASE¶: Mouse button released, a PuglButtonEvent.

enumerator PUGL_MOTION¶: Pointer moved, a PuglMotionEvent.

enumerator PUGL_SCROLL¶: Scrolled, a PuglScrollEvent.

enumerator PUGL_CLIENT¶: Custom client message, a PuglClientEvent.

enumerator PUGL_TIMER¶: Timer triggered, a PuglTimerEvent.

enumerator PUGL_LOOP_ENTER¶: Recursive loop entered, a PuglLoopEnterEvent.

enumerator PUGL_LOOP_LEAVE¶: Recursive loop left, a PuglLoopLeaveEvent.

enumerator PUGL_DATA_OFFER¶: Data offered from clipboard, a PuglDataOfferEvent.

enumerator PUGL_DATA¶: Data available from clipboard, a PuglDataEvent.

struct PuglAnyEvent¶

Common header for all events.

PuglEventType type¶: Event type.

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

union PuglEvent¶

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 PuglEventType.PUGL_REALIZE, PuglEventType.PUGL_UNREALIZE, and PuglEventType.PUGL_EXPOSE, but only enabled for drawing for PuglEventType.PUGL_EXPOSE.

PuglAnyEvent any¶: Valid for all event types.

PuglEventType type¶: Event type.

PuglButtonEvent button¶: PuglEventType.PUGL_BUTTON_PRESS, PuglEventType.PUGL_BUTTON_RELEASE

PuglConfigureEvent configure¶: PuglEventType.PUGL_CONFIGURE

PuglExposeEvent expose¶: PuglEventType.PUGL_EXPOSE

PuglKeyEvent key¶: PuglEventType.PUGL_KEY_PRESS, PuglEventType.PUGL_KEY_RELEASE

PuglTextEvent text¶: PuglEventType.PUGL_TEXT

PuglCrossingEvent crossing¶: PuglEventType.PUGL_POINTER_IN, PuglEventType.PUGL_POINTER_OUT

PuglMotionEvent motion¶: PuglEventType.PUGL_MOTION

PuglScrollEvent scroll¶: PuglEventType.PUGL_SCROLL

PuglFocusEvent focus¶: PuglEventType.PUGL_FOCUS_IN, PuglEventType.PUGL_FOCUS_OUT

PuglClientEvent client¶: PuglEventType.PUGL_CLIENT

PuglTimerEvent timer¶: PuglEventType.PUGL_TIMER

PuglDataOfferEvent offer¶: PuglEventType.PUGL_DATA_OFFER

PuglDataEvent data¶: PuglEventType.PUGL_DATA

Status¶

enum PuglStatus¶

Return status code.

enumerator PUGL_SUCCESS¶: Success.

enumerator PUGL_FAILURE¶: Non-fatal failure.

enumerator PUGL_UNKNOWN_ERROR¶: Unknown system error.

enumerator PUGL_BAD_BACKEND¶: Invalid or missing backend.

enumerator PUGL_BAD_CONFIGURATION¶: Invalid view configuration.

enumerator PUGL_BAD_PARAMETER¶: Invalid parameter.

enumerator PUGL_BAD_CALL¶: Invalid call.

enumerator PUGL_BACKEND_FAILED¶: Backend initialization failed.

enumerator PUGL_REGISTRATION_FAILED¶: Class registration failed.

enumerator PUGL_REALIZE_FAILED¶: System view realization failed.

enumerator PUGL_SET_FORMAT_FAILED¶: Failed to set pixel format.

enumerator PUGL_CREATE_CONTEXT_FAILED¶: Failed to create drawing context.

enumerator PUGL_UNSUPPORTED¶: Unsupported operation.

enumerator PUGL_NO_MEMORY¶: Failed to allocate memory.

const char *puglStrerror(PuglStatus status)¶: Return a string describing a status code.

String Hints¶

PUGL_NUM_STRING_HINTS¶

3U

The number of PuglStringHint values.

enum PuglStringHint¶

A string property for configuration.

enumerator PUGL_APPLICATION_NAME¶

The application name.

This is a stable identifier for the application, usually something like “my_app” which is the same as the name of the executable. It’s used as the applications name for X11 resources.

enumerator PUGL_CLASS_NAME¶

The application or window class name.

This is a stable identifier for the application window class, a short camel-case name like “MyApp”. This should be the same for every instance of the application, but different from any other application. On X11 and Windows, it’s used to set the class name of windows, which is used for window management and configuration.

enumerator PUGL_WINDOW_TITLE¶

The title of the window or application.

This is used by the system to display a title for the application or window, for example in title bars or window/application switchers. It’s only used to display a label to the user, not as an identifier, and can change over time to reflect the current state of the application. For example, it’s common for programs to add the name of the current document, like “myfile.txt - Fancy Editor”.

World¶

typedef struct PuglWorldImpl PuglWorld¶

The “world” of application state.

The world represents everything that isn’t 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 uint32_t PuglWorldFlags¶: Bitwise OR of PuglWorldFlag values.

enum PuglWorldFlag¶

World flags.

enumerator PUGL_WORLD_THREADS¶

Set up support for threads if necessary.

X11: Calls XInitThreads() which is required for some drivers.

enum PuglWorldType¶

The type of a World.

enumerator PUGL_PROGRAM¶: Top-level application.

enumerator PUGL_MODULE¶: Plugin or module within a larger application.

void puglFreeWorld(PuglWorld *world)¶: Free a world allocated with puglNewWorld()

void *puglGetNativeWorld(PuglWorld *world)¶

Return the native world handle.

The “native world” is a system-specific handle that’s shared across an entire program or module. It serves as a common denominator between Pugl, applications, and the windowing system API.

X11: Returns a pointer to the Display.

MacOS: Returns a pointer to the NSApplication.

Windows: Returns the HMODULE of the calling process.

double puglGetTime(const PuglWorld *world)¶

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.

void *puglGetWorldHandle(PuglWorld *world)¶: Get the user data for the world.

const char *puglGetWorldString(const PuglWorld *world, PuglStringHint key)¶

Get a world or application string property.

The returned string should be accessed immediately or copied if necessary, it may be invalidated by any change to the same world.

PuglWorld *puglNewWorld(PuglWorldType type, PuglWorldFlags flags)¶

Create a new world.

Parameters:

type – The type, which dictates what this world is responsible for.
flags – Flags to control world features.

Returns:

A new world, which must be later freed with puglFreeWorld().

void puglSetWorldHandle(PuglWorld *world, void *handle)¶

Set the user data for the world.

This is usually a pointer to a struct that contains all the state shared by any views.

The handle is opaque to Pugl and isn’t interpreted in any way.

PuglStatus puglSetWorldString(PuglWorld *world, PuglStringHint key, const char *value)¶

Set a string property to configure the world or application.

The string value only needs to be valid for the duration of this call, it will be copied if necessary.

PuglStatus puglUpdate(PuglWorld *world, double timeout)¶

Update by processing events from the window system.

This runs a single iteration of the main loop, and needs to be called repeatedly to update all views.

Plugins should always use a timeout of zero to avoid blocking the host. For continuously animating programs, a timeout that’s a reasonable fraction of the ideal frame period should be used, to minimize input latency by ensuring that as many input events are consumed as possible before drawing.

Parameters:

world – The world to update.
timeout – If zero, then this call won’t block. If positive, then events will be processed for that amount of time, starting from when this function was called. If negative, then this call will block until an event occurs.

Returns:

PuglStatus.PUGL_SUCCESS if events are read, PuglStatus.PUGL_FAILURE if no events are read, or an error.

Backend¶

Cairo¶

Cairo graphics support.

const PuglBackend *puglCairoBackend(void)¶

Cairo graphics backend accessor.

Pass the returned value to puglSetBackend() to draw to a view with Cairo.

OpenGL¶

OpenGL graphics support.

typedef void (*PuglGlFunc)(void)¶: OpenGL extension function.

PuglStatus puglEnterContext(PuglView *view)¶

Enter the OpenGL context.

This can be used to enter the graphics context in unusual situations, for doing things like loading textures. Note that this must not be used for drawing, which may only be done while processing an expose event.

PuglGlFunc puglGetProcAddress(const char *name)¶

Return the address of an OpenGL extension function.

The returned void function pointer must be cast to the appropriate function type (defined by the OpenGL specification) in order to be called.

const PuglBackend *puglGlBackend(void)¶

OpenGL graphics backend.

Pass the returned value to puglSetBackend() to draw to a view with OpenGL.

PuglStatus puglLeaveContext(PuglView *view)¶

Leave the OpenGL context.

This must only be called after puglEnterContext().

Stub¶

Native graphics support.

const PuglBackend *puglStubBackend(void)¶

Stub graphics backend accessor.

This backend just creates a simple native window without setting up any portable graphics API.

Vulkan¶

Vulkan graphics support.

Vulkan support differs from OpenGL because almost all most configuration is done using the Vulkan API itself, rather than by setting view hints to configure the context. Pugl only provides a minimal loader for loading the Vulkan library, and a portable function to create a Vulkan surface for a view, which hides the platform-specific implementation details.

typedef struct PuglVulkanLoaderImpl PuglVulkanLoader¶

Dynamic Vulkan loader.

This can be used to dynamically load the Vulkan library. Applications or plugins shouldn’t link against the Vulkan library, but instead use this at runtime. This ensures that things will work on as many systems as possible, and allows errors to be handled gracefully.

This isn’t a “loader” in the sense of loading all the required Vulkan functions (which is the application’s responsibility), but just a minimal implementation to portably load the Vulkan library and get the two functions that are used to load everything else.

Note that this owns the loaded Vulkan library, so it must outlive all use of the Vulkan API.

VkResult puglCreateSurface(PFN_vkGetInstanceProcAddr vkGetInstanceProcAddr, PuglView *view, VkInstance instance, const VkAllocationCallbacks *allocator, VkSurfaceKHR *surface)¶

Create a Vulkan surface for a Pugl view.

Parameters:

vkGetInstanceProcAddr – Accessor for Vulkan functions.
view – The view the surface is to be displayed on.
instance – The Vulkan instance.
allocator – Vulkan allocation callbacks, may be NULL.
surface – Pointed to a newly created Vulkan surface.

Returns:

VK_SUCCESS on success, or a Vulkan error code.

void puglFreeVulkanLoader(PuglVulkanLoader *loader)¶

Free a loader created with puglNewVulkanLoader().

Note that this closes the Vulkan library, so the Vulkan API can no longer be used.

PFN_vkGetDeviceProcAddr puglGetDeviceProcAddrFunc(const PuglVulkanLoader *loader)¶

Return the vkGetDeviceProcAddr function.

Returns:: Null if the Vulkan library does not contain this function (which is unlikely and indicates a broken system).

const char *const *puglGetInstanceExtensions(uint32_t *count)¶

Return the Vulkan instance extensions required to draw to a PuglView.

This simply returns static strings, it does not access Vulkan or the window system. The returned array always contains at least “VK_KHR_surface”.

Parameters:

count – The number of extensions in the returned array.

Returns:

An array of extension name strings.

PFN_vkGetInstanceProcAddr puglGetInstanceProcAddrFunc(const PuglVulkanLoader *loader)¶

Return the vkGetInstanceProcAddr function.

Returns:: Null if the Vulkan library does not contain this function (which is unlikely and indicates a broken system).

PuglVulkanLoader *puglNewVulkanLoader(PuglWorld *world, const char *libraryName)¶

Create a new dynamic loader for Vulkan functions.

This dynamically loads the Vulkan library and gets the load functions from it.

Parameters:

world – The world the returned loader is a part of.
libraryName – The name of the Vulkan library to load, or null. Typically, this is left unset, which will load the standard Vulkan library for the current platform. It can be set to an alternative name, or an absolute path, to support special packaging scenarios or unusual system configurations. This name is passed directly to the underlying platform library loading function (dlopen or LoadLibrary).

Returns:

A new Vulkan loader, or null on failure.

const PuglBackend *puglVulkanBackend(void)¶

Vulkan graphics backend.

Pass the returned value to puglSetBackend() to draw to a view with Vulkan.

typedef struct PuglBackendImpl PuglBackend¶

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 realizing a view.

View¶

Setup¶

Functions for creating and destroying a view.

void puglFreeView(PuglView *view)¶: Free a view created with puglNewView()

const PuglBackend *puglGetBackend(const PuglView *view)¶: Return the graphics backend used by a view.

void *puglGetHandle(PuglView *view)¶: Get the user data for a view.

double puglGetScaleFactor(const PuglView *view)¶

Return the scale factor of the view.

This factor describe how large UI elements (especially text) should be compared to “normal”. For example, 2.0 means the UI should be drawn twice as large. “Normal” is loosely defined as a typical default size on a “standard DPI” display (around 96 DPI).

int puglGetViewHint(const PuglView *view, PuglViewHint hint)¶

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.

const char *puglGetViewString(const PuglView *view, PuglStringHint key)¶

Get a view string property.

The returned string should be accessed immediately, or copied. It may become invalid upon any call to any function that manipulates the same view.

PuglWorld *puglGetWorld(PuglView *view)¶: Return the world that view is a part of.

PuglView *puglNewView(PuglWorld *world)¶

Create a new view.

A newly created view doesn’t correspond to a real system view or window until it’s configured and realized.

PuglStatus puglRegisterDropType(PuglView *view, const char *type)¶

Register support for accepting a type of dropped data.

Before realizing the view, this should be called to register every type of dragged data the view may accept when dropped.

Parameters:

view – The view that will accept this type of dropped data.
type – The MIME type to accept, “text/plain” is assumed if NULL.

Returns:

PuglStatus.PUGL_SUCCESS, or PuglStatus.PUGL_UNSUPPORTED if the system doesn’t support this type.

PuglStatus puglSetBackend(PuglView *view, const PuglBackend *backend)¶

Set the graphics backend to use for a view.

This must be called once to set the graphics backend before calling puglRealize().

Pugl includes a “stub” backend for platform-specific applications, and several portable backends:

These backends are modules that aren’t compiled in to 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.

PuglStatus puglSetEventFunc(PuglView *view, PuglEventFunc eventFunc)¶: Set the function to call when an event occurs.

void puglSetHandle(PuglView *view, void *handle)¶

Set the user data for a view.

This is usually a pointer to a struct that contains all the state needed by a view. Everything needed to process events should be stored here, not in static variables.

The handle is opaque to Pugl and isn’t interpreted in any way.

PuglStatus puglSetViewHint(PuglView *view, PuglViewHint hint, int value)¶

Set a hint to configure view properties.

This only has an effect when called before puglRealize().

PuglStatus puglSetViewString(PuglView *view, PuglStringHint key, const char *value)¶

Set a string property to configure view properties.

This is similar to puglSetViewHint() but sets hints with string values. The string value only needs to be valid for the duration of this call, it will be copied if necessary.

Frame¶

Functions for working with the position and size of a view.

PuglPoint puglGetPositionHint(const PuglView *view, PuglPositionHint hint)¶

Get a position hint for the view.

This can be used to get the default or current position of a view, in screen coordinates with an upper left origin.

PuglArea puglGetSizeHint(const PuglView *view, PuglSizeHint hint)¶

Get a size hint for the view.

This can be used to get the default, current, minimum, and maximum size of a view, as well as the supported range of aspect ratios.

PuglStatus puglSetPositionHint(PuglView *view, PuglPositionHint hint, int x, int y)¶

Set a position hint for the view.

This can be used to set the default or current position of a view.

This should be called before puglRealize() so the initial window for the view can be configured correctly. It may also be used dynamically after the window is realized, for some hints.

Returns:: An error code on failure, but always succeeds if the view isn’t yet realized.

PuglStatus puglSetSizeHint(PuglView *view, PuglSizeHint hint, unsigned width, unsigned height)¶

Set a size hint for the view.

This can be used to set the default, current, minimum, and maximum size of a view, as well as the supported range of aspect ratios.

This should be called before puglRealize() so the initial window for the view can be configured correctly. It may also be used dynamically after the window is realized, for some hints.

Returns:: An error code on failure, but always succeeds if the view isn’t yet realized.

Window¶

Functions to control the top-level window of a view.

enum PuglShowCommand¶

A command to control the behaviour of puglShow()

enumerator PUGL_SHOW_PASSIVE¶

Realize and show the window without intentionally raising it.

This will weakly “show” the window but without making any effort to raise it. Depending on the platform or system configuration, the window may be raised above some others regardless.

enumerator PUGL_SHOW_RAISE¶

Raise the window to the top of the application’s stack.

This is the normal “well-behaved” way to show and raise the window, which should be used in most cases.

enumerator PUGL_SHOW_FORCE_RAISE¶

Aggressively force the window to be raised to the top.

This will attempt to raise the window to the top, even if this isn’t the active application, or if doing so would otherwise go against the platform’s guidelines. This generally shouldn’t be used, and isn’t guaranteed to work. On modern Windows systems, the active application must explicitly grant permission for others to steal the foreground from it.

PuglNativeView puglGetNativeView(const PuglView *view)¶: Return the native window handle.

PuglNativeView puglGetParent(const PuglView *view)¶

Return the native view that the view is embedded in.

Returns:: The native view handle of the parent that view is embedded in, or zero (if view is top-level or unrealized).

PuglNativeView puglGetTransientParent(const PuglView *view)¶

Return the transient parent of the window.

Returns:: The native handle to the window this view is a transient child of, or null.

PuglViewStyleFlags puglGetViewStyle(const PuglView *view)¶: Return the style flags currently set for a view.

bool puglGetVisible(const PuglView *view)¶: Return true iff the view is currently visible.

PuglStatus puglHide(PuglView *view)¶

Hide the view.

This is the counterpart to puglShow(). If the view is currently visible, it will be hidden, otherwise, this does nothing.

PuglStatus puglRealize(PuglView *view)¶

Realize 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 puglGetNativeView().

The view should be fully configured using the above functions before this is called. This function may only be called once per view.

PuglStatus puglSetParent(PuglView *view, PuglNativeView parent)¶

Set the native view the view will be embedded in.

This must be called before puglRealize(), reparenting isn’t supported.

PuglStatus puglSetTransientParent(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.

PuglStatus puglSetViewStyle(PuglView *view, PuglViewStyleFlags flags)¶

Set a view style, if supported by the system.

This can be used to manipulate the window into various special states, but note that not all states are supported on all systems. This function may return failure or an error if the platform implementation doesn’t “understand” how to set the given style, but the return value here can’t be used to determine if the state has actually been set. Any changes to the actual state of the view will arrive in later configure events.

PuglStatus puglShow(PuglView *view, PuglShowCommand command)¶

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.

Returns:: PuglStatus.PUGL_SUCCESS, an error from realization, or PuglStatus.PUGL_FAILURE if the window was shown but not raised.

PuglStatus puglUnrealize(PuglView *view)¶

Unrealize a view by destroying the corresponding system view or window.

This is the inverse of puglRealize(). After this call, the view no longer corresponds to a real system view, and can be realized again later.

Graphics¶

Functions for working with the graphics context and scheduling redisplays.

void *puglGetContext(PuglView *view)¶

Get the graphics context.

This is a backend-specific context used for drawing if the backend graphics API requires one. It’s only available during an expose.

Cairo: Returns a pointer to a cairo_t.

All other backends: returns null.

PuglStatus puglObscureRegion(PuglView *view, int x, int y, unsigned width, unsigned height)¶

“Obscure” a region so it will be exposed in the next render.

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 isn’t strictly guaranteed on all platforms. If called elsewhere, an expose will be enqueued to be processed in the next event loop iteration.

The region is clamped to the size of the view if necessary.

Parameters:

view – The view to expose later.
x – The top-left X coordinate of the rectangle to obscure.
y – The top-left Y coordinate of the rectangle to obscure.
width – The width of the rectangle to obscure.
height – The height coordinate of the rectangle to obscure.

PuglStatus puglObscureView(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 isn’t strictly guaranteed on all platforms. If called elsewhere, an expose will be enqueued to be processed in the next event loop iteration.

Interaction¶

Functions for interacting with the user and window system.

PUGL_NUM_CURSORS¶

10U

The number of PuglCursor values.

enum PuglCursor¶

A mouse cursor type.

This is a portable subset of mouse cursors that exist on X11, MacOS, and Windows.

enumerator PUGL_CURSOR_ARROW¶: Default pointing arrow.

enumerator PUGL_CURSOR_CARET¶: Caret (I-Beam) for text entry.

enumerator PUGL_CURSOR_CROSSHAIR¶: Cross-hair.

enumerator PUGL_CURSOR_HAND¶: Hand with a pointing finger.

enumerator PUGL_CURSOR_NO¶: Operation not allowed.

enumerator PUGL_CURSOR_LEFT_RIGHT¶: Left/right arrow for horizontal resize.

enumerator PUGL_CURSOR_UP_DOWN¶: Up/down arrow for vertical resize.

enumerator PUGL_CURSOR_UP_LEFT_DOWN_RIGHT¶: Diagonal arrow for down/right resize.

enumerator PUGL_CURSOR_UP_RIGHT_DOWN_LEFT¶: Diagonal arrow for down/left resize.

enumerator PUGL_CURSOR_ALL_SCROLL¶: Omnidirectional “arrow” for scrolling.

PuglStatus puglAcceptOffer(PuglView *view, const PuglDataOfferEvent *offer, uint32_t typeIndex, PuglDataAction action, int regionX, int regionY, unsigned regionWidth, unsigned regionHeight)¶

Accept data offered from a clipboard.

To accept data, this must be called while handling a PuglEventType.PUGL_DATA_OFFER event. Doing so will request the data from the source as the specified type. When the data is available, a PuglEventType.PUGL_DATA event will be sent to the view which can then retrieve the data with puglGetClipboard().

The region parameters specify a region of the view that will accept the data, which may be used by the system to avoid sending redundant events.

Parameters:

view – The view.
offer – The data offer event.
typeIndex – Index of the type the view will accept, which can be identified with puglGetClipboardType().
action – The action to be performed on the data. This may be used to provide visual feedback to the user, for example by changing the cursor.
regionX – View-relative top-left X coordinate of the accepting region.
regionY – View-relative top-left Y coordinate of the accepting region.
regionWidth – Width of the accepting region.
regionHeight – Height of the accepting region.

const void *puglGetClipboard(PuglView *view, PuglClipboard clipboard, uint32_t typeIndex, 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.

Parameters:

view – The view.
clipboard – Clipboard to get data from.
typeIndex – Index of the data type to get the item as.
len – Set to the length of the data in bytes.

Returns:

The clipboard contents, or null.

const char *puglGetClipboardType(const PuglView *view, PuglClipboard clipboard, uint32_t typeIndex)¶

Return the identifier of a type available in a clipboard.

This is usually a MIME type, but may also be another platform-specific type identifier. Applications must ignore any type they don’t recognize.

Returns null if typeIndex is out of bounds according to puglGetNumClipboardTypes().

uint32_t puglGetNumClipboardTypes(const PuglView *view, PuglClipboard clipboard)¶

Return the number of types available for the data in a clipboard.

Returns zero if the clipboard is empty.

PuglStatus puglGrabFocus(PuglView *view)¶

Grab the keyboard input focus.

Note that this will fail if the view isn’t mapped and so shouldn’t, for example, be called immediately after puglShow().

Returns:: PuglStatus.PUGL_SUCCESS if the focus was successfully grabbed, or an error.

bool puglHasFocus(const PuglView *view)¶

Return whether view has the keyboard input focus.

Returns:: True if the view is realized and focused for keyboard input.

PuglStatus puglPaste(PuglView *view)¶

Request data from the general copy/paste clipboard.

A PuglEventType.PUGL_DATA_OFFER event will be sent if data is available.

PuglStatus puglRejectOffer(PuglView *view, const PuglDataOfferEvent *offer, int regionX, int regionY, unsigned regionWidth, unsigned regionHeight)¶

Reject data offered from a clipboard.

This can be called instead of puglAcceptOffer() to explicitly reject the offer. Note that drag-and-drop will still work if this isn’t called, but applications should always explicitly accept or reject each data offer for optimal behaviour.

The region parameters specify a region of the view that will refuse the data, which may be used by the system to avoid sending redundant events.

Parameters:

view – The view.
offer – The data offer event.
regionX – The top-left X coordinate of the rejecting region.
regionY – The top-left Y coordinate of the rejecting region.
regionWidth – The width of the rejecting region.
regionHeight – The height of the rejecting region.

PuglStatus puglSendEvent(PuglView *view, const PuglEvent *event)¶

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 any other. Only a few event types are currently supported.

Opaque PuglEventType.PUGL_CLIENT events are supported on all platforms.

X11: A PuglEventType.PUGL_EXPOSE event can be sent, which is similar to calling puglObscureRegion(), but will always send a message to the X server, even when called in an event handler.

Returns:: PuglStatus.PUGL_UNSUPPORTED if sending this type of event isn’t supported in general, PuglStatus.PUGL_FAILURE if the event can’t be sent now.

PuglStatus puglSetClipboard(PuglView *view, PuglClipboard clipboard, const char *type, const void *data, size_t len)¶

Set the clipboard contents.

This sets the system clipboard contents, which can be retrieved with puglGetClipboard() or pasted into other applications.

Parameters:

view – The view.
clipboard – Clipboard to set data for.
type – The MIME type of the data, “text/plain” is assumed if NULL.
data – The data to copy to the clipboard.
len – The length of data in bytes (including terminator if necessary).

PuglStatus puglSetCursor(PuglView *view, PuglCursor cursor)¶

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 isn’t supported on this system, for example if compiled on X11 without Xcursor support.

Returns:: PuglStatus.PUGL_BAD_PARAMETER if the given cursor is invalid, PuglStatus.PUGL_UNSUPPORTED if setting the cursor isn’t supported on this system, or another error if the cursor is known but loading it fails.

PuglStatus puglStartTimer(PuglView *view, uintptr_t id, double timeout)¶

Activate a repeating timer event.

This starts a timer which will send a PuglTimerEvent 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.

Parameters:

view – The view to begin sending PuglEventType.PUGL_TIMER events to.
id – The identifier for this timer. This is an application-specific ID, usually a small positive integer enumerator. Only a limited number of timers is supported, and each adds overhead, so applications should create only a few timers, and perform several tasks in each if necessary.
timeout – The period, in seconds, of this timer. The maximum supported resolution is about 10 ms on Windows, and about 1 ms on X11 and MacOS.

Returns:

PuglStatus.PUGL_FAILURE if timers aren’t supported by the system, PuglStatus.PUGL_UNKNOWN_ERROR if setting the timer failed.

PuglStatus puglStopTimer(PuglView *view, uintptr_t id)¶

Stop an active timer.

Parameters:

view – The view that the timer is set for.
id – The ID previously passed to puglStartTimer().

Returns:

PuglStatus.PUGL_FAILURE if timers aren’t supported by this system, PuglStatus.PUGL_UNKNOWN_ERROR if stopping the timer failed.

PUGL_NUM_POSITION_HINTS¶

2U

The number of PuglPositionHint values.

PUGL_NUM_SIZE_HINTS¶

7U

The number of PuglSizeHint values.

PUGL_NUM_VIEW_HINTS¶

21U

The number of PuglViewHint values.

typedef PuglStatus (*PuglEventFunc)(PuglView *view, const PuglEvent *event)¶: A function called when an event occurs.

typedef uintptr_t PuglNativeView¶

A native view handle.

A “native view” is a system-specific handle for a view (or “window”). A PuglView is itself a native view, which may be embedded in another. Like the native world handle, this serves as a common denominator between this and other APIs.

X11: This is a Window.

MacOS: This is a pointer to an NSView*.

Windows: This is a HWND.

typedef struct PuglViewImpl PuglView¶

A drawable region that receives events.

A view can be thought of as a window, but doesn’t necessarily correspond to a top-level window in a desktop environment. For example, a view can be embedded in another, or represent a simple embedded system with no concept of windows at all.

enum PuglPositionHint¶

A hint for configuring or constraining the position of a view.

The system will attempt to make the view adhere to these, but they are suggestions, not hard constraints. Applications should handle any view position gracefully.

An unset position has INT16_MIN (-32768) for both x and y. In practice, set positions should be between -16000 and 16000 for portability. Usually, the origin is the top left of the display, although negative coordinates are possible, particularly on multi-display systems.

enumerator PUGL_DEFAULT_POSITION¶

Default position.

This is used as the initial position if no other position is specified. It isn’t necessary to set a default position (unlike the default size, which is required). If not even a default position is set, then the window will be placed somewhere reasonable according to platform conventions. Applications must not make assumptions about the initial position, which is implementation-defined, platform-specific, and for embedded views, may become invalid if the parent’s size is adjusted.

enumerator PUGL_CURRENT_POSITION¶

Current position.

This reflects the current position of the view, which may be different from the default position if the view has been moved by the user, window manager, or for any other reason. It overrides the default position.

enum PuglSizeHint¶

A hint for configuring/constraining the size of a view.

The system will attempt to make the view adhere to these, but they are suggestions, not hard constraints. Applications should handle any view size gracefully.

enumerator PUGL_DEFAULT_SIZE¶

Default size.

This is used as the size during window creation as a default, if no other size is specified.

enumerator PUGL_CURRENT_SIZE¶

Current size.

This reflects the current size of the view, which may be different from the default size if the view is resizable. It overrides the default size.

enumerator PUGL_MIN_SIZE¶

Minimum size.

If set, the view should be at least this large.

enumerator PUGL_MAX_SIZE¶

Maximum size.

If set, the view should be at most this large.

enumerator PUGL_FIXED_ASPECT¶

Fixed aspect ratio.

If set, the view should have this aspect ratio. Mutually exclusive with PuglSizeHint.PUGL_MIN_ASPECT and PuglSizeHint.PUGL_MAX_ASPECT.

enumerator PUGL_MIN_ASPECT¶

Minimum aspect ratio.

If set, the view should have an aspect ratio no lower than this. Mutually exclusive with PuglSizeHint.PUGL_FIXED_ASPECT.

enumerator PUGL_MAX_ASPECT¶

Maximum aspect ratio.

If set, the view should have an aspect ratio no higher than this. Mutually exclusive with PuglSizeHint.PUGL_FIXED_ASPECT.

enum PuglViewHint¶

An integer hint for configuring a view.

enumerator PUGL_CONTEXT_API¶: OpenGL render API (GL/GLES)

enumerator PUGL_CONTEXT_VERSION_MAJOR¶: OpenGL context major version.

enumerator PUGL_CONTEXT_VERSION_MINOR¶: OpenGL context minor version.

enumerator PUGL_CONTEXT_PROFILE¶: OpenGL context profile (core/compatibility)

enumerator PUGL_CONTEXT_DEBUG¶: OpenGL context debugging enabled.

enumerator PUGL_RED_BITS¶: Number of bits for red channel.

enumerator PUGL_GREEN_BITS¶: Number of bits for green channel.

enumerator PUGL_BLUE_BITS¶: Number of bits for blue channel.

enumerator PUGL_ALPHA_BITS¶: Number of bits for alpha channel.

enumerator PUGL_DEPTH_BITS¶: Number of bits for depth buffer.

enumerator PUGL_STENCIL_BITS¶: Number of bits for stencil buffer.

enumerator PUGL_SAMPLE_BUFFERS¶: Number of sample buffers (AA)

enumerator PUGL_SAMPLES¶: Number of samples per pixel (AA)

enumerator PUGL_DOUBLE_BUFFER¶: True if double buffering should be used.

enumerator PUGL_SWAP_INTERVAL¶: Number of frames between buffer swaps.

enumerator PUGL_RESIZABLE¶: True if view should be resizable.

enumerator PUGL_IGNORE_KEY_REPEAT¶: True if key repeat events are ignored.

enumerator PUGL_REFRESH_RATE¶: Refresh rate in Hz.

enumerator PUGL_VIEW_TYPE¶: View type (a PuglViewType)

enumerator PUGL_DARK_FRAME¶: True if window frame should be dark.

enumerator PUGL_ACCEPT_DROP¶: True if view accepts dropped data.

enum PuglViewHintValue¶

A special view hint value.

enumerator PUGL_DONT_CARE¶: Generic trinary: unset.

enumerator PUGL_FALSE¶: Generic trinary: false.

enumerator PUGL_TRUE¶: Generic trinary: true.

enumerator PUGL_OPENGL_API¶: For PuglViewHint.PUGL_CONTEXT_API.

enumerator PUGL_OPENGL_ES_API¶: For PuglViewHint.PUGL_CONTEXT_API.

enumerator PUGL_OPENGL_CORE_PROFILE¶: For PuglViewHint.PUGL_CONTEXT_PROFILE.

enumerator PUGL_OPENGL_COMPATIBILITY_PROFILE¶: For PuglViewHint.PUGL_CONTEXT_PROFILE.

enum PuglViewType¶

View type.

enumerator PUGL_VIEW_TYPE_NORMAL¶: A normal top-level window.

enumerator PUGL_VIEW_TYPE_UTILITY¶: A utility window like a palette or toolbox.

enumerator PUGL_VIEW_TYPE_DIALOG¶: A dialog window.