Pugl

Pugl is an API for writing portable and embeddable GUIs. Pugl is not a toolkit or framework, but a minimal portability layer that sets up a drawing context and delivers events.

Compared to other libraries, Pugl is particularly suitable for use in plugins or other loadable modules. There is no implicit context or static data in the library, so it may be statically linked and used multiple times in the same process.

Pugl has a modular design that separates the core library from graphics backends. The core library is graphics agnostic, it implements platform support and depends only on standard system libraries. MacOS, Windows, and X11 are currently supported as platforms.

Graphics backends are separate so that applications only depend on the API that they use. Pugl includes graphics backends for Cairo, OpenGL, and Vulkan. It is also possible to use some other graphics API by implementing a custom backend, or simply accessing the native platform handle for a window.

Usage

Building Against Pugl

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

  • pugl-cairo-0

  • pugl-gl-0

  • pugl-vulkan-0

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

If you are instead including the source directly in your project, the structure is quite simple and hopefully obvious. It is only necessary to copy the platform and backend implementations that you need.

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 puglSetClassName(). This allows the window system to distinguish different applications and, for example, users to set up rules to manage their windows nicely:

puglSetClassName(world, "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 double defaultWidth  = 1920.0;
const double defaultHeight = 1080.0;

puglSetWindowTitle(view, "My Window");
puglSetDefaultSize(view, defaultWidth, defaultHeight);
puglSetMinSize(view, defaultWidth / 4.0, defaultHeight / 4.0);
puglSetAspectRatio(view, 1, 1, 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 puglSetParentWindow(). If the parent is a Pugl view, the native handle can be accessed with puglGetNativeWindow(). For example:

puglSetParentWindow(view, puglGetNativeWindow(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_USE_COMPAT_PROFILE, PUGL_FALSE);
puglSetViewHint(view, PUGL_CONTEXT_VERSION_MAJOR, 3);
puglSetViewHint(view, PUGL_CONTEXT_VERSION_MINOR, 3);

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_CREATE and PUGL_DESTROY 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);

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

1

MacOS has a strong distinction between views, which may be nested, and windows, which may not. On Windows and X11, everything is a nestable window, but top-level windows are configured differently.

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_CREATE:
    return setupGraphics(app);
  case PUGL_DESTROY:
    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 during the handling of these events:

As always, drawing is only possible during an expose.

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 puglPostRedisplay() or puglPostRedisplayRect(). After these are called, a PuglExposeEvent will be dispatched on the next call to puglUpdate().

For continuous redrawing, call puglPostRedisplay() 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 data between different views, including views in different processes. A clipboard transfer is a multi-step event-driven process, where the sender and receiver can negotiate a mutually supported data format.

Copying

Data can be copied to the general clipboard with puglSetClipboard(). The MIME type of the data must be specified. Commonly supported types are text/plain for plain text, and text/uri-list for lists of URIs (including local files).

For example, a string can be copied to the clipboard by setting the general clipboard to text/plain data:

const char* someString = "Copied string";

puglSetClipboard(view,
                 "text/plain",
                 someString,
                 strlen(someString));

Pasting

Data from a clipboard can be pasted to a view using puglPaste():

puglPaste(view);

This initiates a data transfer from the clipboard to the view if possible. If data is available, the view will be sent a PUGL_DATA_OFFER event to begin the transfer.

Receiving Data

A data transfer from a clipboard to a view begins with the view receiving a PUGL_DATA_OFFER event. This indicates that data (possibly in several formats) is being offered to a view, which can either “accept” or “reject” it:

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 PuglEventDataOffer* event)
{
  size_t numTypes = puglGetNumClipboardTypes(view, clipboard);

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

If the view supports one of the data types, it can accept the offer with puglAcceptOffer():

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

When an offer is accepted, the data will be transferred and converted if necessary, then the view will be sent a PUGL_DATA event. When the data event is received, the data can be fetched with puglGetClipboard():

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

// ...

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

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

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

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

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

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

Pugl C API.

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.

PuglGlFunc puglGetProcAddress(const char *name)

Return the address of an 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.

PuglStatus puglLeaveContext(PuglView *view)

Leave the OpenGL context.

This must only be called after puglEnterContext().

const PuglBackend *puglGlBackend(void)

OpenGL graphics backend.

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

Status

Most functions return a status code which can be used to check for errors.

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

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.

enum PuglWorldType

The type of a World.

enumerator PUGL_PROGRAM

Top-level application.

enumerator PUGL_MODULE

Plugin or module within a larger application.

enum PuglWorldFlag

World flags.

enumerator PUGL_WORLD_THREADS

Set up support for threads if necessary. - X11: Calls XInitThreads() which is required for some drivers.

typedef struct PuglWorldImpl PuglWorld

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 void *PuglWorldHandle

Handle for the world’s opaque user data.

typedef uint32_t PuglWorldFlags

Bitwise OR of PuglWorldFlag values.

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 puglFreeWorld(PuglWorld *world)

Free a world allocated with puglNewWorld()

void puglSetWorldHandle(PuglWorld *world, PuglWorldHandle handle)

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.

PuglWorldHandle puglGetWorldHandle(PuglWorld *world)

Get the user data for the world.

void *puglGetNativeWorld(PuglWorld *world)

Return a pointer to the native handle of the world.

X11: Returns a pointer to the Display.

MacOS: Returns a pointer to the NSApplication.

Windows: Returns the HMODULE of the calling process.

PuglStatus puglSetClassName(PuglWorld *world, const char *name)

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.

const char *puglGetClassName(const PuglWorld *world)

Get the class name of the application, or null.

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.

PuglStatus puglUpdate(PuglWorld *world, double timeout)

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 minimize input latency by ensuring that as many input events are consumed as possible before drawing.

Returns

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

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.

Setup

Functions for creating and destroying a view.

PuglView *puglNewView(PuglWorld *world)

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

void puglFreeView(PuglView *view)

Free a view created with puglNewView()

PuglWorld *puglGetWorld(PuglView *view)

Return the world that view is a part of.

void puglSetHandle(PuglView *view, PuglHandle handle)

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.

PuglHandle puglGetHandle(PuglView *view)

Get the user data for a view.

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 the following backends:

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.

const PuglBackend *puglGetBackend(const PuglView *view)

Return the graphics backend used by a view.

PuglStatus puglSetEventFunc(PuglView *view, PuglEventFunc eventFunc)

Set the function to call when an event occurs.

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

Set a hint to configure view properties.

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

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.

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, but means a good size on a “standard DPI” display (around 96 DPI). In other words, the scale 1.0 should have text that is reasonably sized on a 96 DPI display, and the scale 2.0 should have text twice that large.

Frame

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

PuglRect puglGetFrame(const PuglView *view)

Get the current position and size of the view.

The position is in screen coordinates with an upper left origin.

PuglStatus puglSetFrame(PuglView *view, PuglRect frame)

Set the current position and size of the view.

The position is in screen coordinates with an upper left origin.

Returns

PuglStatus.PUGL_UNKNOWN_ERROR on failure, in which case the view frame is unchanged.

PuglStatus puglSetPosition(PuglView *view, int x, int y)

Set the current position of the view.

Returns

PuglStatus.PUGL_UNKNOWN_ERROR on failure, in which case the view frame is unchanged.

PuglStatus puglSetSize(PuglView *view, unsigned width, unsigned height)

Set the current size of the view.

Returns

PuglStatus.PUGL_UNKNOWN_ERROR on failure, in which case the view frame is unchanged.

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

Set a size hint for the view.

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

This should be called before puglResize() so the initial window for the view can be configured correctly.

Returns

PuglStatus.PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is not yet realized.

Window

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

PuglStatus puglSetWindowTitle(PuglView *view, const char *title)

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.

const char *puglGetWindowTitle(const PuglView *view)

Return the title of the window, or null.

PuglStatus puglSetParentWindow(PuglView *view, PuglNativeView parent)

Set the parent window for embedding a view in an existing window.

This must be called before puglRealize(), reparenting is not supported.

PuglNativeView puglGetParentWindow(const PuglView *view)

Return the parent window this view is embedded in, or null.

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.

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.

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

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

PuglStatus puglHide(PuglView *view)

Hide the current window.

bool puglGetVisible(const PuglView *view)

Return true iff the view is currently visible.

PuglNativeView puglGetNativeWindow(PuglView *view)

Return the native window handle.

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 is only available during an expose.

Cairo: Returns a pointer to a cairo_t.

All other backends: returns null.

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

PuglStatus puglPostRedisplayRect(PuglView *view, PuglRect rect)

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.

Interaction

Functions for interacting with the user and window system.

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.

PuglStatus puglGrabFocus(PuglView *view)

Grab the keyboard input focus.

Note that this will fail if the view is not mapped and so should not, 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.

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.

uint32_t puglGetNumClipboardTypes(const PuglView *view)

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

Returns zero if the clipboard is empty.

const char *puglGetClipboardType(const PuglView *view, 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 do not recognize.

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

PuglStatus puglAcceptOffer(PuglView *view, const PuglDataOfferEvent *offer, uint32_t typeIndex)

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

Parameters
  • view – The view.

  • offer – The data offer event.

  • typeIndex – The index of the type that the view will accept. This is the typeIndex argument to the call of puglGetClipboardType() that returned the accepted type.

PuglStatus puglSetClipboard(PuglView *view, 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.

  • 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).

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

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

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 is not 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_FAILURE if the cursor is known but loading it system fails.

PuglStatus puglRequestAttention(PuglView *view)

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.

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

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

Returns

PuglStatus.PUGL_FAILURE if timers are not 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 are not supported by this system, PuglStatus.PUGL_UNKNOWN_ERROR if stopping the timer failed.

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 other events. Note that this function only works for certain event types.

Currently, only PuglEventType.PUGL_CLIENT events are supported on all platforms.

X11: A PuglEventType.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.

Returns

PuglStatus.PUGL_UNSUPPORTED if sending events of this type is not supported, PuglStatus.PUGL_UNKNOWN_ERROR if sending the event failed.

enum PuglViewHint

A hint for configuring a view.

enumerator PUGL_USE_COMPAT_PROFILE

Use compatible (not core) OpenGL profile.

enumerator PUGL_USE_DEBUG_CONTEXT

True to use a debug OpenGL context.

enumerator PUGL_CONTEXT_VERSION_MAJOR

OpenGL context major version.

enumerator PUGL_CONTEXT_VERSION_MINOR

OpenGL context minor version.

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_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_NUM_VIEW_HINTS
enum PuglViewHintValue

A special view hint value.

enumerator PUGL_DONT_CARE

Use best available value.

enumerator PUGL_FALSE

Explicitly false.

enumerator PUGL_TRUE

Explicitly true.

enum PuglSizeHint

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

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

enumerator PUGL_DEFAULT_SIZE

Default size.

enumerator PUGL_MIN_SIZE

Minimum size.

enumerator PUGL_MAX_SIZE

Maximum size.

enumerator PUGL_FIXED_ASPECT

Fixed aspect ratio. If set, the view’s size should be constrained to 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’s size should be constrained to 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’s size should be constrained to an aspect ratio no higher than this. Mutually exclusive with PuglSizeHint.PUGL_FIXED_ASPECT.

typedef struct PuglViewImpl PuglView

A drawable region that receives events.

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 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 uintptr_t PuglNativeView

A native view handle.

X11: This is a Window.

MacOS: This is a pointer to an NSView*.

Windows: This is a HWND.

typedef void *PuglHandle

Handle for a view’s opaque user data.

typedef PuglStatus (*PuglEventFunc)(PuglView *view, const PuglEvent *event)

A function called when an event occurs.

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 should not 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 is not 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.

https://www.khronos.org/registry/vulkan/specs/1.0/html/chap4.html

PuglVulkanLoader *puglNewVulkanLoader(PuglWorld *world)

Create a new dynamic loader for Vulkan functions.

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

Returns

A new Vulkan loader, or null on failure.

void puglFreeVulkanLoader(PuglVulkanLoader *loader)

Free a loader created with puglNewVulkanLoader().

Note that this closes the Vulkan library, so no Vulkan objects or API may be used after this is called.

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

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.

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.

const PuglBackend *puglVulkanBackend(void)

Vulkan graphics backend.

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

struct PuglRect

A rectangle in a view or on the screen.

This type is used to describe two things: the position and size of a view (for configuring), or a rectangle within a view (for exposing).

The coordinate (0, 0) represents the top-left pixel of the parent window (or display if there isn’t one), or the top-left pixel of the view, respectively.

PuglCoord x
PuglCoord y
PuglSpan width
PuglSpan height
typedef int16_t PuglCoord

A pixel coordinate within/of a view.

This is relative to the top left corner of the view’s parent, or to the top left corner of the view itself, depending on the context.

There are platform-imposed limits on window positions. For portability, applications should keep coordinates between -16000 and 16000. Note that negative frame coordinates are possible, for example with multiple screens.

typedef uint16_t PuglSpan

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

Due to platform limits, the span of a view in either dimension should be between 1 and 10000.