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.

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.