World

Typedefs
typedef struct PuglWorldImpl	PuglWorld
typedef void *	PuglWorldHandle
	Handle for the world's opaque user data.
typedef uint32_t	PuglWorldFlags
	Bitwise OR of PuglWorldFlag values.

Enumerations
enum	PuglWorldType { PUGL_PROGRAM , PUGL_MODULE }
	The type of a World. More...
enum	PuglWorldFlag { PUGL_WORLD_THREADS = 1u << 0u }
	World flags. More...

Functions
PUGL_API PuglWorld *	puglNewWorld (PuglWorldType type, PuglWorldFlags flags)
PUGL_API void	puglFreeWorld (PuglWorld *world)
	Free a world allocated with puglNewWorld().
PUGL_API void	puglSetWorldHandle (PuglWorld *world, PuglWorldHandle handle)
PUGL_API PuglWorldHandle	puglGetWorldHandle (PuglWorld *world)
	Get the user data for the world.
PUGL_API void *	puglGetNativeWorld (PuglWorld *world)
PUGL_API PuglStatus	puglSetClassName (PuglWorld *world, const char *name)
PUGL_API const char *	puglGetClassName (const PuglWorld *world)
	Get the class name of the application, or null.
PUGL_API double	puglGetTime (const PuglWorld *world)
PUGL_API PuglStatus	puglUpdate (PuglWorld *world, double timeout)

Detailed Description

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.

Typedef Documentation

PuglWorld

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.

PuglWorldFlags

typedef uint32_t PuglWorldFlags

Bitwise OR of PuglWorldFlag values.

PuglWorldHandle

typedef void* PuglWorldHandle

Handle for the world's opaque user data.

Enumeration Type Documentation

PuglWorldFlag

enum PuglWorldFlag

World flags.

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

PuglWorldType

enum PuglWorldType

The type of a World.

Enumerator
PUGL_PROGRAM	Top-level application.
PUGL_MODULE	Plugin or module within a larger application.

Function Documentation

puglFreeWorld()

PUGL_API void puglFreeWorld

(

PuglWorld *

world

)

Free a world allocated with puglNewWorld().

puglGetClassName()

PUGL_API const char * puglGetClassName

(

const PuglWorld *

world

)

Get the class name of the application, or null.

puglGetNativeWorld()

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

puglGetTime()

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

puglGetWorldHandle()

PUGL_API PuglWorldHandle puglGetWorldHandle

(

PuglWorld *

world

)

Get the user data for the world.

puglNewWorld()

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

puglSetClassName()

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

puglSetWorldHandle()

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

puglUpdate()

PUGL_API 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

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