include/backends/GP_Backend.h

   1 /*****************************************************************************
   2  * This file is part of gfxprim library.                                     *
   3  *                                                                           *
   4  * Gfxprim is free software; you can redistribute it and/or                  *
   5  * modify it under the terms of the GNU Lesser General Public                *
   6  * License as published by the Free Software Foundation; either              *
   7  * version 2.1 of the License, or (at your option) any later version.        *
   8  *                                                                           *
   9  * Gfxprim is distributed in the hope that it will be useful,                *
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of            *
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU         *
  12  * Lesser General Public License for more details.                           *
  13  *                                                                           *
  14  * You should have received a copy of the GNU Lesser General Public          *
  15  * License along with gfxprim; if not, write to the Free Software            *
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor,                        *
  17  * Boston, MA  02110-1301  USA                                               *
  18  *                                                                           *
  19  * Copyright (C) 2009-2010 Jiri "BlueBear" Dluhos                            *
  20  *                         <jiri.bluebear.dluhos@gmail.com>                  *
  21  *                                                                           *
  22  * Copyright (C) 2009-2013 Cyril Hrubis <metan@ucw.cz>                       *
  23  *                                                                           *
  24  *****************************************************************************/
  25
  26 /*
  27
  28   The GP_Backend is overall structure for API for managing
  29   connection/mmaped memory/... to xserver window/framebuffer/... .
  30
  31   In contrast to other graphics libraries we do not try to create unified
  32   initalization interface that would match specialities for every possible
  33   backend. Rather than that we are trying to create API that is the same
  34   for all backends, once initalization is done.
  35
  36   So once you initalize, for example, framebuffer driver, the GP_Backend
  37   structure is returned, which then could be used with generic code for
  38   backend drawing.
  39
  40  */
  41
  42 #ifndef BACKENDS_GP_BACKEND_H
  43 #define BACKENDS_GP_BACKEND_H
  44
  45 #include "core/GP_Pixmap.h"
  46
  47 #include "input/GP_EventQueue.h"
  48 #include "input/GP_Timer.h"
  49
  50 typedef struct GP_Backend {
  51         /*
  52          * Backend name.
  53          */
  54         const char *name;
  55
  56         /*
  57          * Pointer to pixmap app should draw to.
  58          *
  59          * This MAY change upon a flip operation.
  60          */
  61         GP_Pixmap *pixmap;
  62
  63         /*
  64          * If display is buffered, this copies content
  65          * of pixmap onto display.
  66          *
  67          * If display is not buffered, this is no-op (set to NULL).
  68          */
  69         void (*Flip)(struct GP_Backend *self);
  70
  71         /*
  72          * Updates display rectangle.
  73          *
  74          * In contrast to flip operation, the pixmap
  75          * must not change (this is intended for updating very small areas).
  76          *
  77          * If display is not buffered, this is no-op (set to NULL).
  78          */
  79         void (*UpdateRect)(struct GP_Backend *self,
  80                            GP_Coord x0, GP_Coord y0,
  81                            GP_Coord x1, GP_Coord y1);
  82
  83         /*
  84          * Callback to change attributes.
  85          *
  86          * If w and h are zero, only caption is changed.
  87          *
  88          * If w is set and h is zero, only w is changed and vice versa.
  89          *
  90          * If caption is NULL only w and h are changed.
  91          *
  92          * Use the inline wrappers instead.
  93          */
  94         int (*SetAttributes)(struct GP_Backend *self,
  95                              uint32_t w, uint32_t h,
  96                              const char *caption);
  97
  98         /*
  99          * Resize acknowledge callback. This must be called
 100          * after you got resize event in order to resize
 101          * backend buffers.
 102          */
 103         int (*ResizeAck)(struct GP_Backend *self);
 104
 105         /*
 106          * Exits the backend.
 107          */
 108         void (*Exit)(struct GP_Backend *self);
 109
 110         /*
 111          * Connection fd. Set to -1 if not available
 112          */
 113         int fd;
 114
 115         /*
 116          * Non-blocking event loop.
 117          *
 118          * The events are filled into the event queue see GP_Input.h.
 119          */
 120         void (*Poll)(struct GP_Backend *self);
 121
 122         /*
 123          * Blocking event loop. Blocks until events are ready.
 124          *
 125          * Note that events received by a backend are not necessarily
 126          * translated to input events. So input queue may be empty
 127          * after Wait has returned.
 128          *
 129          * The events are filled into the event queue see GP_Input.h.
 130          */
 131         void (*Wait)(struct GP_Backend *self);
 132
 133         /*
 134          * Queue to store input events.
 135          */
 136         struct GP_EventQueue event_queue;
 137
 138         /*
 139          * Priority queue for timers.
 140          */
 141         struct GP_Timer *timers;
 142
 143         /* Backed private data */
 144         char priv[];
 145 } GP_Backend;
 146
 147 #define GP_BACKEND_PRIV(backend) ((void*)(backend)->priv)
 148
 149 /*
 150  * Calls backend->Flip().
 151  */
 152 void GP_BackendFlip(GP_Backend *backend);
 153
 154 /*
 155  * Calls backend->UpdateRect().
 156  */
 157 void GP_BackendUpdateRectXYXY(GP_Backend *backend,
 158                               GP_Coord x0, GP_Coord y0,
 159                               GP_Coord x1, GP_Coord y1);
 160
 161 static inline void GP_BackendUpdateRect(GP_Backend *backend,
 162                                         GP_Coord x0, GP_Coord y0,
 163                                         GP_Coord x1, GP_Coord y1)
 164 {
 165         return GP_BackendUpdateRectXYXY(backend, x0, y0, x1, y1);
 166 }
 167
 168 static inline void GP_BackendUpdateRectXYWH(GP_Backend *backend,
 169                                             GP_Coord x, GP_Coord y,
 170                                             GP_Size w, GP_Size h)
 171 {
 172         GP_BackendUpdateRectXYXY(backend, x, y, x + w - 1, y + h - 1);
 173 }
 174
 175 /*
 176  * Calls backend->Exit().
 177  */
 178 static inline void GP_BackendExit(GP_Backend *backend)
 179 {
 180         if (backend)
 181                 backend->Exit(backend);
 182 }
 183
 184 /*
 185  * Polls backend, the events are filled into event queue.
 186  */
 187 void GP_BackendPoll(GP_Backend *self);
 188
 189 /*
 190  * Poll and GetEvent combined.
 191  */
 192 int GP_BackendPollEvent(GP_Backend *self, GP_Event *ev);
 193
 194 /*
 195  * Waits for backend events.
 196  */
 197 void GP_BackendWait(GP_Backend *self);
 198
 199 /*
 200  * Wait and GetEvent combined.
 201  */
 202 int GP_BackendWaitEvent(GP_Backend *self, GP_Event *ev);
 203
 204 /*
 205  * Adds timer to backend.
 206  *
 207  * If timer Callback is NULL a timer event is pushed into
 208  * the backend event queue once timer expires.
 209  *
 210  * See input/GP_Timer.h for more information about timers.
 211  */
 212 void GP_BackendAddTimer(GP_Backend *self, GP_Timer *timer);
 213
 214 /*
 215  * Removes timer from backend timer queue.
 216  */
 217 void GP_BackendRemTimer(GP_Backend *self, GP_Timer *timer);
 218
 219 /*
 220  * Returns number of timers scheduled in backend.
 221  */
 222 static inline unsigned int GP_BackendTimersInQueue(GP_Backend *self)
 223 {
 224         return GP_TimerQueueSize(self->timers);
 225 }
 226
 227 /*
 228  * Sets backend caption, if supported.
 229  *
 230  * When setting caption is not possible/implemented non zero is returned.
 231  */
 232 static inline int GP_BackendSetCaption(GP_Backend *backend,
 233                                        const char *caption)
 234 {
 235         if (backend->SetAttributes == NULL)
 236                 return 1;
 237
 238         return backend->SetAttributes(backend, 0, 0, caption);
 239 }
 240
 241 /*
 242  * Resize backend, if supported.
 243  *
 244  * When resizing is not possible/implemented non zero is returned.
 245  *
 246  * When the backend size matches the passed width and height,
 247  * no action is done.
 248  *
 249  * Note that after calling this, the backend->pixmap pointer may change.
 250  */
 251 int GP_BackendResize(GP_Backend *backend, uint32_t w, uint32_t h);
 252
 253
 254 /*
 255  * Resize acknowledge. You must call this right after you application has
 256  * received resize event.
 257  *
 258  * This will resize backend buffers. After this call returns the backend width
 259  * height and pixmap pointer are most likely different.
 260  *
 261  * This function returns zero on succes. Non zero on failure. If it fails the
 262  * best action to take is to save application data and exit (as the backend
 263  * may be in undefined state).
 264  */
 265 int GP_BackendResizeAck(GP_Backend *self);
 266
 267 /*
 268  * Event Queue functions.
 269  */
 270 static inline unsigned int GP_BackendEventsQueued(GP_Backend *self)
 271 {
 272         return GP_EventQueueEventsQueued(&self->event_queue);
 273 }
 274
 275 static inline int GP_BackendGetEvent(GP_Backend *self, GP_Event *ev)
 276 {
 277         return GP_EventQueueGet(&self->event_queue, ev);
 278 }
 279
 280 static inline int GP_BackendPeekEvent(GP_Backend *self, GP_Event *ev)
 281 {
 282         return GP_EventQueuePeek(&self->event_queue, ev);
 283 }
 284
 285 static inline void GP_BackendPutEventBack(GP_Backend *self, GP_Event *ev)
 286 {
 287         GP_EventQueuePutBack(&self->event_queue, ev);
 288 }
 289
 290 #endif /* BACKENDS_GP_BACKEND_H */