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.