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 puglSetParentWindow(). If the parent is a Pugl view, the native handle can be accessed with puglGetNativeView(). For example:

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

Geometry Types¶

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.

enum PuglStringHint¶

A string property for configuration.

enumerator PUGL_CLASS_NAME¶

The application class name.

This is a stable identifier for the application, which should be 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 is used to set the class name of windows (that underlie realized views), which is used for things like loading configuration, or custom window management rules.

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 is 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 is common for programs to add the name of the current document, like “myfile.txt - Fancy Editor”.

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.

PUGL_NUM_STRING_HINTS¶: The number of PuglStringHint values.

Events¶

All updates to the view happen via events, which are dispatched to the view’s event function.

An event is a tagged union with a type, and a set of more specific fields depending on the type.

Management Events¶

struct PuglConfigureEvent¶

View resize or move event.

A configure event is sent whenever the view is resized or moved. When a configure event is received, the graphics context is active but not set up for drawing. For example, it is valid to adjust the OpenGL viewport or otherwise configure the context, but not to draw anything.

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.

enum PuglViewStyleFlag¶

View style flags.

Style flags reflect special modes and states supported by the window system. Applications should ideally use a single main view, but can monitor or manipulate style flags to better integrate with the window system.

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.

typedef uint32_t PuglViewStyleFlags¶: Bitwise OR of PuglViewStyleFlag values.

typedef PuglAnyEvent PuglRealizeEvent¶

View realize event.

This event is sent when a view is realized before it is first displayed, with the graphics context entered. This is typically used for setting up the graphics system, for example by loading OpenGL extensions.