Main loop integration

## Main loop integration Main loop integration — Functions for integrating Cogl with an application's main loop |

## Synopsis

    enum                CoglPollFDEvent;
                        CoglPollFD;
    int                 cogl_poll_renderer_get_info         (CoglRenderer *renderer,
                                                             CoglPollFD **poll_fds,
                                                             int *n_poll_fds,
                                                             int64_t *timeout);
    void                cogl_poll_renderer_dispatch         (CoglRenderer *renderer,
                                                             const CoglPollFD *poll_fds,
                                                             int n_poll_fds);
    GSource *           cogl_glib_source_new                (CoglContext *context,
                                                             int priority);
    GSource *           cogl_glib_renderer_source_new       (CoglRenderer *renderer,
                                                             int priority);

## Description

Cogl needs to integrate with the application's main loop so that it can internally handle some events from the driver. All Cogl applications must use these functions. They provide enough information to describe the state that Cogl will need to wake up on. An application using the GLib main loop can instead use `cogl_glib_source_new()` which provides a GSource ready to be added to the main loop.

## Details

### enum CoglPollFDEvent

    typedef enum {
      COGL_POLL_FD_EVENT_IN = COGL_SYSDEF_POLLIN,
      COGL_POLL_FD_EVENT_PRI = COGL_SYSDEF_POLLPRI,
      COGL_POLL_FD_EVENT_OUT = COGL_SYSDEF_POLLOUT,
      COGL_POLL_FD_EVENT_ERR = COGL_SYSDEF_POLLERR,
      COGL_POLL_FD_EVENT_HUP = COGL_SYSDEF_POLLHUP,
      COGL_POLL_FD_EVENT_NVAL = COGL_SYSDEF_POLLNVAL
    } CoglPollFDEvent;

A bitmask of events that Cogl may need to wake on for a file descriptor. Note that these all have the same values as the corresponding defines for the poll function call on Unix so they may be directly passed to poll.

`COGL_POLL_FD_EVENT_IN` | there is data to read
`COGL_POLL_FD_EVENT_PRI` | data can be written (without blocking)
`COGL_POLL_FD_EVENT_OUT` | there is urgent data to read.
`COGL_POLL_FD_EVENT_ERR` | error condition
`COGL_POLL_FD_EVENT_HUP` | hung up (the connection has been broken, usually for pipes and sockets).
`COGL_POLL_FD_EVENT_NVAL` | invalid request. The file descriptor is not open.

Since 1.10

Stability Level: Unstable

### CoglPollFD

    typedef struct {
      int fd;
      short int events;
      short int revents;
    } CoglPollFD;

A struct for describing the state of a file descriptor that Cogl needs to block on. The `events` field contains a bitmask of CoglPollFDEvents that should cause the application to wake up. After the application is woken up from idle it should pass back an array of CoglPollFDs to Cogl and update the `revents` mask to the actual events that occurred on the file descriptor.

Note that CoglPollFD is deliberately exactly the same as struct pollfd on Unix so that it can simply be cast when calling poll.

int `fd`; | The file descriptor to block on
short int `events`; | A bitmask of events to block on
short int `revents`; | A bitmask of returned events

Since 1.10

Stability Level: Unstable

### cogl_poll_renderer_get_info ()

    int                 cogl_poll_renderer_get_info         (CoglRenderer *renderer,
                                                             CoglPollFD **poll_fds,
                                                             int *n_poll_fds,
                                                             int64_t *timeout);

Is used to integrate Cogl with an application mainloop that is based on the unix poll(2) api (or `select()` or something equivalent). This api should be called whenever an application is about to go idle so that Cogl has a chance to describe what file descriptor events it needs to be woken up for.

### Note

If your application is using the Glib mainloop then you should jump to the `cogl_glib_source_new()` api as a more convenient way of integrating Cogl with the mainloop.

After the function is called *`poll_fds` will contain a pointer to an array of CoglPollFD structs describing the file descriptors that Cogl expects. The fd and events members will be updated accordingly. After the application has completed its idle it is expected to either update the revents members directly in this array or to create a copy of the array and update them there.

When the application mainloop returns from calling poll(2) (or its equivalent) then it should call `cogl_poll_renderer_dispatch()` passing a pointer the array of CoglPollFDs with updated revent values.

When using the `COGL_WINSYS_ID_WGL` winsys (where file descriptors don't make any sense) or `COGL_WINSYS_ID_SDL` (where the event handling functions of SDL don't allow blocking on a file descriptor) *n_poll_fds is guaranteed to be zero.

`timeout` will contain a maximum amount of time to wait in microseconds before the application should wake up or -1 if the application should wait indefinitely. This can also be 0 if Cogl needs to be woken up immediately.

`renderer` : | A CoglRenderer
`poll_fds` : | A return location for a pointer to an array of CoglPollFDs
`n_poll_fds` : | A return location for the number of entries in *`poll_fds`
`timeout` : | A return location for the maximum length of time to wait in microseconds, or -1 to wait indefinitely.
Returns : | A "poll fd state age" that changes whenever the set of poll_fds has changed. If this API is being used to integrate with another system mainloop api then knowing if the set of file descriptors and events has really changed can help avoid redundant work depending the api. The age isn't guaranteed to change when the timeout changes.

Since 1.16

Stability Level: Unstable

### cogl_poll_renderer_dispatch ()

    void                cogl_poll_renderer_dispatch         (CoglRenderer *renderer,
                                                             const CoglPollFD *poll_fds,
                                                             int n_poll_fds);

This should be called whenever an application is woken up from going idle in its main loop. The `poll_fds` array should contain a list of file descriptors matched with the events that occurred in revents. The events field is ignored. It is safe to pass in extra file descriptors that Cogl didn't request when calling `cogl_poll_renderer_get_info()` or a shorter array missing some file descriptors that Cogl requested.

### Note

If your application didn't originally create a CoglRenderer manually then you can easily get a CoglRenderer pointer by calling `cogl_get_renderer()`.

`renderer` : | A CoglRenderer
`poll_fds` : | An array of CoglPollFDs describing the events that have occurred since the application went idle.
`n_poll_fds` : | The length of the `poll_fds` array.

Since 1.16

Stability Level: Unstable

### cogl_glib_source_new ()

    GSource *           cogl_glib_source_new                (CoglContext *context,
                                                             int priority);

Creates a GSource which handles Cogl's internal system event processing. This can be used as a convenience instead of `cogl_poll_renderer_get_info()` and `cogl_poll_renderer_dispatch()` in applications that are already using the GLib main loop. After this is called the GSource should be attached to the main loop using `g_source_attach()`.

Applications that manually connect to a CoglRenderer before they create a CoglContext should instead use `cogl_glib_renderer_source_new()` so that events may be dispatched before a context has been created. In that case you don't need to use this api in addition later, it is simply enough to use `cogl_glib_renderer_source_new()` instead.

### Note

This api is actually just a thin convenience wrapper around `cogl_glib_renderer_source_new()`

`context` : | A CoglContext
`priority` : | The priority of the GSource
Returns : | a new GSource

Since 1.10

Stability Level: Unstable

### cogl_glib_renderer_source_new ()

    GSource *           cogl_glib_renderer_source_new       (CoglRenderer *renderer,
                                                             int priority);

Creates a GSource which handles Cogl's internal system event processing. This can be used as a convenience instead of `cogl_poll_renderer_get_info()` and `cogl_poll_renderer_dispatch()` in applications that are already using the GLib main loop. After this is called the GSource should be attached to the main loop using `g_source_attach()`.

`renderer` : | A CoglRenderer
`priority` : | The priority of the GSource
Returns : | a new GSource

Since 1.16

Stability Level: Unstable