mutter/cogl/cogl-poll.h
Damien Lespiau cfcb440d70 doc: Document the members of CoglPollFDEvent
(cherry picked from commit 7cc94c2a994a774f0d8db172c9e0bec506bd2287)
2013-01-22 17:48:14 +00:00

175 lines
6.1 KiB
C

/*
* Cogl
*
* An object oriented GL/GLES Abstraction/Utility Layer
*
* Copyright (C) 2012 Intel Corporation.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see
* <http://www.gnu.org/licenses/>.
*
*
* Authors:
* Neil Roberts <neil@linux.intel.com>
*/
#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
#error "Only <cogl/cogl.h> can be included directly."
#endif
#ifndef __COGL_POLL_H__
#define __COGL_POLL_H__
#include <cogl/cogl-defines.h>
#include <cogl/cogl-context.h>
COGL_BEGIN_DECLS
/**
* SECTION:cogl-poll
* @short_description: Functions for integrating Cogl with an
* application's main loop
*
* 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.
*/
/**
* CoglPollFDEvent:
* @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.
*
* 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.
*
* Since: 1.10
* Stability: unstable
*/
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;
/**
* CoglPollFD:
* @fd: The file descriptor to block on
* @events: A bitmask of events to block on
* @revents: A bitmask of returned events
*
* A struct for describing the state of a file descriptor that Cogl
* needs to block on. The @events field contains a bitmask of
* #CoglPollFDEvent<!-- -->s that should cause the application to wake
* up. After the application is woken up from idle it should pass back
* an array of #CoglPollFD<!-- -->s 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.
*
* Since: 1.10
* Stability: unstable
*/
typedef struct {
int fd;
short int events;
short int revents;
} CoglPollFD;
/**
* cogl_poll_get_info:
* @context: A #CoglContext
* @poll_fds: A return location for a pointer to an array
* of #CoglPollFD<!-- -->s
* @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.
*
* This should be called whenever an application is about to go idle
* so that Cogl has a chance to describe what state it needs to be
* woken up on. The assumption is that the application is using a main
* loop with something like the poll function call on Unix or the GLib
* main loop.
*
* 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. Either way it should pass a pointer to either array back to
* Cogl when calling cogl_poll_dispatch().
*
* 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 zero if
* Cogl needs to be woken up immediately.
*
* Stability: unstable
* Since: 1.10
*/
void
cogl_poll_get_info (CoglContext *context,
CoglPollFD **poll_fds,
int *n_poll_fds,
int64_t *timeout);
/**
* cogl_poll_dispatch:
* @context: A #CoglContext
* @poll_fds: An array of #CoglPollFD<!-- -->s describing the events
* that have occurred since the application went idle.
* @n_poll_fds: The length of the @poll_fds array.
*
* 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 from
* cogl_context_begin_idle() or a shorter array missing some file
* descriptors that Cogl requested.
*
* Stability: unstable
* Since: 1.10
*/
void
cogl_poll_dispatch (CoglContext *context,
const CoglPollFD *poll_fds,
int n_poll_fds);
COGL_END_DECLS
#endif /* __COGL_POLL_H__ */