cogl/cogl-poll.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2012 Intel Corporation.
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library. If not, see
  20  * <http://www.gnu.org/licenses/>.
  21  *
  22  *
  23  * Authors:
  24  *  Neil Roberts <neil@linux.intel.com>
  25  */
  26
  27 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
  28 #error "Only <cogl/cogl.h> can be included directly."
  29 #endif
  30
  31 #ifndef __COGL_POLL_H__
  32 #define __COGL_POLL_H__
  33
  34 #include <glib.h>
  35 #include <cogl/cogl-defines.h>
  36 #include <cogl/cogl-context.h>
  37
  38 G_BEGIN_DECLS
  39
  40 /**
  41  * SECTION:cogl-poll
  42  * @short_description: Functions for integrating Cogl with an
  43  *   application's main loop
  44  *
  45  * Cogl needs to integrate with the application's main loop so that it
  46  * can internally handle some events from the driver. All Cogl
  47  * applications must use these functions. They provide enough
  48  * information to describe the state that Cogl will need to wake up
  49  * on. An application using the GLib main loop can instead use
  50  * cogl_glib_source_new() which provides a #GSource ready to be added
  51  * to the main loop.
  52  */
  53
  54 /**
  55  * CoglPollFDEvent:
  56  *
  57  * A bitmask of events that Cogl may need to wake on for a file
  58  * descriptor. Note that these all have the same values as the
  59  * corresponding defines for the poll function call on Unix so they
  60  * may be directly passed to poll.
  61  *
  62  * Since: 1.10
  63  * Stability: unstable
  64  */
  65 typedef enum
  66 {
  67   COGL_POLL_FD_EVENT_IN = COGL_SYSDEF_POLLIN,
  68   COGL_POLL_FD_EVENT_PRI = COGL_SYSDEF_POLLPRI,
  69   COGL_POLL_FD_EVENT_OUT = COGL_SYSDEF_POLLOUT,
  70   COGL_POLL_FD_EVENT_ERR = COGL_SYSDEF_POLLERR,
  71   COGL_POLL_FD_EVENT_HUP = COGL_SYSDEF_POLLHUP,
  72   COGL_POLL_FD_EVENT_NVAL = COGL_SYSDEF_POLLNVAL
  73 } CoglPollFDEvent;
  74
  75 /**
  76  * CoglPollFD:
  77  * @fd: The file descriptor to block on
  78  * @events: A bitmask of events to block on
  79  * @revents: A bitmask of returned events
  80  *
  81  * A struct for describing the state of a file descriptor that Cogl
  82  * needs to block on. The @events field contains a bitmask of
  83  * #CoglPollFDEvent<!-- -->s that should cause the application to wake
  84  * up. After the application is woken up from idle it should pass back
  85  * an array of #CoglPollFD<!-- -->s to Cogl and update the @revents
  86  * mask to the actual events that occurred on the file descriptor.
  87  *
  88  * Note that CoglPollFD is deliberately exactly the same as struct
  89  * pollfd on Unix so that it can simply be cast when calling poll.
  90  *
  91  * Since: 1.10
  92  * Stability: unstable
  93  */
  94 typedef struct {
  95   int fd;
  96   short int events;
  97   short int revents;
  98 } CoglPollFD;
  99
 100 /**
 101  * cogl_poll_get_info:
 102  * @context: A #CoglContext
 103  * @poll_fds: A return location for a pointer to an array
 104  *            of #CoglPollFD<!-- -->s
 105  * @n_poll_fds: A return location for the number of entries in *@poll_fds
 106  * @timeout: A return location for the maximum length of time to wait
 107  *           in microseconds, or -1 to wait indefinitely.
 108  *
 109  * This should be called whenever an application is about to go idle
 110  * so that Cogl has a chance to describe what state it needs to be
 111  * woken up on. The assumption is that the application is using a main
 112  * loop with something like the poll function call on Unix or the GLib
 113  * main loop.
 114  *
 115  * After the function is called *@poll_fds will contain a pointer to
 116  * an array of #CoglPollFD structs describing the file descriptors
 117  * that Cogl expects. The fd and events members will be updated
 118  * accordingly. After the application has completed its idle it is
 119  * expected to either update the revents members directly in this
 120  * array or to create a copy of the array and update them
 121  * there. Either way it should pass a pointer to either array back to
 122  * Cogl when calling cogl_poll_dispatch().
 123  *
 124  * When using the %COGL_WINSYS_ID_WGL winsys (where file descriptors
 125  * don't make any sense) or %COGL_WINSYS_ID_SDL (where the event
 126  * handling functions of SDL don't allow blocking on a file
 127  * descriptor) *n_poll_fds is guaranteed to be zero.
 128  *
 129  * @timeout will contain a maximum amount of time to wait in
 130  * microseconds before the application should wake up or -1 if the
 131  * application should wait indefinitely. This can also be 0 zero if
 132  * Cogl needs to be woken up immediately.
 133  *
 134  * Stability: unstable
 135  * Since: 1.10
 136  */
 137 void
 138 cogl_poll_get_info (CoglContext *context,
 139                     CoglPollFD **poll_fds,
 140                     int *n_poll_fds,
 141                     gint64 *timeout);
 142
 143 /**
 144  * cogl_poll_dispatch:
 145  * @context: A #CoglContext
 146  * @poll_fds: An array of #CoglPollFD<!-- -->s describing the events
 147  *            that have occurred since the application went idle.
 148  * @n_poll_fds: The length of the @poll_fds array.
 149  *
 150  * This should be called whenever an application is woken up from
 151  * going idle in its main loop. The @poll_fds array should contain a
 152  * list of file descriptors matched with the events that occurred in
 153  * revents. The events field is ignored. It is safe to pass in extra
 154  * file descriptors that Cogl didn't request from
 155  * cogl_context_begin_idle() or a shorter array missing some file
 156  * descriptors that Cogl requested.
 157  *
 158  * Stability: unstable
 159  * Since: 1.10
 160  */
 161 void
 162 cogl_poll_dispatch (CoglContext *context,
 163                     const CoglPollFD *poll_fds,
 164                     int n_poll_fds);
 165
 166 G_END_DECLS
 167
 168 #endif /* __COGL_POLL_H__ */