This is the API documentation for Pugl.
This page refers to the [C API](@ref pugl_c),
there is also a [C++ API](@ref pugl_cxx) in the `pugl` namespace.

The Pugl API revolves around two main objects:
the [World](@ref world) and the [View](@ref view).
An application creates a single world to manage top-level state,
then creates one or more views to display.

## World

The [World](@ref world) contains all top-level state,
and manages views and the event loop.

A world must be [created](@ref puglNewWorld) before any views,
and it must outlive all views.

## View

A [View](@ref view) is a drawable region that receives events.

Creating a visible view is a multi-step process.
When a new view is [created](@ref puglNewView),
it does not yet represent a real system view or window.
To display, it must first have a [backend](@ref puglSetBackend)
and [event handler](@ref puglSetEventFunc) set,
and be configured by [setting hints](@ref puglSetViewHint)
and optionally [adjusting the frame](@ref frame).

The [Backend](@ref PuglBackend) controls drawing for a view.
Pugl includes [Cairo](@ref cairo) and [OpenGL](@ref gl) backends,
as well as a [stub](@ref stub) backend that creates a native window with no drawing context.


Once the view is configured,
it can be [realized](@ref puglRealize) and [shown](@ref puglShowWindow).
By default a view will correspond to a top-level system window.
To create a view within another window,
it must have a [parent window set](@ref puglSetParentWindow) before being created.


## Events

[Events](@ref events) are sent to a view when it has received user input or must be drawn.

Events are handled by the [event handler](@ref PuglEventFunc) set during initialisation.
This function is called whenever something happens that the view must respond to.
This includes user interaction like mouse and keyboard input,
and system events like window resizing and exposure.

## Event Loop

The event loop is driven by repeatedly calling #puglUpdate which processes events from the window system,
and dispatches them to views when necessary.

Typically, a plugin calls #puglUpdate with timeout 0 in some callback driven by the host.
A program can use whatever timeout is appropriate:
event-driven applications may wait forever,
or for continuous animation,
use a timeout that is a significant fraction of the frame period
(with enough time left over to render).

Redrawing can be requested by calling #puglPostRedisplay or #puglPostRedisplayRect,
which post expose events to the queue.
Note, however, that this will not wake up a blocked #puglUpdate call on MacOS
(which does not handle drawing via events).
For continuous redrawing, call #puglPostRedisplay when a #PUGL_UPDATE event is received.
This event is sent before views are redrawn,
so can be used as a hook to expand the update region right before the view is exposed.

## Error Handling

Most functions return a [Status](@ref status) which should be checked to detect failure.