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 initalization interface each backend has it's specific function and sematics
   7 but once backend is initalized the backend structure provides unified API for
   8 controling the drawing.
   9
  10 So far there are three backends implemented, linux mmaped framebuffer, libSDL
  11 and X11 backend.
  12
  13 Initalization functions
  14 ~~~~~~~~~~~~~~~~~~~~~~~
  15
  16 [source,c]
  17 -------------------------------------------------------------------------------
  18 GP_Backend *GP_BackendLinuxFBInit(const char *path);
  19 -------------------------------------------------------------------------------
  20
  21 Initalizes mmaped framebuffer backend. The path is path to the framebuffer
  22 device ie. '/dev/fbX'. This backend is not buffered, everything you draw
  23 appears on the screen right away (an swich may be added for that purpose).
  24
  25 Also note that this backend doesn't initalize any input driver. You need to
  26 initalize input driver in order to get keystrokes and/or pointer events.
  27
  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 Initalize SDL as an backend driver. The backend is thread safe as all the
  42 operations are guarded by locks. You can't initalize more than one backend at a
  43 time, that is inherited SDL limiation. If you call the initalizaiton for a
  44 second time, you will get a pointer to allready running backend. This driver
  45 feeds input events into global input event queue (see input docs for details).
  46 If w, h and/or bpp are zero SDL tries to do a guess, most of the time wrong for
  47 w and h though. The caption is window caption and may be ignored for some of
  48 the backends. And finally flags may change the SDL to go to fullscreen mode or
  49 make the window resizeable.
  50
  51 [source,c]
  52 -------------------------------------------------------------------------------
  53 GP_Backend *GP_BackendX11Init(const char *display, int x, int y,
  54                               unsigned int w, unsigned int h,
  55                               const char *caption);
  56 -------------------------------------------------------------------------------
  57
  58 Returns pointer to backend. When display is NULL default display is used
  59 (which is what you want most of the time). This backend feeds key events into
  60 global input queue (pointer events not implemented yet). Note this is
  61 experimental version of X11 backend and will be changed to support more
  62 windows at a time.
  63
  64
  65 Overall init function
  66 ~~~~~~~~~~~~~~~~~~~~~
  67
  68 Althoug there is no unified backend initalization, there is something close to
  69 it.
  70
  71 [source,c]
  72 -------------------------------------------------------------------------------
  73 #include <GP.h>
  74
  75 GP_Backend *GP_BackendInit(const char *params, const char *caption, FILE *help);
  76 -------------------------------------------------------------------------------
  77
  78 This function takes a params string as an parameter which is used for
  79 determining backend-dependend parametrs. The format is
  80 'backend_name:backend_parameters' where backend parameters may be window size
  81 (either 'WxH' or 'FS' in case of SDL backend). The caption is window caption
  82 (which is ignored in some of the cases) and the 'FILE' is file, where an error
  83 is printed in case of failure, you should mostly use 'stderr' for that
  84 purpose. If params is set to 'NULL' the the call only prints help into the
  85 passed help 'FILE'. If intitalizaton was succesfull pointer to allocated and
  86 initalized backend is returned otherwise 'NULL' is returned and some helpful
  87 infomation should be printed into the passed help 'FILE'.
  88
  89
  90 Drawing Backend API
  91 ~~~~~~~~~~~~~~~~~~~
  92
  93 The drawing backend API consist of structure with callbacks. Every backend
  94 initalization yields pointer to this structure. Although is possible to call
  95 these pointers directly it's not recomended and everbody should rather use
  96 backend inline functions instead.
  97
  98 The backend API consist of several functions:
  99
 100 [source,c]
 101 -------------------------------------------------------------------------------
 102 void GP_BackendExit(GP_Backend *backend);
 103 -------------------------------------------------------------------------------
 104
 105 Calls an backend exit callback.
 106
 107 [source,c]
 108 -------------------------------------------------------------------------------
 109 GP_BackendFlip(GP_Backend *backend);
 110 -------------------------------------------------------------------------------
 111
 112 Flips a screen. Updates rect for a buffered backends.
 113
 114 [source,c]
 115 -------------------------------------------------------------------------------
 116 void GP_BackendUpdateRect(GP_Backend *backend,
 117                           GP_Coord x0, GP_Coord y0,
 118                           GP_Coord x1, GP_Coord y1);
 119 -------------------------------------------------------------------------------
 120
 121 Updates particular rectangle for a buffered backends.
 122
 123 [source,c]
 124 -------------------------------------------------------------------------------
 125 void GP_BackendPoll(GP_Backend *backend);
 126 -------------------------------------------------------------------------------
 127
 128 Polls for backend events. For backends that do not expose file descriptor
 129 (namely SDL) this should be called repeatedly. For other backend it may be
 130 called either repeatedly or when data are ready on filedescriptor.