doc/backends.txt

   1 Drawing Backends
   2 ----------------
   3
   4 Drawing backends provide means to draw into computer screen or into an window
   5 inside of running operating system. Instead of having one unified
   6 initialization interface each backend has it's specific function and semantics
   7 but once backend is initialized the backend structure provides unified API for
   8 controlling the drawing.
   9
  10 So far there are three backends implemented, Linux mmaped frame-buffer, libSDL
  11 and X11 backend.
  12
  13 Initialization functions
  14 ~~~~~~~~~~~~~~~~~~~~~~~
  15
  16 [source,c]
  17 -------------------------------------------------------------------------------
  18 GP_Backend *GP_BackendLinuxFBInit(const char *path, int flag);
  19 -------------------------------------------------------------------------------
  20
  21 Initializes mmaped frame-buffer backend. The path is path to the frame-buffer
  22 device i.e. '/dev/fbX'. This backend is not buffered, everything you draw
  23 appears on the screen right away (an switch may be added for that purpose).
  24
  25 If flag is set console KBD driver is used to feed keystrokes into the event
  26 queue, otherwise no events are generated and you are expected to initialize
  27 input event driver in order to get keystrokes and/or pointer events.
  28
  29 [source,c]
  30 -------------------------------------------------------------------------------
  31 enum GP_BackendSDLFlags {
  32         GP_SDL_FULLSCREEN = 0x01,
  33         GP_SDL_RESIZABLE  = 0x02,
  34 };
  35
  36 GP_Backend *GP_BackendSDLInit(GP_Size w, GP_Size h,
  37                               uint8_t bpp, uint8_t flags,
  38                               const char *caption);
  39 -------------------------------------------------------------------------------
  40
  41 Initialize SDL as an backend driver. The backend is thread safe as all the
  42 operations are guarded by locks.
  43
  44 You can't initialize more than one backend at a time, which is inherited SDL
  45 limitation. If you call the initialization for a second time, you will get a
  46 pointer to already running backend.
  47
  48 This driver feeds input events into global input event queue (see input docs
  49 for details).
  50
  51 If w, h and/or bpp are zero SDL tries to do a guess, most of the time wrong
  52 for w and h though.
  53
  54 The caption is window caption.
  55
  56 And finally flags may change the SDL to go to full-screen mode or make the
  57 window resizable.
  58
  59 [source,c]
  60 -------------------------------------------------------------------------------
  61 enum GP_BackendX11Flags {
  62         /*
  63          * When set, w and h is ignored and root window is used
  64          */
  65         GP_X11_USE_ROOT_WIN = 0x01,
  66 };
  67
  68 GP_Backend *GP_BackendX11Init(const char *display, int x, int y,
  69                               unsigned int w, unsigned int h,
  70                               const char *caption,
  71                               enum GP_BackendX11Flags flags);
  72 -------------------------------------------------------------------------------
  73
  74 Returns pointer to initialized X11 backend or in case of failure NULL.
  75
  76 When display is NULL default display is used (which is what you want most of the
  77 time).
  78
  79 This backend feeds key events into global input queue.
  80
  81 Note this is experimental version of X11 backend and will be changed to support
  82 more windows at a time.
  83
  84 Overall init function
  85 ~~~~~~~~~~~~~~~~~~~~~
  86
  87 Although there is no unified backend initialization, there is something close to
  88 it.
  89
  90 [source,c]
  91 -------------------------------------------------------------------------------
  92 #include <GP.h>
  93
  94 GP_Backend *GP_BackendInit(const char *params, const char *caption, FILE *help);
  95 -------------------------------------------------------------------------------
  96
  97 This function takes a params string as an parameter which is used for
  98 determining backend-dependent parameters. The format is
  99 'backend_name:backend_parameters' where backend parameters may be window size
 100 (either 'WxH' or 'FS' in case of SDL backend). The caption is window caption
 101 (which is ignored in some of the cases) and the 'FILE' is file, where an error
 102 is printed in case of failure, you should mostly use 'stderr' for that
 103 purpose. If params is set to 'NULL' the the call only prints help into the
 104 passed help 'FILE'. If initialization was successful pointer to allocated and
 105 initialized backend is returned otherwise 'NULL' is returned and some helpful
 106 information should be printed into the passed help 'FILE'.
 107
 108
 109 Drawing Backend API
 110 ~~~~~~~~~~~~~~~~~~~
 111
 112 The drawing backend API consist of structure with callbacks. Every backend
 113 initialization yields pointer to this structure. Although is possible to call
 114 these pointers directly it's not recommended and everybody should rather use
 115 backend inline functions instead.
 116
 117 The backend API consist GP_Backend structure and of several functions:
 118
 119 [source,c]
 120 -------------------------------------------------------------------------------
 121 typdef struct GP_Backend {
 122         /*
 123          * Backend name.
 124          */
 125         const char *name;
 126
 127         /*
 128          * Pointer to context app should draw to.
 129          */
 130         GP_Context *context;
 131
 132         ...
 133
 134         /*
 135          * Connection fd. Set to -1 if not available
 136          */
 137         int fd;
 138 };
 139 -------------------------------------------------------------------------------
 140
 141 [source,c]
 142 -------------------------------------------------------------------------------
 143 void GP_BackendExit(GP_Backend *backend);
 144 -------------------------------------------------------------------------------
 145
 146 Calls an backend exit callback.
 147
 148 [source,c]
 149 -------------------------------------------------------------------------------
 150 GP_BackendFlip(GP_Backend *backend);
 151 -------------------------------------------------------------------------------
 152
 153 Flips a screen. Updates rectangle for a buffered backends.
 154
 155 [source,c]
 156 -------------------------------------------------------------------------------
 157 void GP_BackendUpdateRect(GP_Backend *backend,
 158                           GP_Coord x0, GP_Coord y0,
 159                           GP_Coord x1, GP_Coord y1);
 160 -------------------------------------------------------------------------------
 161
 162 Updates particular rectangle for a buffered backends.
 163
 164 [source,c]
 165 -------------------------------------------------------------------------------
 166 void GP_BackendPoll(GP_Backend *backend);
 167 -------------------------------------------------------------------------------
 168
 169 Polls for backend events. For backends that do not expose file descriptor
 170 (namely SDL) this should be called repeatedly. For other backend it may be
 171 called either repeatedly or when data are ready on file-descriptor.
 172
 173 [source,c]
 174 -------------------------------------------------------------------------------
 175 int GP_BackendSetCaption(GP_Backend *backend, const char *caption)
 176 -------------------------------------------------------------------------------
 177
 178 Sets backend caption. On success zero is returned. On failure (backend doesn't
 179 support caption, operation failed) non zero is returned.
 180
 181 [source,c]
 182 -------------------------------------------------------------------------------
 183 int GP_BackendResize(GP_Backend *backend, uint32_t w, uint32_t h);
 184 -------------------------------------------------------------------------------
 185
 186 Resize backend, if supported. On success zero is returned and backend is
 187 resized, otherwise (if resize failed, or is not supported) non-zero is
 188 returned. If backend size already matches w and h, nothing is done.
 189
 190 Note that backend->context pointer may change upon calling this function and
 191 at least backend->context->pixels pointer will change.